Undate objects

dates, intervals, and calendar

class undate.undate.Undate(year: int | str | None = None, month: int | str | None = None, day: int | str | None = None, converter: BaseDateConverter | None = None, label: str | None = None, calendar: str | Calendar | None = None)

object for representing uncertain, fuzzy or partially unknown dates

MISSING_DIGIT: str = 'X'

symbol for unknown digits within a date value

as_calendar(calendar: str | Calendar)

Return a new Undate object with the same year, month, day, and labels used to initialize the current object, but with a different calendar. Note that this does NOT do calendar conversion, but reinterprets current numeric year, month, day values according to the new calendar.

calendar: Calendar = 'gregorian'

the calendar this date is using; Gregorian by default

property day: str | None

day as 2-character string or None if unset

duration() → Timedelta | UnDelta

What is the duration of this date? Calculate based on earliest and latest date within range, taking into account the precision of the date even if not all parts of the date are known. Note that durations are inclusive (i.e., a closed interval) and include both the earliest and latest date rather than the difference between them. Returns a undate.date.Timedelta when possible, and an undate.date.UnDelta when the duration is uncertain.

format(format) → str

format this undate as a string using the specified format; for now, only supports named converters

is_known(part: str) → bool

Check if a part of the date (year, month, day) is fully known. Returns False if unknown or only partially known.

is_unknown(part: str) → bool

Check if a part of the date (year, month, day) is completely unknown.

property known_year: bool

year is fully known

label: str | None = None

A string to label a specific undate, e.g. “German Unity Date 2022” for Oct. 3, 2022. Labels are not taken into account when comparing undate objects.

property month: str | None

month as 2-character string, or None if unknown/unset

classmethod parse(date_string, format) → Undate | UndateInterval

parse a string to an undate or undate interval using the specified format; for now, only supports named converters

property possible_years: list[int] | range

A list or range of possible years for this date in the original calendar. Returns a list with a single year for dates with fully-known years.

precision: DatePrecision

precision of the date (day, month, year, etc.)

property representative_years: list[int]

A list of representative years for this date.

set_calendar(calendar: str | Calendar)

Find calendar by name if passed as string and set on the object. Only intended for use at initialization time; use as_calendar() to change calendar.

classmethod to_undate(other: object) → Undate

Convert arbitrary object to Undate, if possible. Raises TypeError if conversion is not possible.

Currently supports:
property unknown_year: bool

year is completely unknown

property year: str | None

year as string (minimum 4 characters), if year is known

class undate.undate.Calendar(*values)

Supported calendars

class undate.interval.UndateInterval(earliest: Undate | None = None, latest: Undate | None = None, label: str | None = None)

A date range between two uncertain dates.

Parameters:

  • earliest (undate.Undate) – Earliest undate

  • latest (undate.Undate) – Latest undate

  • label (str) – A string to label a specific undate interval, similar to labels of undate.Undate.

duration() → Timedelta

Calculate the duration between two undates. Note that durations are inclusive (i.e., a closed interval), and include both the earliest and latest date rather than the difference between them.

Returns:

A duration

Return type:

Timedelta

format(format) → str

format this undate interval as a string using the specified format; for now, only supports named converters

intersection(other: UndateInterval) → UndateInterval | None

Determine the intersection or overlap between two UndateInterval objects and return a new interval. Returns None if there is no overlap.

date, timedelta, and date precision

class undate.date.Date(year: int | datetime64, month: int | None = None, day: int | None = None)

Convenience class to make numpy.datetime64 act more like the built-in python datetime.date.

property weekday: int | None

Equivalent to datetime.date.weekday(); returns day of week as an integer where Monday is 0 and Sunday is 6. Only supported for dates with date unit in days.

class undate.date.Timedelta(deltadays: timedelta64 | int)

Convenience class to make numpy.timedelta64 act more like the built-in python datetime.timedelta.

property days: int

number of days, as an integer

class undate.date.DatePrecision(*values)

date precision, to indicate date precision independent from how much of the date is known.