superdate 0.2.2
A super flexible and performant date parser.
Requires Python: <4,>=3

===========
 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.