vgi.auth: import the HTTP and JWT auth helpers on first use

vgi/__init__ imports vgi.auth, which imported vgi_rpc.http to re-export
its auth helpers. That module brings in the HTTP server and client
stack (falcon, httpx2, cryptography, joserfc): about 180 ms of every
'import vgi', and so of every subprocess worker's start, which never
uses it. The helpers now resolve on first access through a module
__getattr__. 'from vgi.auth import bearer_authenticate' works as
before, and raises ImportError when the extra is missing, as it did.
Type checkers see them through TYPE_CHECKING imports.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: rustyconover

vgi/auth.py

@@ -18,8 +18,9 @@
 
 from __future__ import annotations
 
-import contextlib
+import importlib
 from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
 
 from vgi_rpc.rpc import AuthContext, CallContext
 
@@ -43,9 +44,28 @@
     "TokenResolver",
 ]
 
-# HTTP auth helpers — available when vgi[http] is installed.
-with contextlib.suppress(ImportError):
-    from vgi_rpc.http import (  # noqa: F401
+# HTTP auth helpers (``vgi[http]``) and JWT auth (``vgi[oauth]``), resolved on
+# first access rather than at import. ``vgi/__init__`` imports this module, and
+# ``vgi_rpc.http`` brings in the HTTP server and client stack (falcon, httpx2,
+# cryptography, joserfc): importing it here put about 180 ms on every
+# ``import vgi``, and so on the start of every subprocess worker, which never
+# uses it. ``from vgi.auth import bearer_authenticate`` works as before; when
+# the extra is missing it raises ImportError, as it did.
+_LAZY_EXPORTS = {
+    "AuthUnavailableError": "vgi_rpc.http",
+    "OAuthResourceMetadata": "vgi_rpc.http",
+    "bearer_authenticate": "vgi_rpc.http",
+    "bearer_authenticate_static": "vgi_rpc.http",
+    "chain_authenticate": "vgi_rpc.http",
+    "parse_client_id": "vgi_rpc.http",
+    "parse_client_secret": "vgi_rpc.http",
+    "parse_device_code_client_id": "vgi_rpc.http",
+    "parse_device_code_client_secret": "vgi_rpc.http",
+    "jwt_authenticate": "vgi_rpc.http._oauth_jwt",
+}
+
+if TYPE_CHECKING:
+    from vgi_rpc.http import (
         AuthUnavailableError,
         OAuthResourceMetadata,
         bearer_authenticate,
@@ -56,21 +76,39 @@
         parse_device_code_client_id,
         parse_device_code_client_secret,
     )
+    from vgi_rpc.http._oauth_jwt import jwt_authenticate
+
+
+def __getattr__(name: str) -> Any:
+    """Import an HTTP or JWT auth helper on first access (PEP 562).
+
+    Args:
+        name: The attribute being looked up.
+
+    Returns:
+        The helper, which is then cached in this module's namespace.
+
+    Raises:
+        AttributeError: If ``name`` is not a helper this module re-exports, or
+            its extra is not installed.
+    """
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        value = getattr(importlib.import_module(module_name), name)
+    except ImportError as exc:
+        raise AttributeError(
+            f"module {__name__!r} has no attribute {name!r}: it needs {module_name}, which failed to import ({exc})"
+        ) from exc
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    """List this module's names, the lazily imported helpers included.
 
-    __all__ += [
-        "AuthUnavailableError",
-        "OAuthResourceMetadata",
-        "bearer_authenticate",
-        "bearer_authenticate_static",
-        "chain_authenticate",
-        "parse_client_id",
-        "parse_client_secret",
-        "parse_device_code_client_id",
-        "parse_device_code_client_secret",
-    ]
-
-# JWT auth — available when vgi[oauth] is installed (requires authlib).
-with contextlib.suppress(ImportError):
-    from vgi_rpc.http._oauth_jwt import jwt_authenticate  # noqa: F401
-
-    __all__ += ["jwt_authenticate"]
+    Returns:
+        The module's attribute names.
+    """
+    return sorted({*globals(), *_LAZY_EXPORTS})