tww/README.md

Time when and where

Find time now, in the past or future in any timezone or location.

Usage

python tww QUERY [--debug] [--full]

• Supported QUERY types:
  • Just time: <datetime-like>:
    • now
    • in 5 hours
    • 5 January 2012
    • 4:26 PM
    • April 2020
  • Timezone translation <datetime-like> in <timezone/location> to <destination timezone/location> or <datetime-like> to <timezone/location> (assumes datetime is local)
    • 04:26 in japan to local
    • 03:14 in local to IST
    • 15:20 to America/New_York
    • 2021-12-25 12:00 in Brazil
  • Time difference: (time) between <datetime-like> and <datetime-like> or (time) since <datetime-like or (time) until <datetime-like>
    • time between 2012-03-14 and 2012-04-26
    • time since 09:00
    • time until end of workday
  • (Approximate) workdays calculation (assumes monday-friday are work days - ignores public/local holidays (for now)): work days/hours since/until <datetime-like> or `
    • workdays since 2021-01-05
    • work hours until Friday
  • Milliseconds since epoch: (time/(milli)seconds) since epoch or datetime to epoch: <datetime-like> to epoch or (milli)seconds since <datetime-like>/epoch
    • 2021-01:01 to epoch
    • milliseconds since epoch

Few more notes:

• <datetime-like> is any time or time-like string - or example:

  • 2019-04-26 3:14, 06:42 27 January 1992,
  • some human readable like now, in 3 hours, 7 minutes ago and many others.
  • See dateparser for more.
  • custom date-times (like christmas, new years, end of workday) defined in data/custom_dt.csv

• <timezone/location> is either:

  • timezone (tried first) - it can be:
    • tz database name (like Europe/Sofia),
    • UTC time offset (with colon : or not like +02:00 or +0530), or
    • abbreviation (like UTC, CET, PST - however please note that these are not unique and resolution might wrong)
  • a location. Uses a local database of files of countries and cities. It then tries to fuzzymatch the query using fuzzywuzzy. In case it can't find the country or city, it uses geopy for location resolution. Finally it uses timezonefinder for timezone resolution.

• --format is the format of the time to be displayed. See supported datetime formats

Install

virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt

You could alias the whole command to tww for faster typing, e.g. in your .bashrc:

alias tww="~/workspace/tww/venv/bin/python ~/workspace/tww/main.py"

More Examples

Time now (in this timezone):

$ tww now
2019-03-13 15:04:36

Time now to another timezone (UTC let's say):

$ tww now to utc
2019-03-13 15:04:36

One hour from now in UTC, showing only the time:

$ tww in 1 hour to cet --format="%T"
23:17:49

With timezone:

$ tww now to asia/tokyo
2019-03-14 07:06:35

Another time to timezone:

$ tww 15:10 to cet
2019-03-13 23:10:00

Time in one timezone (pst) to another in city:

$ tww 3/14 15 9:26:53 PST to sofia
2015-03-14 19:26:53+02:00

TODO

• Calculate time differences:

  • parse timedelta:
    • (%d) (?year|month|week|day|hour|minute|second)[s]?
  • calculate:
    • <dt-like> (?\+|\-|plus|minus) <timedelta>
      • 12-12-2019 + 2 weeks
      • 05:23 - 150 minutes
    • <timedelta> (before|from) <dt>
      • 3 days from next Friday
      • 2 hours before 15:00

• Day of the week

  • what day is <dt>

• Return Time range

  • parse relative to now:
    • (previous|last|this|next) (year|month|week|day|hour|minute|second|Monday|Tuesday|...|Sunday)

• Countries names in their own languages, list of countries in various languages