fix: emit deprecation warning only when deprecated aliases are accessed

[jsamuel1]

Problem

When importing strands with warnings enabled (PYTHONWARNINGS=once python -c "import strands"), a deprecation warning is emitted:

.venv/lib/python3.13/site-packages/strands/experimental/hooks/__init__.py:3: DeprecationWarning: These events have been moved to production with updated names. Use BeforeModelCallEvent, AfterModelCallEvent, BeforeToolCallEvent, and AfterToolCallEvent from strands.hooks instead.
  from .events import (

This happens because the deprecation warning was emitted at module import time in strands/experimental/hooks/events.py, which triggered whenever strands was imported because other modules (like session_manager.py and _executor.py) import from experimental.hooks.

Solution

Changed from module-level warning to lazy warning using __getattr__:

1. src/strands/experimental/hooks/events.py: Replaced the module-level warnings.warn() call and TypeAlias definitions with a __getattr__ function that emits the warning only when deprecated aliases (BeforeToolInvocationEvent, AfterToolInvocationEvent, BeforeModelInvocationEvent, AfterModelInvocationEvent) are actually accessed.

2. src/strands/experimental/hooks/__init__.py: Updated to not import the deprecated aliases at module level. Added a __getattr__ function to delegate attribute access to the events module, which handles the deprecation warnings.

3. tests/strands/experimental/hooks/test_hook_aliases.py: Updated the test to verify the new behavior (warning on access, not on import).

Verification

Before fix:

$ PYTHONWARNINGS=once python -c "import strands"
# Warning emitted

After fix:

$ PYTHONWARNINGS=once python -c "import strands"
# No warning

$ PYTHONWARNINGS=once python -c "from strands.experimental.hooks import BeforeToolInvocationEvent"
# Warning emitted only when deprecated alias is accessed

Fixes #1236

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[zastrowm]

I made a mess adding a return type and rebasing to main, but I think it's good now