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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-utils
-Version: 4.2.0
+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
@@ -37,6 +37,7 @@ Project-URL: Documentation, https://python-utils.readthedocs.io/
 Project-URL: Repository, https://github.com/WoLpH/python-utils
 Project-URL: Changelog, https://github.com/WoLpH/python-utils/releases
 Project-URL: Funding, https://github.com/sponsors/wolph
+Project-URL: Issues, https://github.com/wolph/python-utils/issues
 Provides-Extra: docs
 Provides-Extra: loguru
 Provides-Extra: tests

{python_utils-4.2.0 → python_utils-4.2.2}/_python_utils_tests/test_import.py

@@ -299,3 +299,106 @@ def test_import_global_requested_name_needs_an_export(
     import_.import_global(module_name, ['eggs'], locals_={}, globals_=scope)
     assert scope == {}
     assert 'eggs' not in calls
+
+
+@pytest.fixture
+def deep_package(
+    tmp_path: pathlib.Path, monkeypatch: pytest.MonkeyPatch
+) -> collections.abc.Iterator[str]:
+    """Create ``testrel.nested.deeper`` with importable helper modules."""
+    package: pathlib.Path = tmp_path / 'testrel'
+    nested: pathlib.Path = package / 'nested'
+    deeper: pathlib.Path = nested / 'deeper'
+    deeper.mkdir(parents=True)
+    (package / '__init__.py').write_text('', encoding='utf-8')
+    (nested / '__init__.py').write_text('', encoding='utf-8')
+    (deeper / '__init__.py').write_text('', encoding='utf-8')
+    (package / 'helper.py').write_text('value = 42\n', encoding='utf-8')
+    (nested / 'inner.py').write_text(
+        "inner_value = 'inner'\n", encoding='utf-8'
+    )
+    monkeypatch.setattr(sys, 'path', [str(tmp_path), *sys.path])
+
+    yield 'testrel'
+
+    imported: list[str] = [
+        name for name in sys.modules if name.split('.')[0] == 'testrel'
+    ]
+    for name in imported:
+        del sys.modules[name]
+
+
+def test_import_globals_relative_import_two_dots(deep_package: str) -> None:
+    """Resolve ``..helper`` two levels up, to ``testrel.helper`` (#73)."""
+    locals_: types.Dict[str, types.Any] = {}
+    globals_: types.Dict[str, types.Any] = {'__package__': 'testrel.nested'}
+    import_.import_global('..helper', locals_=locals_, globals_=globals_)
+    assert globals_['value'] == 42
+
+
+def test_import_globals_relative_import_three_dots(deep_package: str) -> None:
+    """Resolve ``...helper`` three levels up, to ``testrel.helper`` (#73)."""
+    locals_: types.Dict[str, types.Any] = {}
+    globals_: types.Dict[str, types.Any] = {
+        '__package__': 'testrel.nested.deeper'
+    }
+    import_.import_global('...helper', locals_=locals_, globals_=globals_)
+    assert globals_['value'] == 42
+
+
+def test_import_globals_relative_import_one_dot(deep_package: str) -> None:
+    """Keep resolving a single leading dot one level up (#73 control)."""
+    locals_: types.Dict[str, types.Any] = {}
+    globals_: types.Dict[str, types.Any] = {'__package__': 'testrel.nested'}
+    import_.import_global('.inner', locals_=locals_, globals_=globals_)
+    assert globals_['inner_value'] == 'inner'
+
+
+def test_import_globals_relative_import_dots_only(deep_package: str) -> None:
+    """Reject a dots-only name, which names no module to import (#73)."""
+    locals_: types.Dict[str, types.Any] = {}
+    globals_: types.Dict[str, types.Any] = {'__package__': 'testrel.nested'}
+    with pytest.raises(ImportError):
+        import_.import_global('..', locals_=locals_, globals_=globals_)
+
+
+def test_import_globals_relative_import_dots_only_exception(
+    deep_package: str,
+) -> None:
+    """Keep raising ModuleNotFoundError for a dots-only name, as 4.2.0 did."""
+    globals_: types.Dict[str, types.Any] = {
+        '__package__': 'testrel.nested.deeper'
+    }
+    error = import_.import_global(
+        '...',
+        exceptions=ModuleNotFoundError,
+        locals_={},
+        globals_=globals_,
+    )
+    assert isinstance(error, ModuleNotFoundError)
+
+
+def test_import_globals_relative_import_beyond_top_level(
+    deep_package: str,
+) -> None:
+    """Raise ModuleNotFoundError above the top-level package, as 4.2.0 did."""
+    globals_: types.Dict[str, types.Any] = {
+        '__package__': 'testrel.nested.deeper'
+    }
+    with pytest.raises(ModuleNotFoundError, match='beyond top-level'):
+        import_.import_global('....helper', locals_={}, globals_=globals_)
+
+
+def test_import_globals_empty_name() -> None:
+    """Keep raising IndexError for an empty name, as 4.2.0 did."""
+    with pytest.raises(IndexError):
+        import_.import_global('', locals_={}, globals_={'__package__': ''})
+
+
+def test_import_globals_relative_import_trailing_dot(
+    deep_package: str,
+) -> None:
+    """Raise ModuleNotFoundError for ``..helper.``, as 4.2.0 did."""
+    globals_: types.Dict[str, types.Any] = {'__package__': 'testrel.nested'}
+    with pytest.raises(ModuleNotFoundError):
+        import_.import_global('..helper.', locals_={}, globals_=globals_)

{python_utils-4.2.0 → 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.0 → python_utils-4.2.2}/pyproject.toml

@@ -70,6 +70,7 @@ doctest_optionflags = [
     "ALLOW_BYTES",
 ]
 asyncio_mode = "strict"
+asyncio_default_fixture_loop_scope = "function"
 xfail_strict = true
 filterwarnings = [
     "error",
@@ -125,7 +126,7 @@ source-include = [
 
 [project]
 name = "python-utils"
-version = "4.2.0"
+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"
@@ -168,6 +169,7 @@ Documentation = "https://python-utils.readthedocs.io/"
 Repository = "https://github.com/WoLpH/python-utils"
 Changelog = "https://github.com/WoLpH/python-utils/releases"
 Funding = "https://github.com/sponsors/wolph"
+Issues = "https://github.com/wolph/python-utils/issues"
 
 [project.optional-dependencies]
 loguru = ["loguru"]

{python_utils-4.2.0 → 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.0" # 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'
@@ -52,6 +52,7 @@ Documentation = 'https://python-utils.readthedocs.io/'
 Repository = 'https://github.com/WoLpH/python-utils'
 Changelog = 'https://github.com/WoLpH/python-utils/releases'
 Funding = 'https://github.com/sponsors/wolph'
+Issues = 'https://github.com/wolph/python-utils/issues'
 
 [project.optional-dependencies]
 loguru = ['loguru']
@@ -124,6 +125,9 @@ addopts = [
 ]
 doctest_optionflags = ['ALLOW_UNICODE', 'ALLOW_BYTES']
 asyncio_mode = 'strict'
+# pytest-asyncio 1.4 warns when this is unset, and filterwarnings turns the
+# warning into an INTERNALERROR. 'function' is the scope it already used.
+asyncio_default_fixture_loop_scope = 'function'
 xfail_strict = true
 filterwarnings = [
     'error',

{python_utils-4.2.0 → python_utils-4.2.2}/python_utils/import_.py

@@ -113,24 +113,44 @@ def import_global(  # noqa: C901
                 globals_ = frame.f_globals
 
         try:
-            # Relative imports are supported (from .spam import eggs)
+            # Relative imports are supported (from .spam import eggs). Each
+            # leading dot counts as one level, so ``..spam`` goes up two.
+            # An empty or dots-only name keeps the one-level path it had in
+            # 4.2.0, and with it the IndexError or ModuleNotFoundError.
+            multi_dot: bool = False
             if not name_parts[0]:
-                name_parts = name_parts[1:]
-                level = 1
-
-            # raise IOError((name, level))
-            module = __import__(
-                name=name_parts[0] or '.',
-                globals=globals_,
-                locals=locals_,
-                fromlist=name_parts[1:],
-                level=max(level, 0),
-            )
-
-            # Make sure we get the right part of a dotted import (i.e.
-            # spam.eggs should return eggs, not spam)
-            for attr in name_parts[1:]:
-                module = _get_attribute(module, attr, '.'.join(name_parts))
+                remainder: str = name.lstrip('.')
+                dots: int = len(name) - len(remainder)
+                if dots > 1 and remainder:
+                    multi_dot = True
+                    level = dots
+                    name_parts = remainder.split('.')
+                else:
+                    name_parts = name_parts[1:]
+                    level = 1
+
+            try:
+                module = __import__(
+                    name=name_parts[0] or '.',
+                    globals=globals_,
+                    locals=locals_,
+                    fromlist=name_parts[1:],
+                    level=max(level, 0),
+                )
+
+                # Make sure we get the right part of a dotted import (i.e.
+                # spam.eggs should return eggs, not spam)
+                for attr in name_parts[1:]:
+                    module = _get_attribute(module, attr, '.'.join(name_parts))
+            except ImportError as error:
+                # Every multi-dot name failed with ModuleNotFoundError in
+                # 4.2.0. Python raises a plain ImportError for some of them,
+                # such as going above the top-level package, which
+                # `except ModuleNotFoundError` misses. The subclass is
+                # caught by both.
+                if not multi_dot or isinstance(error, ModuleNotFoundError):
+                    raise
+                raise ModuleNotFoundError(str(error), name=name) from error
 
             # If no list of modules is given, autodetect from either __all__
             # or a dir() of the module

{python_utils-4.2.0 → 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: