fix(api): avoid loading unrelated API resources on first use (openai#3898)

Importing the SDK or accessing one API resource currently loads
unrelated resources, including Assistants. Load resource exports and
streaming helpers when first accessed to reduce startup work.

Existing import paths, class identity, static typing, wildcard imports,
and discovery are preserved. Code that inspects module dictionaries
directly may observe exports appearing later; import work and import
errors move to first access.

Regression tests cover import isolation, public exports, runtime
annotations, pickling, reloads, sync/async requests and streams, and
concurrent first access. Endpoint methods, models, dependencies, and
webhook behavior are unchanged.

Validation: 682 focused tests passed (14 skipped), along with Mypy,
Pyright, and Ruff. Python 3.10/3.14, HTTPX2, build, lint, and baseline
checks passed on the final revision. End-to-end testing also passed.

Co-authored-by: marcuswood-oai <323319819+marcuswood-oai@users.noreply.github.com>

Author: marcuswood-oai

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: 5ca8ce21-7fe9-4009-836d-1c94c1c1e116
+generation_id: 84d5b19e-e118-402a-940c-00134d57a039
 openapi_spec_hash: 9530fc18efeeb0be58821616af20494d
 openapi_transformed_spec_hash: bcd481fc6089377839837e55cdfa80cc
 config_hash: 487f26152d0893506c0e0d1060441bd0
-codegen_sha: da44ef0149596e5412c15e70836dd015824a9a90
-codegen_hash: 838f201dfcf9313561fe25f2783c231d707b30a12cf93d0e54aec3687399b0ea
-public_codegen_sha: 8b18351582d0b9a4c85a147b4e8769630610fdeb
+codegen_sha: 136c93db5472eb81849571ca9059367e650ef723
+codegen_hash: 0a9ede8d6058e352650cb2411de35dc1509646d728f9a94c78531c177508d37e
+public_codegen_sha: 2fbff3f92f139fde3a75d38e399be22ad19afe04

src/openai/__init__.py

@@ -108,10 +108,27 @@
 from .lib.azure import AzureOpenAI as AzureOpenAI, AsyncAzureOpenAI as AsyncAzureOpenAI
 from .lib.bedrock import BedrockOpenAI as BedrockOpenAI, AsyncBedrockOpenAI as AsyncBedrockOpenAI
 from .lib._old_api import *
-from .lib.streaming import (
-    AssistantEventHandler as AssistantEventHandler,
-    AsyncAssistantEventHandler as AsyncAssistantEventHandler,
-)
+
+if _t.TYPE_CHECKING:
+    from .lib.streaming import (
+        AssistantEventHandler as AssistantEventHandler,
+        AsyncAssistantEventHandler as AsyncAssistantEventHandler,
+    )
+else:
+    _STREAMING_EXPORTS = ("AssistantEventHandler", "AsyncAssistantEventHandler")
+
+    def __getattr__(name: str) -> _t.Any:
+        if name in _STREAMING_EXPORTS:
+            from importlib import import_module
+
+            value = getattr(import_module(".lib.streaming", __name__), name)
+            globals()[name] = value
+            return value
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    def __dir__() -> list[str]:
+        return sorted(set(globals()) | set(_STREAMING_EXPORTS))
+
 
 _setup_logging()
 

src/openai/lib/streaming/__init__.py

@@ -1,8 +1,34 @@
-from ._assistants import (
-    AssistantEventHandler as AssistantEventHandler,
-    AssistantEventHandlerT as AssistantEventHandlerT,
-    AssistantStreamManager as AssistantStreamManager,
-    AsyncAssistantEventHandler as AsyncAssistantEventHandler,
-    AsyncAssistantEventHandlerT as AsyncAssistantEventHandlerT,
-    AsyncAssistantStreamManager as AsyncAssistantStreamManager,
-)
+import typing as _t
+
+if _t.TYPE_CHECKING:
+    from ._assistants import (
+        AssistantEventHandler as AssistantEventHandler,
+        AssistantEventHandlerT as AssistantEventHandlerT,
+        AssistantStreamManager as AssistantStreamManager,
+        AsyncAssistantEventHandler as AsyncAssistantEventHandler,
+        AsyncAssistantEventHandlerT as AsyncAssistantEventHandlerT,
+        AsyncAssistantStreamManager as AsyncAssistantStreamManager,
+    )
+else:
+
+    def __getattr__(name: str) -> _t.Any:
+        if name in __all__:
+            from importlib import import_module
+
+            value = getattr(import_module("._assistants", __name__), name)
+            globals()[name] = value
+            return value
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    def __dir__() -> list[str]:
+        return sorted(set(globals()) | set(__all__))
+
+
+__all__ = [
+    "AssistantEventHandler",
+    "AssistantEventHandlerT",
+    "AssistantStreamManager",
+    "AsyncAssistantEventHandler",
+    "AsyncAssistantEventHandlerT",
+    "AsyncAssistantStreamManager",
+]