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	2401.04
last sun in 2021	2021-12-26
april+1M	2023-05-01
t+1d 08h30	2023-06-06 08:30:00
1am t == t 1am	True
1am t	2023-06-05 01:00:00
(2020-10-10+1d) 3pm	2020-10-11 15:00:00
t 1:00 == t 1am	True
t 1:00	2023-06-05 01:00:00
t 1am	2023-06-05 01:00:00
august	2023-Aug
4th wed in august	2023-08-23
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	True
days until mon	-0.96
days until next mon	6.04
next mon + 1d	2023-06-13
monday+1d	2023-05-30
weekday t+100d	Wednesday
(weekday t+100d)==100d.weekday	True
(weekday t+100d)	Wednesday
weekday tm	Tuesday
yesterday==thu	False
yesterday==thursday	False
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	2759.04
6pm+1h	19:00:00
2014 01	2014-Jan
1st friday in april	2023-04-07
first friday in april	2023-04-07
1st friday in next month	2023-07-07
first friday in next month	2023-07-07
next month	2023-07-01
seconds until 11 pm	85931.98
seconds until tomorrow	3131.80
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	2023-06-03 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	-6 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	-30826227127.30
seconds until 3000 Apr 10	30826227127.12
2000-10-10 16:00	2000-10-10 16:00:00
2000-10-10 00:16	2000-10-10 00:16:00
next Sunday	2023-06-11
n	2023-06-05 23:07:53.607236
YD.day	4
T.weekday	Monday
T.day	5
T-10d	2023-05-26
T-1.5d	2023-06-03 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	-23902 days, 22:22:22
1957-12-26 - t	-23902 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	-72702485.53
2021 feb 14 12:00:00	2021-02-14 12:00:00
10h30 + 14h	1 day, 0:30:00
n - 1234	19514 days, 1:47:32.086022
1m in hours	0.02
1 in unix	1
08h30	8:30:00
-1d.weekday	Sunday
(t + 180d)-180d == t	True
(n + 181d)-180d != n	True
(n + 180d)-180d == n	True
(T-1d).weekday	Sunday