approx-dates 0.0.1

Installation

You can install this package with:

pip install approx_dates

Usage

You can create a full date or a partial date from the an ISO 8601 string:

from approx_dates.models import ApproxDate

ApproxDate.from_iso8601('1215-06-15')
ApproxDate.from_iso8601('1215-06')
ApproxDate.from_iso8601('1215')

Or you can reprent points arbitrarily far in the past or future with:

ApproxDate.PAST
ApproxDate.FUTURE

To represent a date that’s somewhere within two bounds, you can specify two endpoints. For example:

from datetime import date

ApproxDate(date(2016, 12, 25), date(2016, 12, 31))

These endpoints are intended to be inclusive. For example, the above ApproxDate might represent the 25th, 26th, … or the 31st of December 2016.

You can test whether an ApproxDate represents arbitrarily far in the future or in the past with the past and future properties which evaluate to True or False.

To convert an ApproxDate into one of core Python’s datetime.date objects, you can use on of the following methods:

ad = ApproxDate.from_iso8601('1979-03')

ad.earliest_date
>>> datetime.date(1979, 3, 1)

ad.latest_date
>>> datetime.date(1979, 3, 31)

ad.midpoint_date
>>> datetime.date(1979, 3, 16)

Obviously, whether one ApproxDate is earlier or later than another is ill-defined, so the __lt__, __gt__, __lte__ and __gte__ magic methods are not defined on ApproxDate. If you need to compare two ApproxDate objects, you need to first convert it to a datetime.date using one of the methods above.

The __eq__ and __ne__ magic methods are defined, so that two approx dates can be tested for whether they represent exactly the same possible range of dates. If the right hand side of an equality or inequality comparison is a datetime.date, it will treated equal if the ApproxDate on the left is precise to a day, and reprents the same date.

You can also test whether a datetime.date might be between two ApproxDate or datetime.date objects using the ApproxDate.possibly_between class method, e.g.:

d1 = ApproxDate.from_iso8601('2000')
d2 = ApproxDate.from_iso8601('2005')
ApproxDate.possibly_between(d1, date(2000, 7, 1), d2)
>>> True

ApproxDate.possibly_between(d1, date(1999, 12, 31), d2)
>>> True

Development

After cloning this repository, you can install the dependencies for development with:

pip install -e .
pip install tox

And then run the tests with:

tox