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`
  - (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](https://pypi.org/project/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](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) (like `Europe/Sofia`),
    - [UTC time offset](https://en.wikipedia.org/wiki/List_of_UTC_time_offsets) (with colon `:` or not like `+02:00` or `+0530`), or
    - [abbreviation](https://en.wikipedia.org/wiki/List_of_time_zone_abbreviations) (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](https://github.com/seatgeek/fuzzywuzzy). In case it can't find the country or city, it uses [geopy](https://geopy.readthedocs.io/en/stable/) for location resolution. Finally it uses [timezonefinder](https://pypi.org/project/timezonefinder/) for timezone resolution.

* `--format` is the format of the time to be displayed. See supported [datetime formats](https://docs.python.org/3/library/datetime.html#strftime-strptime-behavior)

## 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](https://www.worldatlas.com/articles/names-of-countries-in-their-own-languages.html), [list of countries in various languages](https://en.wikipedia.org/wiki/List_of_country_names_in_various_languages_(A%E2%80%93C))