fix: #2863 lazy-load SQLiteSession exports (#2864)

Author: seratch

src/agents/__init__.py

@@ -1,6 +1,6 @@
 import logging
 import sys
-from typing import Literal
+from typing import TYPE_CHECKING, Any, Literal
 
 from openai import AsyncOpenAI
 
@@ -74,7 +74,6 @@
     Session,
     SessionABC,
     SessionSettings,
-    SQLiteSession,
     is_openai_responses_compaction_aware_session,
 )
 from .model_settings import ModelSettings
@@ -225,6 +224,19 @@
 from .usage import Usage
 from .version import __version__
 
+if TYPE_CHECKING:
+    from .memory.sqlite_session import SQLiteSession
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SQLiteSession":
+        from .memory.sqlite_session import SQLiteSession
+
+        globals()[name] = SQLiteSession
+        return SQLiteSession
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 def set_default_openai_key(key: str, use_for_tracing: bool = True) -> None:
     """Set the default OpenAI API key to use for LLM requests (and optionally tracing()). This is

src/agents/memory/__init__.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
 from .openai_conversations_session import OpenAIConversationsSession
 from .openai_responses_compaction_session import OpenAIResponsesCompactionSession
 from .session import (
@@ -8,9 +12,11 @@
     is_openai_responses_compaction_aware_session,
 )
 from .session_settings import SessionSettings
-from .sqlite_session import SQLiteSession
 from .util import SessionInputCallback
 
+if TYPE_CHECKING:
+    from .sqlite_session import SQLiteSession
+
 __all__ = [
     "Session",
     "SessionABC",
@@ -23,3 +29,13 @@
     "OpenAIResponsesCompactionAwareSession",
     "is_openai_responses_compaction_aware_session",
 ]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "SQLiteSession":
+        from .sqlite_session import SQLiteSession
+
+        globals()[name] = SQLiteSession
+        return SQLiteSession
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tests/tracing/test_import_side_effects.py

@@ -67,6 +67,85 @@ def test_import_agents_has_no_tracing_side_effects() -> None:
     assert payload["shutdown_handler_registered"] is False
 
 
+def test_import_agents_does_not_require_sqlite3() -> None:
+    payload = _run_python(
+        """
+import importlib.abc
+import json
+import sys
+
+class BlockSqlite3(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname, path, target=None):
+        if fullname in {"sqlite3", "_sqlite3"}:
+            raise ModuleNotFoundError(f"blocked optional backend module: {fullname}")
+        return None
+
+sys.meta_path.insert(0, BlockSqlite3())
+
+import agents
+from agents import Agent, Runner
+from agents.memory import Session, SessionSettings
+
+print(
+    json.dumps(
+        {
+            "agent_name": Agent.__name__,
+            "runner_name": Runner.__name__,
+            "session_name": Session.__name__,
+            "settings_name": SessionSettings.__name__,
+            "sqlite3_loaded": "sqlite3" in sys.modules,
+            "private_sqlite3_loaded": "_sqlite3" in sys.modules,
+            "sqlite_session_loaded": "agents.memory.sqlite_session" in sys.modules,
+            "sqlite_session_exported": "SQLiteSession" in agents.__all__,
+        }
+    )
+)
+"""
+    )
+
+    assert payload["agent_name"] == "Agent"
+    assert payload["runner_name"] == "Runner"
+    assert payload["session_name"] == "Session"
+    assert payload["settings_name"] == "SessionSettings"
+    assert payload["sqlite3_loaded"] is False
+    assert payload["private_sqlite3_loaded"] is False
+    assert payload["sqlite_session_loaded"] is False
+    assert payload["sqlite_session_exported"] is True
+
+
+def test_sqlite_session_top_level_export_is_lazy() -> None:
+    payload = _run_python(
+        """
+import json
+import sys
+
+import agents
+
+loaded_after_import = "agents.memory.sqlite_session" in sys.modules
+
+from agents import SQLiteSession
+
+loaded_after_export = "agents.memory.sqlite_session" in sys.modules
+
+print(
+    json.dumps(
+        {
+            "sqlite_session_name": SQLiteSession.__name__,
+            "loaded_after_import": loaded_after_import,
+            "loaded_after_export": loaded_after_export,
+            "sqlite3_loaded": "sqlite3" in sys.modules,
+        }
+    )
+)
+"""
+    )
+
+    assert payload["sqlite_session_name"] == "SQLiteSession"
+    assert payload["loaded_after_import"] is False
+    assert payload["loaded_after_export"] is True
+    assert payload["sqlite3_loaded"] is True
+
+
 def test_get_trace_provider_lazily_initializes_defaults() -> None:
     payload = _run_python(
         """