Skip to main content

Classes for representing partial and approximate dates

Project description

[This is a preliminary version of this library (hence the 0.* version number) and the API may change.]

It’s frequently useful to be able to represent partial or approximate dates in Python. Colloquially, examples of these might be:

  • 1963 (i.e. just the year, with no month or day specified)

  • March 1979 (i.e. just the year and the month, with no day specified)

  • At some point before the 21st of July 2015

  • At some point after 1st January 2000

  • Some point between 25th and 31st of December 2016

  • At an arbitrary or unknown point in the past

  • At an arbitrary or unknown point in the future

The ApproxDate class can represent all of the above, as well as precise dates, where the exact year, month and day is known.

This package has been tested on Python 2.7 and Python 3.5.

Similar Packages

The alternative to this package that I’m aware of is the ApproximateDate class from django-date-extensions. This has a different model for approximate dates - they can be past, future, YYYY, YYYY-MM or YYYY-MM-DD, whereas the ApproxDate model in this package can also represent a date which is known to be between two arbitrary dates, or is known to be before (or after) some particular date.


You can install this package with:

pip install approx_dates


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

from approx_dates.models import ApproxDate


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


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 objects, you can use on of the following methods:

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

>>>, 3, 1)

>>>, 3, 31)

>>>, 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 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, 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 might be between two ApproxDate or 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


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

pip install -e .
pip install tox

And then run the tests with:


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

approx_dates-0.0.1.tar.gz (5.1 kB view hashes)

Uploaded source

approx-dates-0.0.1.tar.gz (5.1 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page