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

infdate/__init__.py

@@ -1,42 +1,37 @@
 # -*- coding: utf-8 -*-
 
 """
-infdate: a wrapper around standard library’s datetime.date objects,
-capable of representing positive and negative infinity
+infdate: a wrapper around the standard library’s datetime.date objects,
+capable of representing past and future infinity
 """
 
+import warnings
+
 from datetime import date, datetime
 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
+# Internal module constants:
+# TypeVar for GenericDate
 # -----------------------------------------------------------------------------
 
-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")
 
-RESOLUTION: Final[int] = 1
+_INFINITY_FORMS = (-inf, inf)
 
 
 # -----------------------------------------------------------------------------
-# Internal module constants:
-# TypeVar for GenericDate
+# Public module constants:
+# format strings
 # -----------------------------------------------------------------------------
 
-_GD = TypeVar("_GD", bound="GenericDate")
+INFINITE_PAST_DATE_DISPLAY: Final[str] = "<-inf>"
+INFINITE_FUTURE_DATE_DISPLAY: Final[str] = "<inf>"
+
+ISO_DATE_FORMAT: Final[str] = "%Y-%m-%d"
+ISO_DATETIME_FORMAT_UTC: Final[str] = f"{ISO_DATE_FORMAT}T%H:%M:%S.%fZ"
 
 
 # -----------------------------------------------------------------------------
@@ -49,7 +44,7 @@ class GenericDate:
 
     def __init__(self, ordinal: int | float, /) -> None:
         """Create a date-like object"""
-        if ordinal in (-inf, inf):
+        if ordinal in _INFINITY_FORMS:
             self.__ordinal = ordinal
         else:
             self.__ordinal = trunc(ordinal)
@@ -92,12 +87,14 @@ class GenericDate:
         return hash(f"date with ordinal {self.__ordinal}")
 
     def _add_days(self: _GD, delta: int | float, /):
-        """Add other, respecting maybe-nondeterministic values"""
+        """Add other, respecting maybe-nondeterministic values
+        (ie. -inf or inf)
+        """
         # 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):
+            for infinity_form in _INFINITY_FORMS:
                 if observed_item == infinity_form:
                     if observed_item == self.__ordinal:
                         return self
@@ -155,6 +152,18 @@ class GenericDate:
         """Return a copy with year, month, and/or date replaced"""
         raise NotImplementedError
 
+    def pretty(
+        self: _GD,
+        /,
+        *,
+        inf_common_prefix: str = "",
+        inf_past_suffix: str = "",
+        inf_future_suffix: str = "",
+        fmt: str = ISO_DATE_FORMAT,
+    ) -> str:
+        """Return the date, pretty printed"""
+        raise NotImplementedError
+
 
 class InfinityDate(GenericDate):
     """Infinity Date object"""
@@ -162,6 +171,7 @@ class InfinityDate(GenericDate):
     def __init__(self, /, *, past_bound: bool = False) -> None:
         """Store -inf or inf"""
         ordinal = -inf if past_bound else inf
+        self.__is_past = past_bound
         super().__init__(ordinal)
 
     def __repr__(self, /) -> str:
@@ -170,10 +180,10 @@ class InfinityDate(GenericDate):
 
     def strftime(self, fmt: str, /) -> str:
         """String representation of the date"""
-        if self.toordinal() == inf:
-            return INFINITE_DATE_DISPLAY
+        if self.__is_past:
+            return INFINITE_PAST_DATE_DISPLAY
         #
-        return NEGATIVE_INFINITE_DATE_DISPLAY
+        return INFINITE_FUTURE_DATE_DISPLAY
 
     __format__ = strftime
 
@@ -183,6 +193,25 @@ class InfinityDate(GenericDate):
             f"{self.__class__.__name__} instances do not support .replace()"
         )
 
+    @final
+    def pretty(
+        self,
+        /,
+        *,
+        inf_common_prefix: str = "",
+        inf_past_suffix: str = "",
+        inf_future_suffix: str = "",
+        # pylint:disable = unused-argument ; required by inheritance
+        fmt: str = ISO_DATE_FORMAT,
+    ) -> str:
+        """Return the date, pretty printed"""
+        if self.__is_past:
+            pretty_result = f"{inf_common_prefix}{inf_past_suffix}"
+        else:
+            pretty_result = f"{inf_common_prefix}{inf_future_suffix}"
+        #
+        return pretty_result or self.isoformat()
+
 
 # pylint: disable=too-many-instance-attributes
 class RealDate(GenericDate):
@@ -226,29 +255,78 @@ class RealDate(GenericDate):
             )
         )
 
+    @final
+    def pretty(
+        self,
+        /,
+        *,
+        inf_common_prefix: str = "",
+        inf_past_suffix: str = "",
+        inf_future_suffix: str = "",
+        fmt: str = ISO_DATE_FORMAT,
+    ) -> str:
+        """Return the date, pretty printed"""
+        return self.strftime(fmt)
+
+
+# -----------------------------------------------------------------------------
+# Private module functions
+# -----------------------------------------------------------------------------
+
+
+def _from_datetime_object(source: date | datetime, /) -> GenericDate:
+    """Create a new RealDate instance from a
+    date or datetime object (module-private function)
+    """
+    return RealDate(source.year, source.month, source.day)
+
 
 # -----------------------------------------------------------------------------
 # Public module constants continued:
-# absolute minimum and maximum dates
+# minimum and maximum dates and ordinals, resolution (one day)
 # -----------------------------------------------------------------------------
 
-MIN: Final[GenericDate] = InfinityDate(past_bound=True)
-MAX: Final[GenericDate] = InfinityDate(past_bound=False)
+
+INFINITE_PAST: Final[GenericDate] = InfinityDate(past_bound=True)
+INFINITE_FUTURE: Final[GenericDate] = InfinityDate(past_bound=False)
+
+MIN: Final[GenericDate] = INFINITE_PAST
+MAX: Final[GenericDate] = INFINITE_FUTURE
+
+REAL_MIN: Final[GenericDate] = _from_datetime_object(date.min)
+REAL_MAX: Final[GenericDate] = _from_datetime_object(date.max)
+
+MIN_ORDINAL: Final[int] = date.min.toordinal()
+MAX_ORDINAL: Final[int] = date.max.toordinal()
+
+RESOLUTION: Final[int] = 1
 
 
 # -----------------------------------------------------------------------------
-# Module-level factory functions
+# Public module-level factory functions
 # -----------------------------------------------------------------------------
 
 
-def from_datetime_object(source: date | datetime, /) -> GenericDate:
+def fromdatetime(source: date | datetime, /) -> GenericDate:
     """Create a new RealDate instance from a
     date or datetime object
     """
-    return RealDate(source.year, source.month, source.day)
+    return _from_datetime_object(source)
 
 
-def from_native_type(
+def from_datetime_object(source: date | datetime, /) -> GenericDate:
+    """Create a new RealDate instance from a
+    date or datetime object (deprecated function name)
+    """
+    warnings.warn(
+        "outdated function name, please use fromdatetime() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return fromdatetime(source)
+
+
+def fromnative(
     source: Any,
     /,
     *,
@@ -259,7 +337,7 @@ def from_native_type(
     assuming infinity in the latter case
     """
     if isinstance(source, str):
-        return from_datetime_object(datetime.strptime(source, fmt))
+        return _from_datetime_object(datetime.strptime(source, fmt))
     #
     if source == -inf or source is None and past_bound:
         return MIN
@@ -270,65 +348,63 @@ def from_native_type(
     raise ValueError(f"Don’t know how to convert {source!r} into a date")
 
 
+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 (deprecated function name)
+    """
+    warnings.warn(
+        "outdated function name, please use fromnative() instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return fromnative(source, fmt=fmt, past_bound=past_bound)
+
+
 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
+    if timestamp in _INFINITY_FORMS:
+        return INFINITE_PAST if timestamp == -inf else INFINITE_FUTURE
     #
     stdlib_date_object = date.fromtimestamp(timestamp)
-    return from_datetime_object(stdlib_date_object)
+    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
-    #
-    if ordinal == inf:
-        return MAX
+    if ordinal in _INFINITY_FORMS:
+        return INFINITE_PAST if ordinal == -inf else INFINITE_FUTURE
     #
     new_ordinal = trunc(ordinal)
     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)
-
-
-# -----------------------------------------------------------------------------
-# 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
-# -----------------------------------------------------------------------------
+    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 == INFINITE_FUTURE_DATE_DISPLAY:
+        return INFINITE_FUTURE
     #
-    if lower_source_stripped == NEGATIVE_INFINITE_DATE_DISPLAY:
-        return MIN
+    if lower_source_stripped == INFINITE_PAST_DATE_DISPLAY:
+        return INFINITE_PAST
     #
-    return from_datetime_object(date.fromisoformat(source))
+    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))
+    return _from_datetime_object(date.fromisocalendar(year, week, weekday))
 
 
 def today() -> GenericDate:
     """Today as RealDate object"""
-    return from_datetime_object(date.today())
+    return _from_datetime_object(date.today())

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infdate
-Version: 0.2.2
+Version: 0.2.4
 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
@@ -38,11 +38,11 @@ _Python module for date calculations implementing a concept of infinity_
 
 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.
+over the other classes for that purpose.
 
-**InfinityDate** can represent either positive or negative infinity.
-The module-level constants **MIN** and **MAX** contain the two possible
-**InfinityDate** instance variations.
+**InfinityDate** can represent either past or future infinity.
+The module-level constants **INFINITE_PAST** and **INFINITE_FUTURE**
+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.
@@ -57,14 +57,14 @@ infdate.MIN < infdate.REAL_MIN <= real_date_instance <= infdate.REAL_MAX < infda
 
 ### 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**
+*   **INFINITE_PAST** = **InfinityDate(**_past_bound_=`True`**)** → infinity before any date
+*   **INFINITE_FUTURE** = **InfinityDate(**_past_bound_=`False`**)** → infinity after any date
+*   **MIN** = **INFINITE_PAST**
+*   **MAX** = **INFINITE_FUTURE**
+*   **REAL_MIN** = **RealDate(**_`1`, `1`, `1`_**)** → the same date as **datetime.date.min**
+*   **REAL_MAX** = **RealDate(**_`9999`, `12`, `31`_**)** → the same date as **datetime.date.max**
+*   **MIN_ORDINAL** = `1` → the same value as **datetime.date.min.toordinal()**
+*   **MAX_ORDINAL** = `3652059` → the same value as **datetime.date.max.toordinal()**
 *   **RESOLUTION** = `1` → represents the lowest possible date difference: _one day_
 
 
@@ -81,21 +81,23 @@ are provided as module-level functions:
 
 Two additional factory functions are provided:
 
-*   **from_datetime_object()** to create a **RealDate** instance from a
+*   **fromdatetime()** to create a **RealDate** instance from a
     **datetime.date** or **datetime.datetime** instance
+    (deprecated old name: _from_datetime_object()_).
 
-*   **from_native_type()** to create an **InfinityDate** or **RealDate**
-    instance from a string, from **None**, **-math.inf** or **math.inf**.
+*   **fromnative()** to create an **InfinityDate** or **RealDate**
+    instance from a string, from **None**, **-math.inf** or **math.inf**
+    (deprecated old name: _from_native_type()_).
 
     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
+### Differences between the infdate module 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,
+*   infdate module 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**.
@@ -107,6 +109,9 @@ Some notable difference from the **datetime.date** class, mainly due to the desi
     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]).
 
+*   infdate module classes have a **.pretty()** method that can be used to format **RealDate** instances with a format string like **.strftime()** (provided with the _fmt_ argument that defaults to the ISO format `%Y-%m-%d`),
+    or to apply a custom format to **InfinityDate** classes using the _inf_common_prefix_, _inf_past_suffix_ and _inf_future_suffix_ arguments.
+
 
 ## Example usage
 
@@ -114,27 +119,25 @@ Some notable difference from the **datetime.date** class, mainly due to the desi
 >>> import infdate
 >>> today = infdate.today()
 >>> today
-RealDate(2025, 6, 27)
+RealDate(2025, 6, 30)
 >>> print(f"US date notation: {today:%m/%d/%y}")
-US date notation: 06/27/25
+US date notation: 06/30/25
 >>> today.ctime()
-'Fri Jun 27 00:00:00 2025'
+'Mon Jun 30 00:00:00 2025'
 >>> today.isocalendar()
-datetime.IsoCalendarDate(year=2025, week=26, weekday=5)
->>>
+datetime.IsoCalendarDate(year=2025, week=27, weekday=1)
 >>> yesterday = today - 1
 >>> yesterday.ctime()
-'Thu Jun 26 00:00:00 2025'
->>>
+'Sun Jun 29 00:00:00 2025'
 >>> today - yesterday
 1
->>> infdate.MIN
+>>> infdate.INFINITE_PAST
 InfinityDate(past_bound=True)
->>> infdate.MAX
+>>> infdate.INFINITE_FUTURE
 InfinityDate(past_bound=False)
->>> infdate.MAX - today
+>>> infdate.INFINITE_FUTURE - today
 inf
->>> infdate.MAX - infdate.MIN
+>>> infdate.INFINITE_FUTURE - infdate.INFINITE_PAST
 inf
 ```
 
@@ -145,6 +148,8 @@ Subtracting **InfinityDate** or **RealDate** and **datetime.date** instances fro
 ``` pycon
 >>> from datetime import date
 >>> stdlib_today = date.today()
+>>> stdlib_today
+datetime.date(2025, 6, 30)
 >>> today == stdlib_today
 True
 >>> yesterday < stdlib_today
@@ -153,7 +158,7 @@ True
 -1
 >>> stdlib_today - yesterday
 1
->>> stdlib_today - infdate.MIN
+>>> stdlib_today - infdate.INFINITE_PAST
 inf
 ```
 

infdate-0.2.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+infdate/__init__.py,sha256=IIJ8ZoTGNoBeFTt86_ysMCUVBj36r8vcqpReJa6EiUM,13523
+infdate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+infdate-0.2.4.dist-info/METADATA,sha256=O22fG8KKeSgLV2hDAN8pkM2JmKh4i-_yCX_glIlTGp8,6569
+infdate-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+infdate-0.2.4.dist-info/licenses/LICENSE,sha256=867pxriiObx28vCU1JsRtu3H9kUKyl54e0-xl1IIv3Y,913
+infdate-0.2.4.dist-info/RECORD,,

infdate-0.2.2.dist-info/RECORD

@@ -1,6 +0,0 @@
-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,,