infdate 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

infdate/__init__.py

@@ -6,7 +6,7 @@ capable of representing positive and negative infinity
 """
 
 from datetime import date, datetime
-from math import inf
+from math import inf, trunc
 from typing import final, overload, Any, Final, TypeVar
 
 
@@ -28,6 +28,8 @@ ISO_DATETIME_FORMAT_UTC: Final[str] = f"{ISO_DATE_FORMAT}T%H:%M:%S.%fZ"
 MIN_ORDINAL: Final[int] = date.min.toordinal()
 MAX_ORDINAL: Final[int] = date.max.toordinal()
 
+RESOLUTION: Final[int] = 1
+
 
 # -----------------------------------------------------------------------------
 # Internal module constants:
@@ -45,15 +47,15 @@ _GD = TypeVar("_GD", bound="GenericDate")
 class GenericDate:
     """Base Date object derived from an ordinal"""
 
-    # pylint: disable=invalid-name
-    resolution: Final = 1
-    # pylint: enable=invalid-name
-
-    def __init__(self, ordinal: float, /) -> None:
+    def __init__(self, ordinal: int | float, /) -> None:
         """Create a date-like object"""
-        self.__ordinal = ordinal
+        if ordinal in (-inf, inf):
+            self.__ordinal = ordinal
+        else:
+            self.__ordinal = trunc(ordinal)
+        #
 
-    def toordinal(self: _GD) -> float:
+    def toordinal(self: _GD) -> int | float:
         """to ordinal (almost like date.toordinal())"""
         return self.__ordinal
 
@@ -109,24 +111,30 @@ class GenericDate:
             return self
         #
         # Return a RealDate instance if possible
-        return fromordinal(self.__ordinal + delta)
+        return fromordinal(self.__ordinal + trunc(delta))
 
     def __add__(self: _GD, delta: int | float, /) -> _GD:
         """gd_instance1 + number capability"""
         return self._add_days(delta)
 
+    __radd__ = __add__
+
     @overload
     def __sub__(self: _GD, other: int | float, /) -> _GD: ...
     @overload
-    def __sub__(self: _GD, other: _GD, /) -> int | float: ...
+    def __sub__(self: _GD, other: _GD | date, /) -> int | float: ...
     @final
-    def __sub__(self: _GD, other: _GD | int | float, /) -> _GD | int | float:
+    def __sub__(self: _GD, other: _GD | date | int | float, /) -> _GD | int | float:
         """subtract other, respecting possibly nondeterministic values"""
         if isinstance(other, (int, float)):
             return self._add_days(-other)
         #
         return self.__ordinal - other.toordinal()
 
+    def __rsub__(self: _GD, other: _GD | date, /) -> int | float:
+        """subtract from other, respecting possibly nondeterministic values"""
+        return other.toordinal() - self.__ordinal
+
     def __repr__(self: _GD, /) -> str:
         """String representation of the object"""
         return f"{self.__class__.__name__}({repr(self.__ordinal)})"
@@ -186,7 +194,7 @@ class RealDate(GenericDate):
         self.year = year
         self.month = month
         self.day = day
-        super().__init__(float(self._wrapped_date_object.toordinal()))
+        super().__init__(self._wrapped_date_object.toordinal())
         self.timetuple = self._wrapped_date_object.timetuple
         self.weekday = self._wrapped_date_object.weekday
         self.isoweekday = self._wrapped_date_object.isoweekday
@@ -274,7 +282,7 @@ def fromtimestamp(timestamp: float) -> GenericDate:
     return from_datetime_object(stdlib_date_object)
 
 
-def fromordinal(ordinal: float | int) -> GenericDate:
+def fromordinal(ordinal: int | float) -> GenericDate:
     """Create an InfinityDate or RealDate instance from the provided ordinal"""
     if ordinal == -inf:
         return MIN
@@ -282,11 +290,7 @@ def fromordinal(ordinal: float | int) -> GenericDate:
     if ordinal == inf:
         return MAX
     #
-    try:
-        new_ordinal = int(ordinal)
-    except ValueError as error:
-        raise ValueError(f"Cannot convert {ordinal!r} to integer") from error
-    #
+    new_ordinal = trunc(ordinal)
     if not MIN_ORDINAL <= new_ordinal <= MAX_ORDINAL:
         raise OverflowError("RealDate value out of range")
     #

{infdate-0.2.1.dist-info → infdate-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infdate
-Version: 0.2.1
+Version: 0.2.2
 Summary: Date object wrapper supporting infinity
 Project-URL: Homepage, https://gitlab.com/blackstream-x/infdate
 Project-URL: CI, https://gitlab.com/blackstream-x/infdate/-/pipelines
@@ -14,12 +14,13 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 
 # infdate
@@ -35,14 +36,18 @@ _Python module for date calculations implementing a concept of infinity_
         └── RealDate
 
 
-The base class **GenericDate** should not be instantiated but can be used as a type annotation.
+The base class **GenericDate** should not be instantiated
+but can be used as a type annotation. In fact, it should be preferred
+over the other classes in typing annotations.
 
 **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.
+**[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**:
 
@@ -50,9 +55,21 @@ 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
+### Module-level constants
+
+*   **MIN** = **InfinityDate(**_past_bound_=`True`**)** → the beginning of time
+*   **MAX** = **InfinityDate(**_past_bound_=`False`**)** → the end of time
+*   **MIN_ORDINAL** = `1` → same as **datetime.date.min.toordinal()**
+*   **MAX_ORDINAL** = `3652059` → same as **datetime.date.max.toordinal()**
+*   **REAL_MIN** = **fromordinal(MIN_ORDINAL)**
+    → represents _0001-01-01_, the same date as **datetime.date.min**
+*   **REAL_MAX** = **fromordinal(MAX_ORDINAL)**
+    → represents _9999-12-31_, the same date as **datetime.date.max**
+*   **RESOLUTION** = `1` → represents the lowest possible date difference: _one day_
 
 
+### Module-level factory functions
+
 The following factory methods from the **datetime.date** class
 are provided as module-level functions:
 
@@ -78,15 +95,17 @@ Two additional factory functions are provided:
 
 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**
+*   infdate classes have no **max**, **min** or **resolution** attributes,
+    but there are [module-level constants] serving the same purpose.
 
-*   The **resolution** attribute is **1.0** instead of **datetime.timedelta(days=1)**
-    but also represents exactly one day.
+*   The **.toordinal()** method returns **int**, **math.inf**, or **-math.inf**.
 
-*   Subtracting a date from an **InfinityDate** or **RealDate** always returns a float instead of a **datetime.timedelta** instance.
+*   Subtracting a date from an **InfinityDate** or **RealDate** always returns
+    an **int**, **math.inf**, or **-math.inf** 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).
+    from an **InfinityDate** or **RealDate**, only **float** or **int**
+    (support for adding and subtracting datetime.timedelta instances might be added in the future, [see the feature request]).
 
 
 ## Example usage
@@ -95,22 +114,20 @@ Some notable difference from the **datetime.date** class, mainly due to the desi
 >>> 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
+RealDate(2025, 6, 27)
+>>> print(f"US date notation: {today:%m/%d/%y}")
+US date notation: 06/27/25
 >>> today.ctime()
-'Wed Jun 25 00:00:00 2025'
+'Fri Jun 27 00:00:00 2025'
 >>> today.isocalendar()
-datetime.IsoCalendarDate(year=2025, week=26, weekday=3)
+datetime.IsoCalendarDate(year=2025, week=26, weekday=5)
 >>>
 >>> yesterday = today - 1
 >>> yesterday.ctime()
-'Tue Jun 24 00:00:00 2025'
+'Thu Jun 26 00:00:00 2025'
 >>>
 >>> today - yesterday
-1.0
+1
 >>> infdate.MIN
 InfinityDate(past_bound=True)
 >>> infdate.MAX
@@ -123,25 +140,26 @@ 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'
+Subtracting **InfinityDate** or **RealDate** and **datetime.date** instances from each other also works:
 
+``` pycon
+>>> from datetime import date
+>>> stdlib_today = date.today()
+>>> today == stdlib_today
+True
+>>> yesterday < stdlib_today
+True
+>>> yesterday - stdlib_today
+-1
+>>> stdlib_today - yesterday
+1
+>>> stdlib_today - infdate.MIN
+inf
+```
 
 
 * * *
-[Personal Access Tokens API]: https://docs.gitlab.com/api/personal_access_tokens/
+[datetime.date]: https://docs.python.org/3/library/datetime.html#date-objects
+[Personal Access Tokens API]: https://docs.gitlab.com/api/personal_access_tokens/
+[module-level constants]: #module-level-constants
+[see the feature request]: https://gitlab.com/blackstream-x/infdate/-/issues/6

infdate-0.2.2.dist-info/RECORD

@@ -0,0 +1,6 @@
+infdate/__init__.py,sha256=5hjONWaY3mtCaXUQz2YN3qm6R84p6eV5bjTwW8JcvFU,11360
+infdate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+infdate-0.2.2.dist-info/METADATA,sha256=LBnq5cSaqv4eIom0ZC0NTMV0jNiAziuRyLqEY-Rhvls,5904
+infdate-0.2.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+infdate-0.2.2.dist-info/licenses/LICENSE,sha256=867pxriiObx28vCU1JsRtu3H9kUKyl54e0-xl1IIv3Y,913
+infdate-0.2.2.dist-info/RECORD,,

infdate-0.2.1.dist-info/RECORD

@@ -1,6 +0,0 @@
-infdate/__init__.py,sha256=n3WfJnHma_FGelLrkOjBt4gj49P-_rlsqc0FTLmUxCI,11195
-infdate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-infdate-0.2.1.dist-info/METADATA,sha256=V85LBfMkyB66rZJI4ceghR0KL-x0b2RQoOo-0_Sr77s,5205
-infdate-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-infdate-0.2.1.dist-info/licenses/LICENSE,sha256=867pxriiObx28vCU1JsRtu3H9kUKyl54e0-xl1IIv3Y,913
-infdate-0.2.1.dist-info/RECORD,,