perf: defer typing_extensions and lazy __version__ to keep imports light

Builds on the lazy package init: removes typing_extensions from the submodule
import path and defers __version__.

- Add stdlib-only python_utils/_aliases.py holding the lightweight type aliases;
  python_utils.types re-exports them (explicit `X as X` idiom) and keeps its
  eager typing_extensions facade + runtime overrides unchanged.
- Rewire time/converters/formatters/generators/import_ off python_utils.types
  onto _aliases, so importing them no longer pulls typing_extensions.
- Move logger's only typing_extensions use (Logged.__new__ -> Self) into
  TYPE_CHECKING (Self is a new addition; runtime introspection of __new__'s
  return type is not a compat obligation).
- Make python_utils.__version__ lazy via the PEP 562 __getattr__ so bare
  `import python_utils` no longer calls importlib.metadata.version()
  (~89 -> ~8 modules added to sys.modules).
- Add a deterministic import-footprint regression gate + get_type_hints smoke.

Public API verified byte-identical to develop via an export/signature manifest
diff, except: (a) aio_timeout_generator's default iterable (from the lazy
asyncio change) and (b) converters' raw __annotations__ strings now name the
bare aliases (get_type_hints resolves identically). `from __future__ import
annotations` is limited to where required (logger, containers) so
inspect.signature keeps returning evaluated type objects elsewhere. The
undocumented python_utils.<submodule>.types re-export attribute is removed.

Author: wolph

_python_utils_tests/test_aliases.py

@@ -0,0 +1,58 @@
+"""The lightweight alias module must define the public type aliases without
+pulling in typing_extensions, so importers stay light.
+"""
+
+import os
+import subprocess
+import sys
+
+
+def test_aliases_do_not_import_typing_extensions() -> None:
+    result = subprocess.run(
+        [
+            sys.executable,
+            '-c',
+            'import sys, python_utils._aliases\n'
+            "assert 'typing_extensions' not in sys.modules\n",
+        ],
+        capture_output=True,
+        text=True,
+        env={**os.environ, 'PYTHONPATH': os.pathsep.join(sys.path)},
+    )
+    assert result.returncode == 0, result.stderr
+
+
+def test_aliases_values() -> None:
+    from python_utils import _aliases
+
+    assert _aliases.Number == (int | float)
+    assert _aliases.delta_type == (
+        __import__('datetime').timedelta | int | float
+    )
+    assert set(_aliases.__all__) == {
+        'Scope',
+        'OptionalScope',
+        'Number',
+        'DecimalNumber',
+        'ExceptionType',
+        'ExceptionsType',
+        'StringTypes',
+        'delta_type',
+        'timestamp_type',
+    }
+
+
+def test_types_reexports_aliases_identically() -> None:
+    from python_utils import _aliases, types
+
+    for name in _aliases.__all__:
+        assert getattr(types, name) is getattr(_aliases, name), name
+
+
+def test_types_still_exposes_typing_extensions_surface() -> None:
+    # The facade must keep re-exporting typing_extensions (e.g. Self).
+    # ``hasattr`` (not ``types.Self``) avoids basedpyright's
+    # reportUnknownMemberType, since the wildcard re-export has no static type.
+    from python_utils import types
+
+    assert hasattr(types, 'Self')

_python_utils_tests/test_import_footprint.py

@@ -0,0 +1,101 @@
+"""Deterministic import-footprint regression gate.
+
+Each target module is imported in a clean subprocess; a per-target denylist of
+heavy modules must be absent from sys.modules afterward. This is the CI
+performance guard: it fails the moment an eager heavy import is reintroduced.
+"""
+
+import json
+import os
+import subprocess
+import sys
+
+import pytest
+
+# (import target, modules that must be ABSENT from sys.modules afterward)
+FOOTPRINT_CASES = [
+    ('python_utils', ('typing_extensions', 'asyncio')),
+    ('python_utils.time', ('typing_extensions', 'asyncio')),
+    ('python_utils.logger', ('typing_extensions',)),
+    ('python_utils.converters', ('typing_extensions', 'asyncio')),
+    ('python_utils.formatters', ('typing_extensions', 'asyncio')),
+    ('python_utils.import_', ('typing_extensions', 'asyncio')),
+    ('python_utils.terminal', ('typing_extensions',)),
+    ('python_utils.containers', ('typing_extensions', 'asyncio')),
+    ('python_utils.decorators', ('typing_extensions', 'asyncio')),
+    ('python_utils.exceptions', ('typing_extensions', 'asyncio')),
+    # aio, generators legitimately use asyncio; only typing_extensions denied.
+    ('python_utils.aio', ('typing_extensions',)),
+    ('python_utils.generators', ('typing_extensions',)),
+]
+
+
+def _modules_after_import(target: str) -> set[str]:
+    result = subprocess.run(
+        [
+            sys.executable,
+            '-c',
+            f'import sys, {target}\n'
+            'import json\n'
+            'print(json.dumps(sorted(sys.modules)))\n',
+        ],
+        capture_output=True,
+        text=True,
+        env={**os.environ, 'PYTHONPATH': os.pathsep.join(sys.path)},
+    )
+    assert result.returncode == 0, result.stderr
+
+    return set(json.loads(result.stdout))
+
+
+@pytest.mark.parametrize(('target', 'denied'), FOOTPRINT_CASES)
+def test_import_footprint(target: str, denied: tuple[str, ...]) -> None:
+    present = _modules_after_import(target)
+    leaked = [m for m in denied if m in present]
+    assert not leaked, f'{target} eagerly imported {leaked}'
+
+
+def test_bare_import_module_count_under_budget() -> None:
+    # Coarse bloat tripwire (denylist above is the real guard). Cap tightened
+    # now that __version__ is lazy (importlib.metadata no longer pulled on bare
+    # import). Bump only if a new Python version legitimately adds startup
+    # modules. Measures modules ADDED by importing python_utils.
+    added = len(_modules_after_import('python_utils')) - len(
+        _modules_after_import('sys')
+    )
+    assert added < 40, f'python_utils added {added} modules to sys.modules'
+
+
+def test_bare_import_does_not_pull_importlib_metadata() -> None:
+    # __version__ is resolved lazily; bare import must not call
+    # importlib.metadata.version() (which drags in email/zipfile/json/...).
+    present = _modules_after_import('python_utils')
+    assert 'importlib.metadata' not in present
+
+
+def test_version_resolves_correctly() -> None:
+    import python_utils
+
+    assert isinstance(python_utils.__version__, str)
+    assert python_utils.__version__  # non-empty
+
+
+PUBLIC_CALLABLES_TO_INTROSPECT = [
+    ('python_utils.time', 'timeout_generator'),
+    ('python_utils.time', 'aio_timeout_generator'),
+    ('python_utils.time', 'format_time'),
+    ('python_utils.converters', 'remap'),
+    ('python_utils.converters', 'to_int'),
+    ('python_utils.formatters', 'timesince'),
+    ('python_utils.import_', 'import_global'),
+]
+
+
+@pytest.mark.parametrize(('module', 'name'), PUBLIC_CALLABLES_TO_INTROSPECT)
+def test_get_type_hints_still_resolves(module: str, name: str) -> None:
+    import importlib
+    import typing
+
+    obj = getattr(importlib.import_module(module), name)
+    # Must not raise NameError now that type imports moved/changed.
+    typing.get_type_hints(obj)

python_utils/__init__.py

@@ -61,8 +61,6 @@
 import importlib as _importlib
 import typing as _typing
 
-from .__about__ import __version__
-
 if _typing.TYPE_CHECKING:  # pragma: no cover
     # Eager imports for type checkers only; the runtime equivalents are loaded
     # lazily by ``__getattr__`` below. Names appear in ``__all__`` so they are
@@ -79,6 +77,7 @@
         time,
         types,
     )
+    from .__about__ import __version__
     from .aio import acount
     from .containers import CastedDict, LazyCastedDict, UniqueList
     from .converters import (
@@ -127,6 +126,7 @@
 
 #: Exported name -> submodule it lives in.
 _NAME_TO_MODULE: dict[str, str] = {
+    '__version__': '__about__',
     'acount': 'aio',
     'CastedDict': 'containers',
     'LazyCastedDict': 'containers',

python_utils/_aliases.py

@@ -0,0 +1,43 @@
+"""Lightweight, stdlib-only type aliases shared across python_utils.
+
+These live here (rather than in ``python_utils.types``) so internal modules can
+import them without dragging in ``typing_extensions``. ``python_utils.types``
+re-exports everything defined here, so the public names are unchanged.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+from typing import Any
+
+__all__ = [
+    'DecimalNumber',
+    'ExceptionType',
+    'ExceptionsType',
+    'Number',
+    'OptionalScope',
+    'Scope',
+    'StringTypes',
+    'delta_type',
+    'timestamp_type',
+]
+
+Scope = dict[str, Any]
+OptionalScope = Scope | None
+Number = int | float
+DecimalNumber = Number | decimal.Decimal
+ExceptionType = type[Exception]
+ExceptionsType = tuple[ExceptionType, ...] | ExceptionType
+StringTypes = str | bytes
+
+delta_type = datetime.timedelta | int | float
+timestamp_type = (
+    datetime.timedelta
+    | datetime.date
+    | datetime.datetime
+    | str
+    | int
+    | float
+    | None
+)

python_utils/containers.py

@@ -54,6 +54,8 @@
     SliceableDeque([2, 3, 4])
 """
 
+from __future__ import annotations
+
 # pyright: reportIncompatibleMethodOverride=false
 import abc
 import collections
@@ -534,11 +536,11 @@ class SliceableDeque(typing.Generic[T], collections.deque[T]):
     def __getitem__(self, index: typing.SupportsIndex) -> T: ...
 
     @typing.overload
-    def __getitem__(self, index: slice) -> 'SliceableDeque[T]': ...
+    def __getitem__(self, index: slice) -> SliceableDeque[T]: ...
 
     def __getitem__(
         self, index: typing.SupportsIndex | slice
-    ) -> T | 'SliceableDeque[T]':
+    ) -> T | SliceableDeque[T]:
         """
         Return the item or slice at the given index.
 

python_utils/converters.py

@@ -20,9 +20,14 @@
 import re
 import typing
 
-from . import types
+from python_utils._aliases import (
+    DecimalNumber,
+    ExceptionsType,
+    Number,
+    StringTypes,
+)
 
-_TN = typing.TypeVar('_TN', bound=types.DecimalNumber)
+_TN = typing.TypeVar('_TN', bound=DecimalNumber)
 
 _RegexpType: typing.TypeAlias = (
     re.Pattern[str] | str | typing.Literal[True] | None
@@ -32,7 +37,7 @@
 def to_int(
     input_: str | None = None,
     default: int = 0,
-    exception: types.ExceptionsType = (ValueError, TypeError),
+    exception: ExceptionsType = (ValueError, TypeError),
     regexp: _RegexpType = None,
 ) -> int:
     r"""
@@ -120,9 +125,9 @@ def to_int(
 def to_float(
     input_: str,
     default: int = 0,
-    exception: types.ExceptionsType = (ValueError, TypeError),
+    exception: ExceptionsType = (ValueError, TypeError),
     regexp: _RegexpType = None,
-) -> types.Number:
+) -> Number:
     r"""
     Convert the given `input_` to an integer or return default.
 
@@ -192,7 +197,7 @@ def to_float(
 
 
 def to_unicode(
-    input_: types.StringTypes,
+    input_: StringTypes,
     encoding: str = 'utf-8',
     errors: str = 'replace',
 ) -> str:
@@ -222,7 +227,7 @@ def to_unicode(
 
 
 def to_str(
-    input_: types.StringTypes,
+    input_: StringTypes,
     encoding: str = 'utf-8',
     errors: str = 'replace',
 ) -> bytes:
@@ -252,9 +257,9 @@ def to_str(
 
 
 def scale_1024(
-    x: types.Number,
+    x: Number,
     n_prefixes: int,
-) -> tuple[types.Number, types.Number]:
+) -> tuple[Number, Number]:
     """Scale a number down to a suitable size, based on powers of 1024.
 
     Returns the scaled number and the power of 1024 used.
@@ -414,7 +419,7 @@ def remap(  # pyright: ignore[reportInconsistentOverload]
         passed parameters are a `float`, otherwise the returned type will be
         `int`.
     """
-    type_: type[types.DecimalNumber]
+    type_: type[DecimalNumber]
     if (
         isinstance(value, decimal.Decimal)
         or isinstance(old_min, decimal.Decimal)

python_utils/formatters.py

@@ -13,7 +13,7 @@
 import datetime
 import typing
 
-from python_utils import types
+from python_utils._aliases import OptionalScope
 
 
 def camel_to_underscore(name: str) -> str:
@@ -56,9 +56,9 @@ def camel_to_underscore(name: str) -> str:
 
 def apply_recursive(
     function: collections.abc.Callable[[str], str],
-    data: types.OptionalScope = None,
+    data: OptionalScope = None,
     **kwargs: typing.Any,
-) -> types.OptionalScope:
+) -> OptionalScope:
     """
     Apply a function to all keys in a scope recursively.