Find difference between dates and times
Project description
dtcalc
A command line tool to find the difference between dates.
The package is self-contained and all it needs to run is a recent Python implementation.
Why
I've known people who would've liked to have a way to quickly do basic arithmetic on datetime values. For reasons like:
- How many days would have passed by this June since my birthday?
- How long is it till my friend's wedding anniversary?
- Did the telecom company did their math right? Does my balance expire a few days before it should have?
- Raised a ticket in a support portal. Issue is supposed to be resolved within 12 days. Okay, when is that?
Installation
dtcalc can installed from PyPI.
pip install dtcalc
Python>=3.7 is needed.
Usage
python3 -m dtcalc [--in-dtfmt INDTFMT] [--out-dtfmt OUTDTFMT] INPUT
Or if you got an alias like alias dtcal='python3 -m dtcalc'
,
dtcalc [--in-dtfmt INDTFMT] [--out-dtfmt OUTDTFMT] INPUT
Example usages
$ dtcalc "3d + (2021-11-04 - 2021-11-06)" --in-dtfmt "%Y-%m-%d"
1 days
$ dtcalc "2021/02/11 - 2021/01/11"
4 weeks, 3 days
$ dtcalc "3d (2021-11-04 11:30 - 2021-11-04 10:30)" --in-dtfmt "%Y-%m-%d %H:%M"m dtc
1 hours
$ dtcal --out-dtfmt "%B %d, %Y" "2021/04/11 + 22w"
September 12, 2021
$ dtcal --out-dtfmt "%B %d, %Y" "2021/04/11 - 2020/11/12 +2d + 3w + 4h + 2m"
24 weeks, 5 days, 4 hours, 2 minutes
Datetime values
The default input and output datetime value format is "%Y/%m/%d"
(as in 2021/11/14
)
Most format codes mentioned here except %Z
can be used. The format codes are mentioned at the end of this README.
The default datetime format can be changed with the following options:
--in-dtfmt
: for input datetime format--out-dtfmt
: for output datetime format
--out-dtfmt
has effect only if the result is a datetime value. If it is an offset value instead, it will be printed in a preset format (I hope to work on that).
Changing datetime format
Input and output datetime formats can be changed using --in-dtfmt
and --out-dtfmt
respectively.
Output format is effective only if result is a datetime. If result is an offset, output format is ignored.
Datetime offsets
Following units can be used to create datetime offset values:
- w: weeks
- d: days
- h: hours
- m: minutes
These units together with an integer (scaling value) produces an offset value. Like:
2d
: 2 days53w
: 53 weeks23w
: 23 hours351
: 351 minutes
Only integers can be used. Float values would throw error. Operators can be used to combine different units instead.
Note that there shouldn't be any space between the integer and the unit. So,
2d
,32w
,451h
are correct.2 d
,32 w
are wrong.
Some other units like years and months are not included as their time duration can vary (eg: due to leap years).
Operations
Addition and subtraction of datetime values are supported.
(2021/11/04 - 2021/11/05)
Datetime offset values can be combined with operators like:
3w + 2d
: 3 weeks and 2 days
There can be any number of spaces (including none) between operators (ie, +
or -
) and values (ie, offsets or datetime). So all of the following are okay.
3w +2d
3w+ 2d
3w+2d
Grouping operations
Operations may also be grouped together using parenthesis (as a way to specify precedence explicit).
Like:
3d + (2021/11/04 - 2021/11/05)
- Evaluated as:
3d + (-1d)
→2d
- Command:
dtcalc "3d + (2021/11/04 - 2021/11/05)"
- Evaluated as:
Evaluation happens one by one from left to right.
Needless to say, the parentheses should match. Every opening parenthesis must have a matching closing parenthesis coming after it.
Caveats
Negation of datetime value
Unary negation of a datetime value would result in an error. Like:
- 2021/04/28
3d - 2021/04/28
because it doesn't make sense to have a negative time.
But subtracting a datetime from another datetime is fine:
2021/05/29 - 2021/05/28 # 1 day
Addtion of two datetime values
Since it doesn't make much sense to add datetimes , addition of two datetime values would throw error. Like:
Datetime format codes
The actual value of some of the format codes are locale-dependent. Examples are as per en_US
locale.
d
: Day of month as zero padded integer (eg: 12)f
: Millisecond as zero padded integer (eg: 012345)H
: Hour (24-hour clock format) as zero padded integer (eg: 22)I
: Hour (12-hour clock format) as zero padded integer (eg: 10)j
: Day of year as zero padded integer (eg: 012)m
: Month as zero padded integer (eg: 02)M
: Minute as zero padded integer (eg: 59)S
: Second as zero padded integer (eg: 59)U
: Week number of year (with Sunday as first day) as zero padded integer (eg: 51)w
: Week day as integer (Sunday is 0)y
: Year without century as zero padded integer (eg: 21)Y
: Year with century (eg: 2021)z
: UTC offset (eg: +0530, -0200)A
: Full weekday name (locale dependent) (eg: Sunday)a
: Abbreviated weekday name (locale dependent) (eg: Sun)B
: Full month name (locale dependent) (eg: January)b
: Abbreviated month name (locale dependent) (eg: Jan)p
: AM/PM%
: literal '%'. Used as escape.
Contribute
This package was hastily put-together as part of an event and as a result almost certainly has got bugs. If you spot any, please tell me about it. :)
Todo
- Add seconds as a unit.
- Notations for today (date only value) and now (datetime value).
- Allow compound offsets.
- 2w4d5h: 2 weeks 4 days 5 hours
- Till next Friday / January.
- Change output format.
- Add logger.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.