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

infdate/__init__.py

@@ -10,6 +10,11 @@ from math import inf
 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>"
 
@@ -24,9 +29,19 @@ MIN_ORDINAL: Final[int] = date.min.toordinal()
 MAX_ORDINAL: Final[int] = date.max.toordinal()
 
 
+# -----------------------------------------------------------------------------
+# Internal module constants:
+# TypeVar for GenericDate
+# -----------------------------------------------------------------------------
+
 _GD = TypeVar("_GD", bound="GenericDate")
 
 
+# -----------------------------------------------------------------------------
+# Classes
+# -----------------------------------------------------------------------------
+
+
 class GenericDate:
     """Base Date object derived from an ordinal"""
 
@@ -204,12 +219,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,6 +262,18 @@ def from_native_type(
     raise ValueError(f"Don’t know how to convert {source!r} into a date")
 
 
+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: float | int) -> GenericDate:
     """Create an InfinityDate or RealDate instance from the provided ordinal"""
     if ordinal == -inf:
@@ -261,6 +294,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 +328,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.0.dist-info → infdate-0.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: infdate
-Version: 0.2.0
+Version: 0.2.1
 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
@@ -28,38 +28,41 @@ _Python module for date calculations implementing a concept of infinity_
 
 ## Module description
 
-Class hierarchy:
+### Classes overview
 
     └── GenericDate
         ├── InfinityDate
         └── RealDate
 
 
+The base class **GenericDate** should not be instantiated but can be used as a type annotation.
 
 **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.
+**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.RealDate(1, 1, 1) <= real_date_instance <= infdate.RealDate(9999, 12, 31) < infdate.MAX
+infdate.MIN < infdate.REAL_MIN <= real_date_instance <= infdate.REAL_MAX < infdate.MAX
 ```
 
+### 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()**
 
-**fromtimestamp()** is still missing by mistake.
-
-Two additional factory functions are provided in the module:
+Two additional factory functions are provided:
 
 *   **from_datetime_object()** to create a **RealDate** instance from a
     **datetime.date** or **datetime.datetime** instance
@@ -70,18 +73,20 @@ Two additional factory functions are provided in the module:
     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:
+
+### 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):
 
 *   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.
+*   Subtracting a date from an **InfinityDate** or **RealDate** always returns a float instead of a **datetime.timedelta** instance.
 
 *   Likewise, you cannot add or subtract **datetime.timedelta** instances
-    from n **InfinityDate** or **RealDate**, only **loat** or **int**.
+    from an **InfinityDate** or **RealDate**, only **float** or **int** (support for adding and subtracting datetime.timedelta instances might be added in the future).
 
 
 ## Example usage
@@ -116,10 +121,10 @@ inf
 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**):
+**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()
@@ -137,5 +142,6 @@ still gives a **TypeError**):
     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.1.dist-info/RECORD

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

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,,