fix: resolve litellm.proxy submodules lazily so litellm.proxy._types stays importable

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

litellm/__init__.py

@@ -1269,14 +1269,12 @@ if TYPE_CHECKING:
     from .llms.deprecated_providers.aleph_alpha import AlephAlphaConfig
     from .llms.gemini.common_utils import GeminiModelInfo
 
-
     from .llms.vertex_ai.vertex_embeddings.transformation import (
         VertexAITextEmbeddingConfig,
     )
 
     vertexAITextEmbeddingConfig = VertexAITextEmbeddingConfig()
 
-
     from .llms.bedrock.embed.amazon_titan_v2_transformation import (
         AmazonTitanV2Config,
     )
@@ -1429,16 +1427,13 @@ if TYPE_CHECKING:
     ### ADAPTERS ###
     import litellm.anthropic_interface as anthropic
 
-
     ### Vector Store Registry ###
 
-
     ### RAG ###
     from . import rag
 
     ### CUSTOM LLMs ###
 
-
     ### CLI UTILITIES ###
     from litellm.litellm_core_utils.cli_token_utils import get_litellm_gateway_api_key
 

litellm/_lazy_imports.py

@@ -411,21 +411,26 @@ class LiteLLMModule(ModuleType):
     search = _shadowable_function_property("search")
 
 
-def lazy_import_litellm_submodule(name: str) -> "ModuleType | None":
-    """Resolve litellm.<name> as a submodule (e.g. litellm.utils) when no other handler matches"""
+def lazy_import_submodule(package: str, name: str) -> "ModuleType | None":
+    """Resolve <package>.<name> as a submodule (e.g. litellm.utils) when no other handler matches"""
     if name.startswith("__") or not name.isidentifier():
         return None
     try:
-        spec: Final = importlib.util.find_spec(f"litellm.{name}")
+        spec: Final = importlib.util.find_spec(f"{package}.{name}")
     except ModuleNotFoundError:
         return None
     if spec is None:
         return None
-    module: Final = importlib.import_module(f"litellm.{name}")
-    get_litellm_globals()[name] = module
+    module: Final = importlib.import_module(f"{package}.{name}")
+    sys.modules[package].__dict__[name] = module  # rebind-ok: caches the resolved submodule on the package
     return module
 
 
+def lazy_import_litellm_submodule(name: str) -> "ModuleType | None":
+    """Resolve litellm.<name> as a submodule (e.g. litellm.utils) when no other handler matches"""
+    return lazy_import_submodule("litellm", name)
+
+
 def _lazy_import_utils_module(name: str) -> object:
     """
     Handler for utils module lazy imports.

litellm/proxy/__init__.py

@@ -1 +1,11 @@
-from . import *
+from types import ModuleType
+from typing import Final
+
+
+def __getattr__(name: str) -> ModuleType:
+    from litellm._lazy_imports import lazy_import_submodule
+
+    submodule: Final = lazy_import_submodule(__name__, name)
+    if submodule is not None:
+        return submodule
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tests/test_litellm/test_lazy_imports.py

@@ -378,6 +378,14 @@ def test_litellm_submodule_fallback():
         _ = litellm.not_a_real_attribute
 
 
+def test_proxy_private_submodule_resolves_in_fresh_process():
+    """litellm.proxy._types resolves without an eager proxy import (used by documentation checks)."""
+    code = "import litellm\nprint(litellm.proxy._types.__name__)\n"
+    result = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True)
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "litellm.proxy._types"
+
+
 def test_lazy_instances_are_singletons():
     """Lazily created instances are cached, so repeated access returns the same object."""
     assert litellm._key_management_settings is litellm._key_management_settings