infdate 0.1.0__tar.gz → 0.2.0__tar.gz

infdate-0.2.0/PKG-INFO

@@ -0,0 +1,141 @@
+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/README.md

@@ -0,0 +1,117 @@
+# 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.1.0 → infdate-0.2.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "infdate"
-version = "0.1.0"
+version = "0.2.0"
 description = "Date object wrapper supporting infinity"
 readme = "README.md"
 authors = [
-    { name = "Rainer Schwarzbach", email = "rainer@blackstream.de" }
+    { name = "Rainer Schwarzbach", email = "rainer@blackstream.de" },
 ]
 requires-python = ">=3.11"
 classifiers = [

infdate-0.2.0/reports/docs/build-info.json

@@ -0,0 +1,8 @@
+{
+  "ci_pipeline_created_at": "2025-06-25T15:48:59Z",
+  "ci_pipeline_id": "1889338569",
+  "ci_pipeline_url": "https://gitlab.com/blackstream-x/infdate/-/pipelines/1889338569",
+  "ci_project_title": "infdate",
+  "ci_project_url": "https://gitlab.com/blackstream-x/infdate",
+  "ci_commit_sha": "2f339a6673ac21ac72292598799f6c602866afaf"
+}

{infdate-0.1.0 → infdate-0.2.0}/reports/docs/build-info.md

@@ -4,6 +4,6 @@ _provided by [glsr-present](https://pypi.org/project/glsr-present/) 0.3.6_
 
 [infdate](https://gitlab.com/blackstream-x/infdate)
 built with pipeline
-[1884836730](https://gitlab.com/blackstream-x/infdate/-/pipelines/1884836730)
-(build started 2025-06-23T16:10:13Z)
+[1889338569](https://gitlab.com/blackstream-x/infdate/-/pipelines/1889338569)
+(build started 2025-06-25T15:48:59Z)
 

infdate-0.2.0/reports/test-junit.xml

@@ -0,0 +1 @@
+<?xml version="1.0" encoding="utf-8"?><testsuites name="pytest tests"><testsuite name="pytest" errors="0" failures="0" skipped="0" tests="33" time="0.768" timestamp="2025-06-25T15:49:40.687820+00:00" hostname="runner-xxurkrix-project-71015407-concurrent-0"><testcase classname="tests.test_infdate.GenericDate" name="test_add" time="0.009" /><testcase classname="tests.test_infdate.GenericDate" name="test_add_days" time="0.005" /><testcase classname="tests.test_infdate.GenericDate" name="test_bool" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_eq" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_ge" time="0.055" /><testcase classname="tests.test_infdate.GenericDate" name="test_gt" time="0.046" /><testcase classname="tests.test_infdate.GenericDate" name="test_hash" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_isoformat" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_le" time="0.055" /><testcase classname="tests.test_infdate.GenericDate" name="test_lt" time="0.045" /><testcase classname="tests.test_infdate.GenericDate" name="test_ne" time="0.045" /><testcase classname="tests.test_infdate.GenericDate" name="test_replace" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_repr" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_str" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_strftime" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_sub_date" time="0.001" /><testcase classname="tests.test_infdate.GenericDate" name="test_sub_number" time="0.004" /><testcase classname="tests.test_infdate.GenericDate" name="test_toordinal" time="0.001" /><testcase classname="tests.test_infdate.InfinityDate" name="test_replace" time="0.001" /><testcase classname="tests.test_infdate.InfinityDate" name="test_repr" time="0.001" /><testcase classname="tests.test_infdate.InfinityDate" name="test_strftime" time="0.001" /><testcase classname="tests.test_infdate.RealDate" name="test_attributes" time="0.001" /><testcase classname="tests.test_infdate.RealDate" name="test_bool" time="0.001" /><testcase classname="tests.test_infdate.RealDate" name="test_proxied_methods" time="0.001" /><testcase classname="tests.test_infdate.RealDate" name="test_replace" time="0.002" /><testcase classname="tests.test_infdate.RealDate" name="test_repr" time="0.001" /><testcase classname="tests.test_infdate.RealDate" name="test_strftime" time="0.003" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_from_datetime_object" time="0.002" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_from_native_type" time="0.005" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_fromisocalendar" time="0.003" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_fromisoformat" time="0.002" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_fromordinal" time="0.002" /><testcase classname="tests.test_infdate.FactoryFunctions" name="test_today" time="0.002" /></testsuite></testsuites>

infdate-0.2.0/src/infdate/__init__.py

@@ -0,0 +1,288 @@
+# -*- coding: utf-8 -*-
+
+"""
+infdate: a wrapper around standard library’s datetime.date objects,
+capable of representing positive and negative infinity
+"""
+
+from datetime import date, datetime
+from math import inf
+from typing import final, overload, Any, Final, TypeVar
+
+
+INFINITE_DATE_DISPLAY: Final[str] = "<inf>"
+NEGATIVE_INFINITE_DATE_DISPLAY: Final[str] = "<-inf>"
+
+INFINITY_SYMBOL: Final[str] = "∝"
+UP_TO_SYMBOL: Final[str] = "⤒"
+FROM_ON_SYMBOL: Final[str] = "↥"
+
+ISO_DATE_FORMAT: Final[str] = "%Y-%m-%d"
+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()
+
+
+_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:
+        """Create a date-like object"""
+        self.__ordinal = ordinal
+
+    def toordinal(self: _GD) -> float:
+        """to ordinal (almost like date.toordinal())"""
+        return self.__ordinal
+
+    def __lt__(self: _GD, other: _GD, /) -> bool:
+        """Rich comparison: less"""
+        return self.__ordinal < other.toordinal()
+
+    def __le__(self: _GD, other: _GD, /) -> bool:
+        """Rich comparison: less or equal"""
+        return self < other or self == other
+
+    def __gt__(self: _GD, other: _GD, /) -> bool:
+        """Rich comparison: greater"""
+        return self.__ordinal > other.toordinal()
+
+    def __ge__(self: _GD, other: _GD, /) -> bool:
+        """Rich comparison: greater or equal"""
+        return self > other or self == other
+
+    def __eq__(self: _GD, other, /) -> bool:
+        """Rich comparison: equals"""
+        return self.__ordinal == other.toordinal()
+
+    def __ne__(self: _GD, other, /) -> bool:
+        """Rich comparison: does not equal"""
+        return self.__ordinal != other.toordinal()
+
+    def __bool__(self: _GD, /) -> bool:
+        """True only if a real date is wrapped"""
+        return False
+
+    def __hash__(self: _GD, /) -> int:
+        """hash value"""
+        return hash(f"date with ordinal {self.__ordinal}")
+
+    def _add_days(self: _GD, delta: int | float, /):
+        """Add other, respecting maybe-nondeterministic values"""
+        # Check for infinity in either self or delta,
+        # and return a matching InfinityDate if found.
+        # Re-use existing objects if possible.
+        for observed_item in (delta, self.__ordinal):
+            for infinity_form in (inf, -inf):
+                if observed_item == infinity_form:
+                    if observed_item == self.__ordinal:
+                        return self
+                    #
+                    return fromordinal(observed_item)
+                #
+            #
+        #
+        # +/- 0 corner case
+        if not delta:
+            return self
+        #
+        # Return a RealDate instance if possible
+        return fromordinal(self.__ordinal + delta)
+
+    def __add__(self: _GD, delta: int | float, /) -> _GD:
+        """gd_instance1 + number capability"""
+        return self._add_days(delta)
+
+    @overload
+    def __sub__(self: _GD, other: int | float, /) -> _GD: ...
+    @overload
+    def __sub__(self: _GD, other: _GD, /) -> int | float: ...
+    @final
+    def __sub__(self: _GD, other: _GD | 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 __repr__(self: _GD, /) -> str:
+        """String representation of the object"""
+        return f"{self.__class__.__name__}({repr(self.__ordinal)})"
+
+    def __str__(self: _GD, /) -> str:
+        """String display of the object"""
+        return self.isoformat()
+
+    def isoformat(self: _GD, /) -> str:
+        """Date representation in ISO format"""
+        return self.strftime(ISO_DATE_FORMAT)
+
+    def strftime(self: _GD, fmt: str, /) -> str:
+        """String representation of the date"""
+        raise NotImplementedError
+
+    def replace(self: _GD, /, year: int = 0, month: int = 0, day: int = 0) -> _GD:
+        """Return a copy with year, month, and/or date replaced"""
+        raise NotImplementedError
+
+
+class InfinityDate(GenericDate):
+    """Infinity Date object"""
+
+    def __init__(self, /, *, past_bound: bool = False) -> None:
+        """Store -inf or inf"""
+        ordinal = -inf if past_bound else inf
+        super().__init__(ordinal)
+
+    def __repr__(self, /) -> str:
+        """String representation of the object"""
+        return f"{self.__class__.__name__}(past_bound={self.toordinal() == -inf})"
+
+    def strftime(self, fmt: str, /) -> str:
+        """String representation of the date"""
+        if self.toordinal() == inf:
+            return INFINITE_DATE_DISPLAY
+        #
+        return NEGATIVE_INFINITE_DATE_DISPLAY
+
+    __format__ = strftime
+
+    def replace(self, /, year: int = 0, month: int = 0, day: int = 0):
+        """Not supported in this class"""
+        raise TypeError(
+            f"{self.__class__.__name__} instances do not support .replace()"
+        )
+
+
+# pylint: disable=too-many-instance-attributes
+class RealDate(GenericDate):
+    """Real (deterministic) Date object based on date"""
+
+    def __init__(self, year: int, month: int, day: int) -> None:
+        """Create a date-like object"""
+        self._wrapped_date_object = date(year, month, day)
+        self.year = year
+        self.month = month
+        self.day = day
+        super().__init__(float(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
+        self.isocalendar = self._wrapped_date_object.isocalendar
+        self.ctime = self._wrapped_date_object.ctime
+
+    def __bool__(self, /) -> bool:
+        """True if a real date is wrapped"""
+        return True
+
+    def __repr__(self, /) -> str:
+        """String representation of the object"""
+        return f"{self.__class__.__name__}({self.year}, {self.month}, {self.day})"
+
+    def strftime(self, fmt: str, /) -> str:
+        """String representation of the date"""
+        return self._wrapped_date_object.strftime(fmt or ISO_DATE_FORMAT)
+
+    __format__ = strftime
+
+    def replace(self, /, year: int = 0, month: int = 0, day: int = 0):
+        """Return a copy with year, month, and/or date replaced"""
+        internal_object = self._wrapped_date_object
+        return from_datetime_object(
+            internal_object.replace(
+                year=year or internal_object.year,
+                month=month or internal_object.month,
+                day=day or internal_object.day,
+            )
+        )
+
+
+# Absolute minimum and maximum dates
+MIN: Final[GenericDate] = InfinityDate(past_bound=True)
+MAX: Final[GenericDate] = InfinityDate(past_bound=False)
+
+
+# Factory functions
+
+
+def from_datetime_object(source: date | datetime, /) -> GenericDate:
+    """Create a new RealDate instance from a
+    date or datetime object
+    """
+    return RealDate(source.year, source.month, source.day)
+
+
+def from_native_type(
+    source: Any,
+    /,
+    *,
+    fmt: str = ISO_DATETIME_FORMAT_UTC,
+    past_bound: bool = False,
+) -> GenericDate:
+    """Create an InfinityDate or RealDate instance from string or another type,
+    assuming infinity in the latter case
+    """
+    if isinstance(source, str):
+        return from_datetime_object(datetime.strptime(source, fmt))
+    #
+    if source == -inf or source is None and past_bound:
+        return MIN
+    #
+    if source == inf or source is None and not past_bound:
+        return MAX
+    #
+    raise ValueError(f"Don’t know how to convert {source!r} into a date")
+
+
+def fromordinal(ordinal: float | int) -> GenericDate:
+    """Create an InfinityDate or RealDate instance from the provided ordinal"""
+    if ordinal == -inf:
+        return MIN
+    #
+    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
+    #
+    if not MIN_ORDINAL <= new_ordinal <= MAX_ORDINAL:
+        raise OverflowError("RealDate value out of range")
+    #
+    stdlib_date_object = date.fromordinal(new_ordinal)
+    return from_datetime_object(stdlib_date_object)
+
+
+def fromisoformat(source: str, /) -> GenericDate:
+    """Create an InfinityDate or RealDate instance from an iso format representation"""
+    lower_source_stripped = source.strip().lower()
+    if lower_source_stripped == INFINITE_DATE_DISPLAY:
+        return MAX
+    #
+    if lower_source_stripped == NEGATIVE_INFINITE_DATE_DISPLAY:
+        return MIN
+    #
+    return from_datetime_object(date.fromisoformat(source))
+
+
+def fromisocalendar(year: int, week: int, weekday: int) -> GenericDate:
+    """Create a RealDate instance from an iso calendar date"""
+    return from_datetime_object(date.fromisocalendar(year, week, weekday))
+
+
+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))