superdate
SuperDate: A super easy to use date parsing library.
Building and installation
Available from PyPi; Just pip3 install superdate
Alternatively, clone this repo and then pip3 install.
pip3 install .
Usage
superdate contains two main components; the parse_date function and SuperDate class.
The parse_date function allows for super intuitive date parsing, while the SuperDate class overloads comparison operators to allow for intuitive date comparisions against strings or date / datetime objects.
parse_date
The parse_date function parses dates from strings. These can be plain iso strings or colloquial English strings. Plain English strings are parsed with down to second precision using the parsedatetime library.
If a time was detected, then a datetime will be returned. If no time information was detected then a date object will be returned. A datetime can be forced to return with force_time=True.
The difference between this function and vanilla parsedatetime is a cache. Dates parsed from Non-ISO strings are cached for faster lookup. This cache clears if a new second has ticked over since the previous call.
# Some examples. Logged on February 26th 2023.
>>> from superdate import parse_date
>>> parse_date('1970-1-1')
datetime.date(1970, 1, 1)
>>> parse_date('today')
datetime.date(2023, 2, 26)
# Force a time
>>> parse_date('today', force_time=True)
datetime.datetime(2023, 2, 26, 9, 0)
>>> parse_date('now')
datetime.datetime(2023, 2, 26, 14, 32)
>>> parse_date('saturday')
datetime.date(2023, 3, 4)
>>> parse_date('saturday at noon')
datetime.datetime(2023, 3, 4, 12, 0)
>>> parse_date('January')
datetime.date(2024, 1, 1)
SuperDate
The SuperDate class wraps the parse_date function, but overloads all comparison operators to allow for more intuitive plain-english comparisons.
Comparisons between dates and datetimes will ignore the time. This is because a very common use case is, for example, a user who asks “what appointments are on Wednesday?”
[a for a in appointments if a.date == 'Wednesday']
Typically “Wednesday” would include hour 0, minute 0, and second 0, which isn’t technically equivalent to an appointment at 4pm. Obviously this user wants to see all their appointments on Wednesday, so the time for each appointment will be ignored when comparing against a plain date.
# Some examples
from superdate import SuperDate
SuperDate('Wednesday') == 'Wednesday' # => True
SuperDate('Wednesday') < 'Wednesday 4pm' # => False
SuperDate('Wednesday') == 'Wednesday 4pm' # => True
SuperDate('Wednesday at noon') < 'Wednesday 4pm' # => True
# Will evaluate to True because we forced a time.
SuperDate('Wednesday', force_time=True) < 'Wednesday 4pm' # => True
All dot operators (.hour .day .strftime etc…) are forwarded to the underlying python3 standard date / datetime object, so this class should be usable anywhere a regular datetime is.
Maintenance and versioning
Update the CHANGELOG and version in pyproject.toml when cutting a release.
Build with python3 -m build and use twine upload -r pypi dist/* to upload to pypi.
Metadata
Release files for superdate 0.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| superdate-0.2.2.tar.gz | 12.0 kB | Without provenance | Details for superdate-0.2.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| superdate-0.2.2-py3-none-any.whl | Python 3 | none | any | Details for superdate-0.2.2-py3-none-any.whl |
Total release size: 24.3 kB
Release files / superdate-0.2.2.tar.gz
| Download URL | superdate-0.2.2.tar.gz |
|---|---|
| Size | 12.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e61942a4caf2c500fc938bd726d001858905e5257bb0f90f17a49706735b79d1
|
|
BLAKE2b-256 checksum How to use checksums |
ba354f4f2a2a7d1facfce276f9a7173f5670f1eaf69d1839eceae78fc23da400
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Release files / superdate-0.2.2-py3-none-any.whl
| Download URL | superdate-0.2.2-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55df7a108db36d7c3952cefc3476dc28af4bcb2f15b695967fc372509b1f20b9
|
|
BLAKE2b-256 checksum How to use checksums |
4156261a39a24ad316000dbcab2e1cde9901bab7dfac8f36ed0e8d55607e9445
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.10
|
Security for superdate 0.2.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.