Mirror Starlette docstring; rewrite shim tests in logfire's reload+patch.dict style

Test diff: -33 / +12. Replaces the bespoke `builtins.__import__` monkeypatch with
`mock.patch.dict('sys.modules', {'httpx2': None | <fake>})` + `importlib.reload`,
matching `logfire/tests/otel_integrations/test_httpx.py::test_missing_opentelemetry_dependency`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dsfaccini

src/mcp/shared/exceptions.py

@@ -42,10 +42,12 @@ def __str__(self) -> str:
 
 
 class MCPDeprecationWarning(UserWarning):
-    """Deprecation warning emitted by the `mcp` package.
+    """A custom deprecation warning for MCP.
 
-    Subclasses `UserWarning` (not `DeprecationWarning`) so it is visible by default —
-    `DeprecationWarning` is silenced at the Python level for non-`__main__` callers.
+    Unlike the built-in DeprecationWarning, this inherits from UserWarning to ensure it is visible by default, helping
+    users discover deprecated features without needing to enable warnings explicitly.
+
+    Reference: https://sethmlarson.dev/deprecations-via-warnings-dont-work-for-python-libraries
     """
 
 

tests/shared/test_httpx_shim.py

@@ -1,61 +1,40 @@
 """Tests for the `httpx` → `httpx2` migration shim in `mcp.shared._httpx`.
 
 `mcp` prefers `httpx2` and falls back to `httpx` with an `MCPDeprecationWarning` emitted at
-the shim's import time. Today the lockfile pins `httpx` (not `httpx2`), so importing the shim
-exercises the fallback.
+the shim's import time. The lockfile pins `httpx` (not `httpx2`), so the canonical state of
+the shim is the fallback path.
 """
 
 from __future__ import annotations
 
 import importlib
-import sys
 import warnings
+from unittest import mock
 
 import pytest
 
+import mcp.shared._httpx
 from mcp.shared.exceptions import MCPDeprecationWarning
 
 
-def _force_reimport_shim() -> None:
-    """Drop the cached shim module so the next import re-runs its top-level code."""
-    sys.modules.pop("mcp.shared._httpx", None)
+@pytest.fixture(autouse=True)
+def _restore_shim_state():
+    """Reload the shim after each test so a simulated `httpx2` doesn't leak into later tests."""
+    yield
+    importlib.reload(mcp.shared._httpx)
 
 
-def test_fallback_emits_warning_at_import(monkeypatch: pytest.MonkeyPatch) -> None:
-    """With only `httpx` installed, importing the shim emits `MCPDeprecationWarning`."""
-    monkeypatch.delitem(sys.modules, "httpx2", raising=False)
-    _force_reimport_shim()
+def test_fallback_emits_warning() -> None:
+    with mock.patch.dict("sys.modules", {"httpx2": None}):
+        with pytest.warns(MCPDeprecationWarning, match=r"install `httpx2` instead"):
+            importlib.reload(mcp.shared._httpx)
 
-    from collections.abc import Mapping, Sequence
 
-    real_import = __import__
+def test_httpx2_present_is_silent() -> None:
+    import httpx
 
-    def fake_import(
-        name: str,
-        globals: Mapping[str, object] | None = None,
-        locals: Mapping[str, object] | None = None,
-        fromlist: Sequence[str] = (),
-        level: int = 0,
-    ) -> object:
-        if name == "httpx2":
-            raise ImportError("simulated: httpx2 not installed")
-        return real_import(name, globals, locals, fromlist, level)
-
-    monkeypatch.setattr("builtins.__import__", fake_import)
-    with pytest.warns(MCPDeprecationWarning, match=r"install `httpx2` instead"):
-        importlib.import_module("mcp.shared._httpx")
-
-
-def test_httpx2_present_is_silent(monkeypatch: pytest.MonkeyPatch) -> None:
-    """When `httpx2` is importable, the shim selects it and emits no warning."""
-    import httpx as real_httpx
-
-    monkeypatch.setitem(sys.modules, "httpx2", real_httpx)
-    _force_reimport_shim()
-
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always", MCPDeprecationWarning)
-        reloaded = importlib.import_module("mcp.shared._httpx")
-
-    assert reloaded.httpx is real_httpx
-    assert [w for w in caught if issubclass(w.category, MCPDeprecationWarning)] == []
+    with mock.patch.dict("sys.modules", {"httpx2": httpx}):
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", MCPDeprecationWarning)
+            importlib.reload(mcp.shared._httpx)
+        assert mcp.shared._httpx.httpx is httpx