Defer asyncio and typing_extensions imports (lazy package init)

`import python_utils` now imports nothing eagerly: the package __init__ uses
PEP 562 __getattr__ to load submodules and their exported names on first
access (with a TYPE_CHECKING block so static typing is unchanged). This avoids
pulling in asyncio for consumers that only need the synchronous utilities.

time.py no longer imports asyncio/aio at module scope (moved into the two async
generators; the `aio.acount` default is resolved lazily), so
`from python_utils.time import format_time` stays asyncio-free.

types.py imports typing_extensions eagerly only on Python < 3.11 (to preserve
the backport overrides); on 3.11+ stdlib typing already provides the names used
and any remaining typing_extensions-only name is served lazily via __getattr__.

Net effect for a typical consumer (measured via python-progressbar): import
drops ~43ms -> ~22ms, with asyncio and typing_extensions no longer loaded.
Behaviour and public API are unchanged; full test suite passes.

Author: wolph

_python_utils_tests/test_lazy_imports.py

@@ -0,0 +1,44 @@
+"""Tests for the lazy-import machinery added to keep `import python_utils`
+light (PEP 562 `__getattr__` in the package and in `types`).
+"""
+
+import pytest
+
+import python_utils
+from python_utils import types
+
+
+def test_package_lazy_attribute_access() -> None:
+    # Submodule access and exported-name access both resolve via __getattr__.
+    assert python_utils.aio is python_utils.aio
+    assert callable(python_utils.acount)
+    missing = 'definitely_not_a_real_attribute'
+    with pytest.raises(AttributeError):
+        getattr(python_utils, missing)
+
+
+def test_types_lazy_typing_extensions(monkeypatch: pytest.MonkeyPatch) -> None:
+    # ``Protocol`` is normally present from ``from typing import *``; remove it
+    # so attribute access falls through to ``types.__getattr__``, which
+    # re-fetches it from typing_extensions (covering the lazy success path).
+    monkeypatch.delattr(types, 'Protocol', raising=False)
+    assert types.Protocol is not None
+    missing = 'not_a_real_typing_name_xyz'
+    with pytest.raises(AttributeError):
+        getattr(types, missing)
+
+
+@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: types.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

python_utils/__init__.py

@@ -2,6 +2,12 @@
 This module initializes the `python_utils` package by importing various
 submodules and functions.
 
+Imports are performed lazily (PEP 562): nothing is imported when you ``import
+python_utils``; each submodule/function is loaded on first access. This keeps
+``import python_utils`` cheap and, in particular, avoids eagerly importing
+``asyncio`` (via the async helpers) for consumers that only need the
+synchronous utilities.
+
 Submodules:
     aio
     converters
@@ -49,39 +55,126 @@
     LoggerBase
 """
 
-from . import (
-    aio,
-    converters,
-    decorators,
-    formatters,
-    generators,
-    import_,
-    logger,
-    terminal,
-    time,
-    types,
-)
-from .aio import acount
-from .containers import CastedDict, LazyCastedDict, UniqueList
-from .converters import remap, scale_1024, to_float, to_int, to_str, to_unicode
-from .decorators import listify, set_attributes
-from .exceptions import raise_exception, reraise
-from .formatters import camel_to_underscore, timesince
-from .generators import abatcher, batcher
-from .import_ import import_global
-from .logger import Logged, LoggerBase
-from .terminal import get_terminal_size
-from .time import (
-    aio_generator_timeout_detector,
-    aio_generator_timeout_detector_decorator,
-    aio_timeout_generator,
-    delta_to_seconds,
-    delta_to_seconds_or_none,
-    format_time,
-    timedelta_to_seconds,
-    timeout_generator,
+import importlib
+import typing
+
+if typing.TYPE_CHECKING:
+    # Eager imports for type checkers only; the runtime equivalents are loaded
+    # lazily by ``__getattr__`` below. Names appear in ``__all__`` so they are
+    # treated as re-exports (not unused imports).
+    from . import (
+        aio,
+        converters,
+        decorators,
+        formatters,
+        generators,
+        import_,
+        logger,
+        terminal,
+        time,
+        types,
+    )
+    from .aio import acount
+    from .containers import CastedDict, LazyCastedDict, UniqueList
+    from .converters import (
+        remap,
+        scale_1024,
+        to_float,
+        to_int,
+        to_str,
+        to_unicode,
+    )
+    from .decorators import listify, set_attributes
+    from .exceptions import raise_exception, reraise
+    from .formatters import camel_to_underscore, timesince
+    from .generators import abatcher, batcher
+    from .import_ import import_global
+    from .logger import Logged, LoggerBase
+    from .terminal import get_terminal_size
+    from .time import (
+        aio_generator_timeout_detector,
+        aio_generator_timeout_detector_decorator,
+        aio_timeout_generator,
+        delta_to_seconds,
+        delta_to_seconds_or_none,
+        format_time,
+        timedelta_to_seconds,
+        timeout_generator,
+    )
+
+#: Submodules that can be accessed as ``python_utils.<name>``.
+_SUBMODULES: frozenset[str] = frozenset(
+    {
+        'aio',
+        'containers',
+        'converters',
+        'decorators',
+        'exceptions',
+        'formatters',
+        'generators',
+        'import_',
+        'logger',
+        'terminal',
+        'time',
+        'types',
+    }
 )
 
+#: Exported name -> submodule it lives in.
+_NAME_TO_MODULE: dict[str, str] = {
+    'acount': 'aio',
+    'CastedDict': 'containers',
+    'LazyCastedDict': 'containers',
+    'UniqueList': 'containers',
+    'remap': 'converters',
+    'scale_1024': 'converters',
+    'to_float': 'converters',
+    'to_int': 'converters',
+    'to_str': 'converters',
+    'to_unicode': 'converters',
+    'listify': 'decorators',
+    'set_attributes': 'decorators',
+    'raise_exception': 'exceptions',
+    'reraise': 'exceptions',
+    'camel_to_underscore': 'formatters',
+    'timesince': 'formatters',
+    'abatcher': 'generators',
+    'batcher': 'generators',
+    'import_global': 'import_',
+    'Logged': 'logger',
+    'LoggerBase': 'logger',
+    'get_terminal_size': 'terminal',
+    'aio_generator_timeout_detector': 'time',
+    'aio_generator_timeout_detector_decorator': 'time',
+    'aio_timeout_generator': 'time',
+    'delta_to_seconds': 'time',
+    'delta_to_seconds_or_none': 'time',
+    'format_time': 'time',
+    'timedelta_to_seconds': 'time',
+    'timeout_generator': 'time',
+}
+
+
+def __getattr__(name: str) -> typing.Any:
+    """Lazily import submodules and their exported names on first access."""
+    if name in _SUBMODULES:
+        module = importlib.import_module(f'.{name}', __name__)
+    elif name in _NAME_TO_MODULE:
+        module = importlib.import_module(f'.{_NAME_TO_MODULE[name]}', __name__)
+        value = getattr(module, name)
+        globals()[name] = value  # cache so __getattr__ runs only once
+        return value
+    else:
+        raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(__all__))
+
+
 __all__ = [
     'CastedDict',
     'LazyCastedDict',

python_utils/converters.py

@@ -353,7 +353,7 @@ def remap(  # pyright: ignore[reportInconsistentOverload]
     new_max: _TN,
 ) -> _TN:
     """
-    remap a value from one range into another.
+    Remap a value from one range into another.
 
     >>> remap(500, 0, 1000, 0, 100)
     50

python_utils/time.py

@@ -19,14 +19,13 @@
 """
 
 # pyright: reportUnnecessaryIsInstance=false
-import asyncio
 import datetime
 import functools
 import itertools
 import time
 
 import python_utils
-from python_utils import aio, exceptions, types
+from python_utils import exceptions, types
 
 _T = types.TypeVar('_T')
 _P = types.ParamSpec('_P')
@@ -260,9 +259,12 @@ def timeout_generator(
 async def aio_timeout_generator(
     timeout: types.delta_type,  # noqa: ASYNC109
     interval: types.delta_type = datetime.timedelta(seconds=1),
-    iterable: types.Union[
-        types.AsyncIterable[_T], types.Callable[..., types.AsyncIterable[_T]]
-    ] = aio.acount,
+    iterable: types.Optional[
+        types.Union[
+            types.AsyncIterable[_T],
+            types.Callable[..., types.AsyncIterable[_T]],
+        ]
+    ] = None,
     interval_multiplier: float = 1.0,
     maximum_interval: types.Optional[types.delta_type] = None,
 ) -> types.AsyncGenerator[_T, None]:
@@ -280,6 +282,18 @@ async def aio_timeout_generator(
     effectively the same as the `timeout_generator` but it uses `async for`
     instead.
     """
+    # Imported lazily so that importing `python_utils.time` for its
+    # synchronous helpers (e.g. ``format_time``) does not pull in ``asyncio``.
+    import asyncio
+
+    from python_utils import aio
+
+    if iterable is None:
+        iterable = types.cast(
+            'types.AsyncIterable[_T]',
+            aio.acount,
+        )
+
     float_interval: float = delta_to_seconds(interval)
     float_maximum_interval: types.Optional[float] = delta_to_seconds_or_none(
         maximum_interval
@@ -328,6 +342,9 @@ async def aio_generator_timeout_detector(
     If `on_timeout` is `None`, the exception is silently ignored and the
     generator will finish as normal.
     """
+    # Imported lazily so importing `python_utils.time` stays asyncio-free.
+    import asyncio
+
     if total_timeout is None:
         total_timeout_end = None
     else:

python_utils/types.py

@@ -14,6 +14,7 @@
 
 import datetime
 import decimal
+import sys  # noqa: F401  (used in version-gated typing_extensions import below)
 from re import Match, Pattern
 from types import *  # pragma: no cover  # noqa: F403
 from typing import *  # pragma: no cover  # noqa: F403
@@ -32,7 +33,15 @@
     Union as U,  # noqa: N817
 )
 
-from typing_extensions import *  # type: ignore[no-redef,assignment] # noqa: F403
+if sys.version_info < (3, 11):  # pragma: no cover
+    # Older Pythons need typing_extensions' backports (names and behavioural
+    # fixes) that stdlib typing lacks, so import it eagerly there. Type
+    # checkers target the minimum version and so always see these names. On
+    # 3.11+ stdlib typing already provides everything used here, and any
+    # remaining typing_extensions-only name is served lazily by __getattr__
+    # below -- so importing this module (and therefore `python_utils`) does
+    # not eagerly pull in typing_extensions.
+    from typing_extensions import *  # type: ignore[no-redef,assignment] # noqa: F403
 
 Scope = Dict[str, Any]
 OptionalScope = O[Scope]
@@ -53,6 +62,30 @@
     None,
 ]
 
+
+def __getattr__(name: str) -> Any:
+    """Lazily resolve typing_extensions-only names on first access.
+
+    On Python 3.11+ typing_extensions is not imported eagerly (see above); any
+    name not provided by stdlib ``typing``/``types`` is fetched from
+    typing_extensions here, on demand.
+    """
+    if name.startswith('__') and name.endswith('__'):
+        raise AttributeError(name)
+
+    import typing_extensions
+
+    try:
+        value = getattr(typing_extensions, name)
+    except AttributeError:
+        raise AttributeError(
+            f'module {__name__!r} has no attribute {name!r}',
+        ) from None
+
+    globals()[name] = value  # cache so __getattr__ runs only once per name
+    return value
+
+
 __all__ = [
     'IO',
     'TYPE_CHECKING',