fix: emit deprecation warning only when deprecated aliases are accessed (#1380)

Previously, the deprecation warning was emitted at module import time,
which triggered whenever `strands` was imported because other modules
import from `experimental.hooks`.

Changed to use `__getattr__` to lazily emit the warning only when the
deprecated aliases (BeforeToolInvocationEvent, AfterToolInvocationEvent,
BeforeModelInvocationEvent, AfterModelInvocationEvent) are actually
accessed.

Fixes #1236

---------

Co-authored-by: Mackenzie Zastrow <zastrowm@users.noreply.github.com>

Author: jsamuel1

src/strands/experimental/hooks/__init__.py

@@ -1,19 +1,28 @@
 """Experimental hook functionality that has not yet reached stability."""
 
+from typing import Any
+
 from .events import (
-    AfterModelInvocationEvent,
-    AfterToolInvocationEvent,
-    BeforeModelInvocationEvent,
-    BeforeToolInvocationEvent,
+    BidiAfterConnectionRestartEvent,
     BidiAfterInvocationEvent,
     BidiAfterToolCallEvent,
     BidiAgentInitializedEvent,
+    BidiBeforeConnectionRestartEvent,
     BidiBeforeInvocationEvent,
     BidiBeforeToolCallEvent,
     BidiInterruptionEvent,
     BidiMessageAddedEvent,
 )
 
+# Deprecated aliases are accessed via __getattr__ to emit warnings only on use
+
+
+def __getattr__(name: str) -> Any:
+    from . import events
+
+    return getattr(events, name)
+
+
 __all__ = [
     "BeforeToolInvocationEvent",
     "AfterToolInvocationEvent",
@@ -27,4 +36,6 @@
     "BidiBeforeToolCallEvent",
     "BidiAfterToolCallEvent",
     "BidiInterruptionEvent",
+    "BidiBeforeConnectionRestartEvent",
+    "BidiAfterConnectionRestartEvent",
 ]

src/strands/experimental/hooks/events.py

@@ -5,7 +5,7 @@
 
 import warnings
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Literal, TypeAlias
+from typing import TYPE_CHECKING, Any, Literal
 
 from ...hooks.events import AfterModelCallEvent, AfterToolCallEvent, BeforeModelCallEvent, BeforeToolCallEvent
 from ...hooks.registry import BaseHookEvent
@@ -16,17 +16,25 @@
     from ..bidi.agent.agent import BidiAgent
     from ..bidi.models import BidiModelTimeoutError
 
-warnings.warn(
-    "BeforeModelCallEvent, AfterModelCallEvent, BeforeToolCallEvent, and AfterToolCallEvent are no longer experimental."
-    "Import from strands.hooks instead.",
-    DeprecationWarning,
-    stacklevel=2,
-)
-
-BeforeToolInvocationEvent: TypeAlias = BeforeToolCallEvent
-AfterToolInvocationEvent: TypeAlias = AfterToolCallEvent
-BeforeModelInvocationEvent: TypeAlias = BeforeModelCallEvent
-AfterModelInvocationEvent: TypeAlias = AfterModelCallEvent
+# Deprecated aliases - warning emitted on access via __getattr__
+_DEPRECATED_ALIASES = {
+    "BeforeToolInvocationEvent": BeforeToolCallEvent,
+    "AfterToolInvocationEvent": AfterToolCallEvent,
+    "BeforeModelInvocationEvent": BeforeModelCallEvent,
+    "AfterModelInvocationEvent": AfterModelCallEvent,
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _DEPRECATED_ALIASES:
+        warnings.warn(
+            f"{name} has been moved to production with an updated name. "
+            f"Use {_DEPRECATED_ALIASES[name].__name__} from strands.hooks instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _DEPRECATED_ALIASES[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 
 # BidiAgent Hook Events

tests/strands/experimental/hooks/test_hook_aliases.py

@@ -112,18 +112,20 @@ def experimental_callback(event: BeforeToolInvocationEvent):
     assert received_event is test_event
 
 
-def test_deprecation_warning_on_import(captured_warnings):
-    """Verify that importing from experimental module emits deprecation warning."""
+def test_deprecation_warning_on_access(captured_warnings):
+    """Verify that accessing deprecated aliases emits deprecation warning."""
+    import strands.experimental.hooks.events as events_module
 
-    module = sys.modules.get("strands.experimental.hooks.events")
-    if module:
-        importlib.reload(module)
-    else:
-        importlib.import_module("strands.experimental.hooks.events")
+    # Clear any existing warnings
+    captured_warnings.clear()
+
+    # Access a deprecated alias - this should trigger the warning
+    _ = events_module.BeforeToolInvocationEvent
 
     assert len(captured_warnings) == 1
     assert issubclass(captured_warnings[0].category, DeprecationWarning)
-    assert "are no longer experimental" in str(captured_warnings[0].message)
+    assert "BeforeToolInvocationEvent" in str(captured_warnings[0].message)
+    assert "BeforeToolCallEvent" in str(captured_warnings[0].message)
 
 
 def test_deprecation_warning_on_import_only_for_experimental(captured_warnings):