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

infdate/__init__.py

@@ -6,10 +6,15 @@ 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
 
 
+# -----------------------------------------------------------------------------
+# Public module constants:
+# display definitions, format strings, upper and loer ordinal boundaries
+# -----------------------------------------------------------------------------
+
 INFINITE_DATE_DISPLAY: Final[str] = "<inf>"
 NEGATIVE_INFINITE_DATE_DISPLAY: Final[str] = "<-inf>"
 
@@ -23,22 +28,34 @@ 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:
+# TypeVar for GenericDate
+# -----------------------------------------------------------------------------
 
 _GD = TypeVar("_GD", bound="GenericDate")
 
 
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+
 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
 
@@ -94,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)})"
@@ -171,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
@@ -204,12 +227,18 @@ class RealDate(GenericDate):
         )
 
 
-# Absolute minimum and maximum dates
+# -----------------------------------------------------------------------------
+# Public module constants continued:
+# absolute minimum and maximum dates
+# -----------------------------------------------------------------------------
+
 MIN: Final[GenericDate] = InfinityDate(past_bound=True)
 MAX: Final[GenericDate] = InfinityDate(past_bound=False)
 
 
-# Factory functions
+# -----------------------------------------------------------------------------
+# Module-level factory functions
+# -----------------------------------------------------------------------------
 
 
 def from_datetime_object(source: date | datetime, /) -> GenericDate:
@@ -241,7 +270,19 @@ def from_native_type(
     raise ValueError(f"Don’t know how to convert {source!r} into a date")
 
 
-def fromordinal(ordinal: float | int) -> GenericDate:
+def fromtimestamp(timestamp: float) -> GenericDate:
+    """Create an InfinityDate or RealDate instance from the provided timestamp"""
+    if timestamp == -inf:
+        return MIN
+    #
+    if timestamp == inf:
+        return MAX
+    #
+    stdlib_date_object = date.fromtimestamp(timestamp)
+    return from_datetime_object(stdlib_date_object)
+
+
+def fromordinal(ordinal: int | float) -> GenericDate:
     """Create an InfinityDate or RealDate instance from the provided ordinal"""
     if ordinal == -inf:
         return MIN
@@ -249,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")
     #
@@ -261,6 +298,20 @@ def fromordinal(ordinal: float | int) -> GenericDate:
     return from_datetime_object(stdlib_date_object)
 
 
+# -----------------------------------------------------------------------------
+# Public module constants continued:
+# minimum and maximum real dates
+# -----------------------------------------------------------------------------
+
+REAL_MIN: Final[GenericDate] = fromordinal(MIN_ORDINAL)
+REAL_MAX: Final[GenericDate] = fromordinal(MAX_ORDINAL)
+
+
+# -----------------------------------------------------------------------------
+# Module-level factory functions continued
+# -----------------------------------------------------------------------------
+
+
 def fromisoformat(source: str, /) -> GenericDate:
     """Create an InfinityDate or RealDate instance from an iso format representation"""
     lower_source_stripped = source.strip().lower()
@@ -281,8 +332,3 @@ def fromisocalendar(year: int, week: int, weekday: int) -> GenericDate:
 def today() -> GenericDate:
     """Today as RealDate object"""
     return from_datetime_object(date.today())
-
-
-# Minimum and maximum real dates
-# setattr(RealDate, "min", fromordinal(MIN_ORDINAL))
-# setattr(RealDate, "max", fromordinal(MAX_ORDINAL))

infdate-0.2.2.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: infdate
+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
+Project-URL: Bug Tracker, https://gitlab.com/blackstream-x/infdate/-/issues
+Project-URL: Repository, https://gitlab.com/blackstream-x/infdate.git
+Author-email: Rainer Schwarzbach <rainer@blackstream.de>
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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.10
+Description-Content-Type: text/markdown
+
+# 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. 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.
+
+For any valid **RealDate** instance, the following is **True**:
+
+``` python
+infdate.MIN < infdate.REAL_MIN <= real_date_instance <= infdate.REAL_MAX < infdate.MAX
+```
+
+### 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:
+
+*   **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):
+
+*   infdate classes have no **max**, **min** or **resolution** attributes,
+    but there are [module-level constants] serving the same purpose.
+
+*   The **.toordinal()** method returns **int**, **math.inf**, or **-math.inf**.
+
+*   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, [see the feature request]).
+
+
+## Example usage
+
+``` pycon
+>>> import infdate
+>>> today = infdate.today()
+>>> today
+RealDate(2025, 6, 27)
+>>> print(f"US date notation: {today:%m/%d/%y}")
+US date notation: 06/27/25
+>>> today.ctime()
+'Fri Jun 27 00:00:00 2025'
+>>> today.isocalendar()
+datetime.IsoCalendarDate(year=2025, week=26, weekday=5)
+>>>
+>>> yesterday = today - 1
+>>> yesterday.ctime()
+'Thu Jun 26 00:00:00 2025'
+>>>
+>>> today - yesterday
+1
+>>> 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 **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
+```
+
+
+* * *
+[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.0.dist-info/METADATA

@@ -1,141 +0,0 @@
-Metadata-Version: 2.4
-Name: infdate
-Version: 0.2.0
-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
-Project-URL: Bug Tracker, https://gitlab.com/blackstream-x/infdate/-/issues
-Project-URL: Repository, https://gitlab.com/blackstream-x/infdate.git
-Author-email: Rainer Schwarzbach <rainer@blackstream.de>
-License-File: LICENSE
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-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.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
-Description-Content-Type: text/markdown
-
-# 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**:
-
-``` python
-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
-
-``` pycon
->>> 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'
-
-
-* * *
-[Personal Access Tokens API]: https://docs.gitlab.com/api/personal_access_tokens/

infdate-0.2.0.dist-info/RECORD

@@ -1,6 +0,0 @@
-infdate/__init__.py,sha256=wBa4EXdkOXSSsX3QpBwx8jIpz3s6UETUoJnTlnqRNhc,9422
-infdate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-infdate-0.2.0.dist-info/METADATA,sha256=_g58qFMeECVrjNn0Z_t3Bggox3GHYXqY9NGVwA75ld4,4573
-infdate-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-infdate-0.2.0.dist-info/licenses/LICENSE,sha256=867pxriiObx28vCU1JsRtu3H9kUKyl54e0-xl1IIv3Y,913
-infdate-0.2.0.dist-info/RECORD,,