undate¶
undate is a Python library for working with uncertain or partially known dates.
Note
This is beta software; it is still in development and not fully feature complete. If you use it, please let us know and share your feedback.
undate supports parsing, formatting, and reasoning with dates in varying
precision and calendars. Dates with different precision and from different original
calendars can be used together. Supported formats include:
portions of EDTF (Extended Date Time Format)
ISO8601
parsing and calendar conversion for dates in Hebrew Anno Mundi and Islamic Hijri calendars
Gregorian dates with full or abbreviated month names in any order for multiple languages (English, Spanish, French, German, Kinyarwanda, Ganda, Tigrinya)
Christian liturgical dates (fixed holidays and movable feasts)
For unambiguous dates, there is an experimental omnibus parser which combines all available parsers.
For more about the origin and goals of undate, read our 2025 software paper:
Rebecca Sutton Koeser, Julia Damerow, Robert Casties, and Cole Crawford. “Undate: Humanistic Dates for Computation.” Computational Humanities Research, August 5, 2025.
Quick Start¶
An Undate is analogous to Python’s datetime.date, but with support for
varying precision and unknown information:
from undate import Undate, UndateInterval
november = Undate(2000, 11) # year and month known
year2k = Undate(2000) # year only
partially_known = Undate("19XX") # partially unknown year
print([str(d) for d in [november, year2k, partially_known]])
# ['2000-11', '2000', '19XX']
Dates can be parsed from multiple formats and calendars, sorted, and compared even when precision differs. See Example Usage for interactive examples.
Installation¶
Install the latest published version from PyPI:
pip install undate
To install a development version or specific branch:
pip install git+https://github.com/dh-tech/undate-python@develop#egg=undate