Defer asyncio and typing_extensions imports (lazy package init)

_python_utils_tests/test_aliases.py

@@ -0,0 +1,57 @@
+"""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:
+    code = (
+        'import sys, python_utils._aliases\n'
+        "assert 'typing_extensions' not in sys.modules\n"
+    )
+    result = subprocess.run(
+        [sys.executable, '-c', code],
+        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,100 @@
+"""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]:
+    code = (
+        f'import sys, {target}\n'
+        'import json\n'
+        'print(json.dumps(sorted(sys.modules)))\n'
+    )
+    result = subprocess.run(
+        [sys.executable, '-c', code],
+        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_tests/test_lazy_imports.py

@@ -0,0 +1,96 @@
+"""Tests for the lazy-import machinery that keeps `import python_utils` light
+(PEP 562 `__getattr__`/`__dir__` in the package, deferred ``asyncio`` in
+``python_utils.time``).
+"""
+
+import collections.abc
+import os
+import subprocess
+import sys
+
+import pytest
+
+import python_utils
+
+
+def _run_clean(code: str) -> subprocess.CompletedProcess[str]:
+    # Run in a fresh interpreter: the test session itself has long since
+    # imported asyncio/typing_extensions, so in-process checks are useless.
+    env = {**os.environ, 'PYTHONPATH': os.pathsep.join(sys.path)}
+    return subprocess.run(
+        [sys.executable, '-c', code],
+        capture_output=True,
+        text=True,
+        env=env,
+    )
+
+
+def test_package_lazy_attribute_access() -> None:
+    # Submodule access and exported-name access both resolve via __getattr__.
+    aio = python_utils.aio
+    assert python_utils.aio is aio  # repeated access returns the cached module
+    assert callable(python_utils.acount)
+    assert isinstance(python_utils.__version__, str)
+    missing = 'definitely_not_a_real_attribute'
+    with pytest.raises(AttributeError):
+        getattr(python_utils, missing)
+
+
+def test_bare_import_stays_light() -> None:
+    # Importing the package must not eagerly pull in heavy/optional deps.
+    result = _run_clean(
+        'import sys, python_utils\n'
+        "assert 'asyncio' not in sys.modules, "
+        "sorted(m for m in sys.modules if m.startswith('asyncio'))\n"
+        "assert 'typing_extensions' not in sys.modules\n"
+    )
+    assert result.returncode == 0, result.stderr
+
+
+def test_importing_time_submodule_avoids_asyncio() -> None:
+    # Importing python_utils.time for its synchronous helpers must not import
+    # asyncio; the async helpers import it lazily inside their own bodies.
+    result = _run_clean(
+        'import sys, python_utils.time\n'
+        "assert 'asyncio' not in sys.modules, "
+        "sorted(m for m in sys.modules if m.startswith('asyncio'))\n"
+    )
+    assert result.returncode == 0, result.stderr
+
+
+def test_first_access_caches_into_module_dict() -> None:
+    # PEP 562 __getattr__ runs once: the resolved object is cached in the
+    # module namespace so subsequent lookups skip __getattr__ entirely.
+    module = python_utils.time
+    assert python_utils.__dict__['time'] is module
+
+    func = python_utils.format_time
+    assert python_utils.__dict__['format_time'] is func
+
+
+def test_dir_lists_lazy_submodules() -> None:
+    # Lazy submodules that are not in __all__ (e.g. ``containers`` and
+    # ``exceptions``) must still be discoverable via ``dir``; tools such as
+    # ``import_global`` intersect requested names with ``dir(module)``.
+    names = set(dir(python_utils))
+    assert {'containers', 'exceptions'} <= names
+    assert set(python_utils.__all__) <= names
+
+
+@pytest.mark.asyncio
+async def test_aio_timeout_generator_default_iterable() -> None:
+    # With no iterable the generator defaults to ``aio.acount`` -- exercising
+    # the lazy ``aio``/``asyncio`` import and the None-resolution branch.
+    count = 0
+    generator: collections.abc.AsyncGenerator[object, None] = (
+        python_utils.aio_timeout_generator(timeout=0.05, interval=0.0)
+    )
+    async for _ in generator:
+        count += 1
+        if count >= 2:
+            break
+
+    assert count == 2
+
+    # Sanity: the re-exported type alias still resolves through the package.
+    assert python_utils.types.AsyncGenerator is not None