infdate 0.2.1

Date object wrapper supporting infinity

infdate

Python module for date calculations implementing a concept of infinity

Module description

Classes overview

└── GenericDate
    ├── InfinityDate
    └── RealDate

The base class GenericDate should not be instantiated but can be used as a type annotation.

InfinityDate can represent either positive or negative infinity. The module-level constants MIN and MAX contain the two possible InfinityDate instance variations.

RealDate instances represent real dates like the standard library’s datetime.date class, with mostly equal or similar semantics. The module -level constants REAL_MIN and REAL_MAX are the eqivalents of datetime.date.min and datetime.date.max as RealDate instances.

For any valid RealDate instance, the following is True:

infdate.MIN < infdate.REAL_MIN <= real_date_instance <= infdate.REAL_MAX < infdate.MAX

Module-level factory functions

The following factory methods from the datetime.date class are provided as module-level functions:

• fromtimestamp() (also accepting -math.inf or math.inf)
• fromordinal() (also accepting -math.inf or math.inf)
• fromisoformat()
• fromisocalendar()
• today()

Two additional factory functions are provided:

• from_datetime_object() to create a RealDate instance from a datetime.date or datetime.datetime instance

• from_native_type() to create an InfinityDate or RealDate instance from a string, from None, -math.inf or math.inf.

  This can come handy when dealing with API representations of dates, eg. in GitLab’s Personal Access Tokens API.

Differences between infdate classes and datetime.date

Some notable difference from the datetime.date class, mainly due to the design decision to express date differences in pure numbers (ie. float because math.inf also is a float):

• The .toordinal() method returns float instead of int

• The resolution attribute is 1.0 instead of datetime.timedelta(days=1) but also represents exactly one day.

• Subtracting a date from an InfinityDate or RealDate always returns a float instead of a datetime.timedelta instance.

• Likewise, you cannot add or subtract datetime.timedelta instances from an InfinityDate or RealDate, only float or int (support for adding and subtracting datetime.timedelta instances might be added in the future).

Example usage

>>> import infdate
>>> today = infdate.today()
>>> today
RealDate(2025, 6, 25)
>>> print(today)
2025-06-25
>>> print(f"US date notation {today:%m/%d/%y}")
US date notation 06/25/25
>>> today.ctime()
'Wed Jun 25 00:00:00 2025'
>>> today.isocalendar()
datetime.IsoCalendarDate(year=2025, week=26, weekday=3)
>>>
>>> yesterday = today - 1
>>> yesterday.ctime()
'Tue Jun 24 00:00:00 2025'
>>>
>>> today - yesterday
1.0
>>> infdate.MIN
InfinityDate(past_bound=True)
>>> infdate.MAX
InfinityDate(past_bound=False)
>>> infdate.MAX - today
inf
>>> infdate.MAX - infdate.MIN
inf

InfinityDate and RealDate instances can be compared with each other, and also with datetime.date instances.

Subtracting instances from each other also works, but currently, __rsub__ is not implemented yet, so although the other direction works, subtracting an InfinityDate or RealDate from a datetime.date currently still raises a TypeError):

>>> from datetime import date
>>> stdlib_today = date.today()
>>> today == stdlib_today
True
>>> yesterday < stdlib_today
True
>>> yesterday - stdlib_today
-1.0
>>> stdlib_today - yesterday
Traceback (most recent call last):
  File "<python-input-22>", line 1, in <module>
    stdlib_today - yesterday
    ~~~~~~~~~~~~~^~~~~~~~~~~
TypeError: unsupported operand type(s) for -: 'datetime.date' and 'RealDate'

---