python-utils 4.2.1__tar.gz → 4.2.2__tar.gz

{python_utils-4.2.1 → python_utils-4.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-utils
-Version: 4.2.1
+Version: 4.2.2
 Summary: Python Utils is a module with some convenient utilities not included with the standard Python install
 Keywords: utils,utilities,helpers,typing,typed,async,lazy-imports
 Author: Rick van Hattem

{python_utils-4.2.1 → python_utils-4.2.2}/_python_utils_tests/test_time.py

@@ -4,6 +4,7 @@ import asyncio
 import datetime
 import itertools
 import time
+from types import SimpleNamespace
 
 import pytest
 
@@ -465,6 +466,137 @@ def test_format_time_extreme_timedeltas() -> None:
     assert smallest == '-999999999 days, 0:00:00'
 
 
+@pytest.mark.parametrize(
+    'value,precision,expected',
+    [
+        (
+            datetime.datetime(1960, 1, 2, 3, 4, 5, 678901),
+            datetime.timedelta(seconds=1),
+            '1960-01-02 03:04:05',
+        ),
+        (
+            datetime.datetime(1900, 1, 2, 3, 4, 5, 678901),
+            datetime.timedelta(milliseconds=10),
+            '1900-01-02 03:04:05.670000',
+        ),
+        (
+            datetime.datetime.min,
+            datetime.timedelta(seconds=1),
+            '0001-01-01 00:00:00',
+        ),
+        (
+            datetime.datetime.max,
+            datetime.timedelta(seconds=1),
+            '9999-12-31 23:59:59',
+        ),
+    ],
+)
+def test_format_time_outside_platform_timestamp_range(
+    value: datetime.datetime,
+    precision: datetime.timedelta,
+    expected: str,
+) -> None:
+    """Format valid naive dates outside the platform's timestamp range."""
+    assert python_utils.format_time(value, precision) == expected
+
+
+class _NoTimestamp(datetime.datetime):
+    """A datetime whose platform cannot give it a timestamp."""
+
+    def timestamp(self) -> float:
+        """Fail the way an out-of-range platform conversion does."""
+        raise ValueError('year 0 is out of range')
+
+
+@pytest.mark.parametrize(
+    'precision',
+    [datetime.timedelta(0), 1, datetime.timedelta(days=999_999_999)],
+)
+def test_format_time_keeps_timestamp_error_without_wall_clock(
+    precision: datetime.timedelta,
+) -> None:
+    """Raise the 4.2.1 error when exact arithmetic cannot help either."""
+    with pytest.raises(ValueError, match='year 0 is out of range'):
+        python_utils.format_time(_NoTimestamp(1, 1, 1), precision)
+
+
+def test_format_time_keeps_timestamp_error_for_subclasses() -> None:
+    """A subclass that cannot give a timestamp raises, as in 4.2.1."""
+    with pytest.raises(ValueError, match='year 0 is out of range'):
+        python_utils.format_time(_NoTimestamp(1, 1, 1))
+
+
+def test_format_time_keeps_timestamp_error_for_aware() -> None:
+    """Aware datetimes without a timestamp raise, as in 4.2.1."""
+    value = _NoTimestamp(2000, 1, 1, tzinfo=datetime.timezone.utc)
+    with pytest.raises(ValueError, match='year 0 is out of range'):
+        python_utils.format_time(value)
+
+
+def test_format_time_keeps_max_when_wall_clock_overflows(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Return the 4.2.1 maximum when neither conversion can format it."""
+
+    class NoFromTimestamp(datetime.datetime):
+        """Simulate a platform unable to convert the timestamp back."""
+
+        @classmethod
+        def fromtimestamp(
+            cls, timestamp: float, tz: datetime.tzinfo | None = None
+        ) -> 'NoFromTimestamp':
+            """Reject every timestamp."""
+            raise ValueError('year 0 is out of range')
+
+    monkeypatch.setattr(
+        python_utils.time,
+        'datetime',
+        SimpleNamespace(
+            datetime=NoFromTimestamp,
+            timedelta=datetime.timedelta,
+            date=datetime.date,
+        ),
+    )
+    value = NoFromTimestamp(1, 1, 2)
+    result = python_utils.format_time(value, datetime.timedelta(days=7))
+    assert result == str(datetime.datetime.max)
+
+
+@pytest.mark.parametrize('error', [OverflowError, OSError, ValueError])
+@pytest.mark.parametrize('tzinfo', [None, datetime.timezone.utc])
+def test_format_time_unavailable_fromtimestamp(
+    monkeypatch: pytest.MonkeyPatch,
+    error: type[Exception],
+    tzinfo: datetime.tzinfo | None,
+) -> None:
+    """Handle platform conversion failures on systems with a wider range."""
+
+    class LimitedDatetime(datetime.datetime):
+        """Simulate a platform unable to convert the timestamp back."""
+
+        @classmethod
+        def fromtimestamp(
+            cls, timestamp: float, tz: datetime.tzinfo | None = None
+        ) -> 'LimitedDatetime':
+            """Reject dates outside the simulated platform range."""
+            raise error('timestamp out of range')
+
+    value = LimitedDatetime(2000, 1, 2, 3, 4, 5, 678901, tzinfo=tzinfo)
+    monkeypatch.setattr(
+        python_utils.time,
+        'datetime',
+        SimpleNamespace(
+            datetime=LimitedDatetime,
+            timedelta=datetime.timedelta,
+            date=datetime.date,
+        ),
+    )
+    expected = (
+        '2000-01-02 03:04:05' if tzinfo is None else str(datetime.datetime.max)
+    )
+    assert python_utils.format_time(value) == expected
+
+
 @pytest.mark.parametrize(
     'delta',
     [

{python_utils-4.2.1 → python_utils-4.2.2}/pyproject.toml

@@ -126,7 +126,7 @@ source-include = [
 
 [project]
 name = "python-utils"
-version = "4.2.1"
+version = "4.2.2"
 description = "Python Utils is a module with some convenient utilities not included with the standard Python install"
 readme = "README.md"
 requires-python = ">=3.10"

{python_utils-4.2.1 → python_utils-4.2.2}/pyproject.toml.orig

@@ -12,7 +12,7 @@ source-include = ['_python_utils_tests/**/*.py', 'conftest.py', 'tox.ini']
 
 [project]
 name = 'python-utils'
-version = "4.2.1" # static; the single source of truth. Bump via `uv version`.
+version = "4.2.2" # static; the single source of truth. Bump via `uv version`.
 description = 'Python Utils is a module with some convenient utilities not included with the standard Python install'
 readme = 'README.md'
 requires-python = '>=3.10'

{python_utils-4.2.1 → python_utils-4.2.2}/python_utils/time.py

@@ -110,6 +110,49 @@ def delta_to_seconds_or_none(
         return delta_to_seconds(interval)
 
 
+def _format_wall_clock(
+    timestamp: datetime.datetime, precision: datetime.timedelta
+) -> str | None:
+    """Truncate a naive datetime by exact arithmetic, None when it cannot.
+
+    Windows cannot convert pre-epoch naive dates to timestamps, and no
+    platform converts the datetime bounds. Wall-clock arithmetic relative
+    to the naive epoch handles both. Aware datetimes, subclasses (whose
+    own arithmetic and ``__str__`` may differ), precisions that are not a
+    usable timedelta and results outside the datetime range give None, so
+    the caller keeps the 4.2.1 outcome for them.
+    """
+    if (
+        type(timestamp) is not datetime.datetime
+        or timestamp.tzinfo is not None
+    ):
+        return None
+    try:
+        return str(timestamp - (timestamp - epoch) % precision)
+    except (ArithmeticError, TypeError, ValueError):
+        return None
+
+
+def _format_datetime(
+    timestamp: datetime.datetime, precision: datetime.timedelta
+) -> str:
+    """Format a datetime even outside the platform's timestamp range."""
+    try:
+        since_epoch = datetime.timedelta(seconds=timestamp.timestamp())
+        seconds = (since_epoch - since_epoch % precision).total_seconds()
+    except (OverflowError, OSError, ValueError):
+        # 4.2.1 raised here, which stays the answer without a wall clock.
+        wall_clock: str | None = _format_wall_clock(timestamp, precision)
+        if wall_clock is None:
+            raise
+        return wall_clock
+    try:
+        return str(datetime.datetime.fromtimestamp(seconds))
+    except (OverflowError, OSError, ValueError):
+        wall_clock = _format_wall_clock(timestamp, precision)
+        return str(datetime.datetime.max) if wall_clock is None else wall_clock
+
+
 def format_time(
     timestamp: _aliases.timestamp_type,
     precision: datetime.timedelta = datetime.timedelta(seconds=1),
@@ -124,6 +167,8 @@ def format_time(
     '0:00:01'
     >>> format_time(datetime.datetime(2000, 1, 2, 3, 4, 5, 6))
     '2000-01-02 03:04:05'
+    >>> format_time(datetime.datetime(1900, 1, 2, 3, 4, 5))
+    '1900-01-02 03:04:05'
     >>> format_time(datetime.date(2000, 1, 2))
     '2000-01-02'
     >>> format_time(datetime.timedelta(seconds=3661))
@@ -152,23 +197,8 @@ def format_time(
         # whole microseconds, which keeps the modulo exact. In float seconds
         # `1.0 % 0.1` is just under 0.1 and the result drops a whole step.
         return str(timestamp - timestamp % precision)
-    elif isinstance(timestamp, datetime.datetime):  # pragma: no cover
-        # Python 2 doesn't have the timestamp method
-        if hasattr(timestamp, 'timestamp'):
-            seconds = timestamp.timestamp()
-        else:
-            seconds = timedelta_to_seconds(timestamp - epoch)
-
-        # Truncate the number to the given precision, in whole microseconds
-        # for the same reason as above
-        since_epoch: datetime.timedelta = datetime.timedelta(seconds=seconds)
-        seconds = (since_epoch - since_epoch % precision).total_seconds()
-
-        try:  # pragma: no cover
-            dt = datetime.datetime.fromtimestamp(seconds)
-        except (ValueError, OSError):  # pragma: no cover
-            dt = datetime.datetime.max
-        return str(dt)
+    elif isinstance(timestamp, datetime.datetime):
+        return _format_datetime(timestamp, precision)
     elif isinstance(timestamp, datetime.date):
         return str(timestamp)
     elif timestamp is None: