infdate 0.2.0

Date object wrapper supporting infinity

infdate

Python module for date calculations implementing a concept of infinity

Module description

Class hierarchy:

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

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 similöar semantics.

For any valid RealDate instance, the following is True:

infdate.MIN < infdate.RealDate(1, 1, 1) <= real_date_instance <= infdate.RealDate(9999, 12, 31) < infdate.MAX

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

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

fromtimestamp() is still missing by mistake.

Two additional factory functions are provided in the module:

• 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.

Some notable difference from the datetime.date class:

• 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 (because math.inf is a float), not a datetime.timedelta instance.

• Likewise, you cannot add or subtract datetime.timedelta instances from n InfinityDate or RealDate, only loat or int.

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

You can compare InfinityDate, RealDate and datetime.date instances, and subtract them from each other (although currently, __rsub__ is not implemented yet, so subtracting an InfinityDate or RealDate from a datetime.date still gives 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'

---