undate overview

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.

Currently 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 dates (bare years are currently assumed to be Gregorian calendar).

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.

Installation

Recommended: use pip to install the latest published version from PyPI:

pip install undate

To install a development version or specific tag or branch, you can install from GitHub. Use the @name notation to specify the branch or tag; e.g., to install development version:

pip install git+https://github.com/dh-tech/undate-python@develop#egg=undate

Quick Start

An Undate is analogous to python’s datetime.date but supports varying degrees of precision and unknown information. Initialize with strings or numbers for whichever parts of the date are known:

from undate import Undate, UndateInterval

november7 = Undate(2000, 11, 7)
november = Undate(2000, 11)
year2k = Undate(2000)
partially_known_year = Undate("19XX")

print([str(d) for d in [november7, november, year2k, partially_known_year]])
# [‘2000-11-07’, ‘2000-11’, ‘2000’, ‘19XX’]

print(repr(Undate.parse("Rajab 495", "Islamic")))
# undate.Undate(year=495, month=7, label="Rajab 495 Islamic", calendar="Islamic")

For full examples including duration, comparison, intervals, parsing, and calendar support, see the interactive documentation.

Documentation

Project documentation is available on ReadTheDocs.

For instructions on setting up for local development, see Developer Notes.

See Contributors for more detailed information about contributors.

Publications & Presentations

• Rebecca Sutton Koeser, Julia Damerow, Robert Casties, and Cole Crawford. “Undate: Humanistic Dates for Computation.” Software paper published in Computational Humanities Research, August 5, 2025.
• Rebecca Sutton Koeser. “Undate: Computing with Uncertain and Partially-Unknown Dates.” Computational notebook presented at USRSE’25. October 6, 2025.
• Rebecca Sutton Koeser. “Undate in Action.” Presentation at Digital Humanities Tech Symposium, DH2025. July 14, 2025.
• Rebecca Sutton Koeser. 2025. “Undate in Action.” In Digital Humanities Tech Symposium 2025—Anthology of Computers and the Humanities, edited by Julia Damerow and Rebecca Sutton Koeser, vol. 2.
• Rebecca Sutton Koeser. Join me for a DHTech hackathon? It’s an un-date! DHTech, February 9, 2023.

Related Projects

• ISO8601 date support and dates with unknown years, including duration, adapted from Shakespeare and Company Project (codebase)
• Parsing and calendar conversion for Hebrew Anno Mundi and Islamic Hijri calendars adapted from Princeton Geniza Project (PGP) (codebase); improved and verified with data and logic from the Islamic Scientific Manuscripts Initiative (ISMI)
• Parsing for dates in African languages inspired by work on and partially checked against data from MasakhaNER
• Parsing and calendar conversion for Christian liturgical holidays adapted from work on Hale/Eliot Letters project

License

This software is licensed under the Apache 2.0 License.