feat: lazy package init to keep import python_utils light

Defer all submodule/function imports via PEP 562 (`__getattr__`/`__dir__`) so
`import python_utils` no longer eagerly imports every submodule, and move
`asyncio` (and `python_utils.aio`) imports inside `python_utils.time`'s async
helpers. Consumers that only need the synchronous utilities no longer pay the
cost of importing `asyncio`.

- __init__.py: PEP 562 lazy loading; `__version__` kept eager (cheap
  metadata). Public `__all__` is unchanged and `dir()` still lists the lazy
  `containers`/`exceptions` submodules so `import_global()` keeps working.
- time.py: `aio_timeout_generator(iterable=...)` now defaults to `None` and
  resolves to `aio.acount` lazily (the default cannot reference `aio.acount`
  without importing asyncio at module load); `asyncio` is imported inside the
  two async helpers.
- tests: regression tests proving a bare `import python_utils` and
  `import python_utils.time` pull in neither `asyncio` nor `typing_extensions`.

Public API verified against the 4.0.0 base via an export/signature diff: the
only differences are the two inherent consequences of deferring asyncio --
`aio_timeout_generator`'s default iterable is `None` instead of `aio.acount`,
and `python_utils.time` no longer re-exposes the `aio`/`asyncio` modules.

Author: wolph

_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

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
@@ -52,40 +58,132 @@
     LoggerBase
 """
 
-from . import (
-    aio,
-    converters,
-    decorators,
-    formatters,
-    generators,
-    import_,
-    logger,
-    terminal,
-    time,
-    types,
-)
+import importlib as _importlib
+import typing as _typing
+
 from .__about__ import __version__
-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,
+
+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
+    # 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__) | _SUBMODULES | set(_NAME_TO_MODULE)
+    )
+
+
 __all__ = [
     'CastedDict',
     'LazyCastedDict',

python_utils/time.py

@@ -16,7 +16,6 @@
 """
 
 # pyright: reportUnnecessaryIsInstance=false
-import asyncio
 import collections.abc
 import datetime
 import functools
@@ -25,7 +24,7 @@
 import typing
 
 import python_utils
-from python_utils import aio, exceptions, types
+from python_utils import exceptions, types
 
 _T = typing.TypeVar('_T')
 _P = typing.ParamSpec('_P')
@@ -256,9 +255,8 @@ async def aio_timeout_generator(
     timeout: types.delta_type,  # noqa: ASYNC109
     interval: types.delta_type = datetime.timedelta(seconds=1),
     iterable: collections.abc.AsyncIterable[_T]
-    | collections.abc.Callable[
-        ..., collections.abc.AsyncIterable[_T]
-    ] = aio.acount,
+    | collections.abc.Callable[..., collections.abc.AsyncIterable[_T]]
+    | None = None,
     interval_multiplier: float = 1.0,
     maximum_interval: types.delta_type | None = None,
 ) -> collections.abc.AsyncGenerator[_T, None]:
@@ -276,6 +274,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 = typing.cast(
+            collections.abc.Callable[[], collections.abc.AsyncIterable[_T]],
+            aio.acount,
+        )
+
     float_interval: float = delta_to_seconds(interval)
     float_maximum_interval: float | None = delta_to_seconds_or_none(
         maximum_interval
@@ -323,6 +333,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: