dte 0.3.2

Date Time Expressions

Date Time Expression

dte is a WIP date-time processing language with focus on broad interpretation.

If you don't think it's intuitive, it's most likely unfinished.

It is strongly inspired by pdd.

How to use & What to know

pip install dte

Conventions

• When there is margin for ambiguity, expressions are always interpreted with highest units appearing before, complying with ISO-8601, e.g.: 2021-06-13, 2023 August 27 or 2019 Jul 20
• Unix timestamps are both interpreted and output in seconds by default, but this is configurable
• When specifying time, just remember that M is for month and m is for minute

Configuration File

dte tries to read a config.json file under config directory (~/.config/dte/ on Linux). In it you can set the following options:

{
  "timestamp_unit": "<seconds|milliseconds>"
  "clock": "<24|12>",
  "datetime_output_format": "<ISO8601|<format>>",
  "comparison_tolerance_seconds": <float>,
  "basedate_output_format": "%Y-%b",
  "decimal_places": <integer>
}

Dependencies

• dateutil handles month and year's complex operations
• ply is a pure-Python implementation of the popular compiler construction tools lex and yacc
• appdirs for reading config file in a cross-platform manner

To do

• format(timepoint, fmt) (in keyword) units given current time field
• add custom/OS locale support (?)
• add tab-completion for:
  • months
  • units given current datetime field or RHS of in keyword
• "days until winter"
• run tests across a variety of locales
• add show function
  • show clock for time
  • show cal for date and basedate

Examples

The following examples are generated based on tests run, so many results will be relative to the day it was tested. Every expression on the left side is valid syntax.

INPUT	OUTPUT
jan 1 + 99999M	8334-04-01
1970 january 1st	1970-01-01
day 13 friday in 2021	2021-08-13
friday day < 8 in Jan 2015	2015-01-02
friday day 13 in August 2021.weekday	Friday
friday day 13 in August 2021	2021-08-13
2020-01-29 + (1 year + 1 month)	2021-02-28
days until Jan 2030	2936.18
last sun in 2021	2021-12-26
april+1M	2022-05-01
t+1d 08h30	2021-12-18 08:30:00
1am t == t 1am	True
1am t	2021-12-17 01:00:00
(2020-10-10+1d) 3pm	2020-10-11 15:00:00
t 1:00 == t 1am	True
t 1:00	2021-12-17 01:00:00
t 1am	2021-12-17 01:00:00
august	2021-Aug
4th wed in august	2021-08-25
5th sunday in 2021	2021-01-31
4th sunday in 2021	2021-01-24
3rd sunday in 2021	2021-01-17
2nd sunday in 2021	2021-01-10
-1d + 2020-10-10	2020-10-09
2014 Jan + 1M	2014-02-01
Jan 2014 + 1M	2014-02-01
seconds in 24h	86400.00
today==mon	False
days until mon	2.18
days until next mon	2.18
next mon + 1d	2021-12-21
monday+1d	2021-12-21
weekday t+100d	Sunday
(weekday t+100d)==100d.weekday	True
(weekday t+100d)	Sunday
weekday tm	Saturday
yesterday==thu	True
yesterday==thursday	True
last fri in Dec 2014	2014-12-26
last fri in 2014 Dec	2014-12-26
last fri in 2014 December	2014-12-26
days until 2030-12-25	3294.18
6pm+1h	19:00:00
2014 01	2014-Jan
1st friday in april	2022-04-01
first friday in april	2022-04-01
1st friday in next month	2022-01-07
first friday in next month	2022-01-07
next month	2022-01-01
seconds until 11 pm	11736.53
seconds until tomorrow	15336.45
1996 August 28 9 AM	1996-08-28 09:00:00
2s2s	0:00:04
1 hour in seconds	3600.00
1h in seconds	3600.00
5m+5m	0:10:00
1957-12-26 22:22:22 in unix	-379118258
yd-5h	2021-12-15 19:00:00
1st sun in April 2021	2021-04-04
first sun in April 2021	2021-04-04
1st friday in April 2014	2014-04-04
first friday in April 2014	2014-04-04
Jan 2014	2014-Jan
weekday 0	Wednesday
wait until (n+.001s)	``
wait .001s	``
t - next Sunday	-2 days, 0:00:00
2012-12-13-3y.weekday	Sunday
1st sunday in 2021	2021-01-03
first sunday in 2021	2021-01-03
last sunday in 2021	2021-12-26
last Sunday != next sunday	True
last Sunday == next sunday	False
next Sunday != last sunday	True
next Sunday == last sunday	False
seconds since 3000 Apr 10	-30872463334.53
seconds until 3000 Apr 10	30872463334.45
2000-10-10 16:00	2000-10-10 16:00:00
2000-10-10 00:16	2000-10-10 00:16:00
next Sunday	2021-12-19
n	2021-12-17 19:44:25.868383
YD.day	16
T.weekday	Friday
T.day	17
T-10d	2021-12-07
T-1.5d	2021-12-15 12:00:00
3M	3 months
3h+3M	3 months, 3:00:00
2h2m	2:02:00
7y6M5w4d3h2m1.1s	7 years, 6 months, 39 days, 3:02:01
1M1d	1 month, 1 day, 0:00:00
-1y2M	-1 year, -2 months
0y2M	2 months
1y2M	1 year, 2 months
6y5M4d3h2m1s	6 years, 5 months, 4 days, 3:02:01
22h22m	22:22:00
22h+2m	22:02:00
12h:00 pm != 12h:00 am	True
2 < 1	False
2020 Jan 27 + 1y == 2021 Jan 27	True
1w	7 days, 0:00:00
1970 Jan 1 - 3h in unix	0
1d1m in hours	24.02
1d+0h22m	1 day, 0:22:00
1d	1 day, 0:00:00
1d in seconds	86400.00
1d in minutes	1440.00
1d in hours	24.00
1958-05-14 - 1958-05-16	-2 days, 0:00:00
1957-12-26 22:22:22 - t	-23367 days, 22:22:22
1957-12-26 - t	-23367 days, 0:00:00
2014 Jan 13==2014 January 13	True
12h:00 AM != 12h:00 PM	True
1610494238.weekday	Tuesday
1610494238+4h.weekday	Wednesday
1610494238	2021-01-12 20:30:38
1-1-1-1-1-1	0:00:00
22m:22 + 4h	4:22:22
6pm	18:00:00
6 pm + 1h	19:00:00
6 pm	18:00:00
2020-Jan-27	2020-01-27
22:22:22	22:22:22
22:22:22s	22:22:22
22h:22:22s	22:22:22
22:22m:22s	22:22:22
22h:22m:22s	22:22:22
22h:22m:22	22:22:22
22h:22	22:22:00
1996.04.28	1996-04-28
2014 January 13	2014-01-13
2014 Jan 13	2014-01-13
11:20s PM	00:11:20
11h:20m pm	23:20:00
11h:20 am	11:20:00
11m:20 PM	00:11:20
11h:20 AM	11:20:00
1-1-1 23:23S	0001-01-01 00:23:23
1-1-1 23m:23S	0001-01-01 00:23:23
1-1-1 23m:23s	0001-01-01 00:23:23
1-1-1 23m:23	0001-01-01 00:23:23
1-1-1 23h:23m	0001-01-01 23:23:00
1-1-1 23h:23	0001-01-01 23:23:00
1-1-1 23:23m	0001-01-01 23:23:00
1-1-1 23:23:23	0001-01-01 23:23:23
seconds until 2021 feb 14 12:00:00	-26466270.99
2021 feb 14 12:00:00	2021-02-14 12:00:00
10h30 + 14h	1 day, 0:30:00
n - 1234	18978 days, 22:23:57.238947
1m in hours	0.02
1 in unix	1
08h30	8:30:00
-1d.weekday	Thursday
(t + 180d)-180d == t	True
(n + 181d)-180d != n	True
(n + 180d)-180d == n	True
(T-1d).weekday	Thursday