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] [--show=<param>]

• The param --full shows the full solutions that parsers came up with.
• You can use --show=<param> to show a particular json entry from the default solution, separated by ->. For example:
  • tww now --show="dt->locale_dt": Thu 13 May 2021 11:26:02 AM CET
  • tww 17:00 --show="dt->emoji_time": 🕔
  • tww time until Christmas --show="timedelta->diff->duration_machine": 0 years, 225 days, 12:30:33

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
• Timezone difference: timezone difference between <tz-like> and <tz-like> or tz diff between <tz-like> and <tz-like>
  • timezone difference between sofia and portugal
• Calculate time differences: <dt-like> (?\+|\-|plus|minus) <timedelta> or <timedelta> (before|from) <dt>
  • 12-12-2019 + 2 weeks
  • 05:23 - 150 minutes
  • 3 days from next Friday
  • 2 hours before 15:00
• Time conversion: * (years|months|weeks|days|hours|minutes|seconds) to (years|months|weeks|days|hours|minutes|seconds)
  • 108 hours to minutes
  • 314 minutes (implicit conversion to automatic human-friendly output)
• (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
• Day of the week
  • what day is today
  • 2021-05-10 day of week
• Find timezones
  • timezone in Brazil
• Print calendar cal(endar) (month) <dt-like> or cal year <dt-like> (for whole year)
  • cal year 2021
  • calendar january 2018

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

• Return Time range

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