feat(otel): add deprecation shim for litestar.contrib.opentelemetry

Re-introduce litestar/contrib/opentelemetry/ as a __getattr__ shim
re-exporting from litestar.plugins.opentelemetry with per-attribute
DeprecationWarning. Preserves the migration path for users coming from
2.x; the shim itself will be stripped before 3.0 GA.

Mirrors the existing v2 prometheus shim pattern (PR #3755 sqlalchemy).
Covers top-level and submodule imports (config, middleware, plugin) so
that legacy import paths continue to resolve to the same plugin objects.

Tests: 5 new deprecation tests in tests/unit/test_contrib/test_opentelemetry.py;
existing 18 OTEL plugin tests still pass.

Author: cofin

litestar/contrib/opentelemetry/__init__.py

@@ -0,0 +1,40 @@
+# ruff: noqa: TC004, F401
+from typing import TYPE_CHECKING
+
+from litestar.utils import warn_deprecation
+
+__all__ = (
+    "OpenTelemetryConfig",
+    "OpenTelemetryInstrumentationMiddleware",
+    "OpenTelemetryPlugin",
+)
+
+
+def __getattr__(attr_name: str) -> object:
+    if attr_name in __all__:
+        from litestar.plugins.opentelemetry import (
+            OpenTelemetryConfig,
+            OpenTelemetryInstrumentationMiddleware,
+            OpenTelemetryPlugin,
+        )
+
+        warn_deprecation(
+            deprecated_name=f"litestar.contrib.opentelemetry.{attr_name}",
+            version="3.0.0b0",
+            kind="import",
+            removal_in="3.0.0",
+            info=f"importing {attr_name} from 'litestar.contrib.opentelemetry' is deprecated, please "
+            f"import it from 'litestar.plugins.opentelemetry' instead",
+        )
+        value = globals()[attr_name] = locals()[attr_name]
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")  # pragma: no cover
+
+
+if TYPE_CHECKING:
+    from litestar.plugins.opentelemetry import (
+        OpenTelemetryConfig,
+        OpenTelemetryInstrumentationMiddleware,
+        OpenTelemetryPlugin,
+    )

litestar/contrib/opentelemetry/config.py

@@ -0,0 +1,28 @@
+# ruff: noqa: TC004, F401
+from typing import TYPE_CHECKING
+
+from litestar.utils import warn_deprecation
+
+__all__ = ("OpenTelemetryConfig",)
+
+
+def __getattr__(attr_name: str) -> object:
+    if attr_name in __all__:
+        from litestar.plugins.opentelemetry import OpenTelemetryConfig
+
+        warn_deprecation(
+            deprecated_name=f"litestar.contrib.opentelemetry.config.{attr_name}",
+            version="3.0.0b0",
+            kind="import",
+            removal_in="3.0.0",
+            info=f"importing {attr_name} from 'litestar.contrib.opentelemetry.config' is deprecated, please "
+            f"import it from 'litestar.plugins.opentelemetry' instead",
+        )
+        value = globals()[attr_name] = locals()[attr_name]
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")  # pragma: no cover
+
+
+if TYPE_CHECKING:
+    from litestar.plugins.opentelemetry import OpenTelemetryConfig

litestar/contrib/opentelemetry/middleware.py

@@ -0,0 +1,28 @@
+# ruff: noqa: TC004, F401
+from typing import TYPE_CHECKING
+
+from litestar.utils import warn_deprecation
+
+__all__ = ("OpenTelemetryInstrumentationMiddleware",)
+
+
+def __getattr__(attr_name: str) -> object:
+    if attr_name in __all__:
+        from litestar.plugins.opentelemetry import OpenTelemetryInstrumentationMiddleware
+
+        warn_deprecation(
+            deprecated_name=f"litestar.contrib.opentelemetry.middleware.{attr_name}",
+            version="3.0.0b0",
+            kind="import",
+            removal_in="3.0.0",
+            info=f"importing {attr_name} from 'litestar.contrib.opentelemetry.middleware' is deprecated, please "
+            f"import it from 'litestar.plugins.opentelemetry' instead",
+        )
+        value = globals()[attr_name] = locals()[attr_name]
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")  # pragma: no cover
+
+
+if TYPE_CHECKING:
+    from litestar.plugins.opentelemetry import OpenTelemetryInstrumentationMiddleware

litestar/contrib/opentelemetry/plugin.py

@@ -0,0 +1,28 @@
+# ruff: noqa: TC004, F401
+from typing import TYPE_CHECKING
+
+from litestar.utils import warn_deprecation
+
+__all__ = ("OpenTelemetryPlugin",)
+
+
+def __getattr__(attr_name: str) -> object:
+    if attr_name in __all__:
+        from litestar.plugins.opentelemetry import OpenTelemetryPlugin
+
+        warn_deprecation(
+            deprecated_name=f"litestar.contrib.opentelemetry.plugin.{attr_name}",
+            version="3.0.0b0",
+            kind="import",
+            removal_in="3.0.0",
+            info=f"importing {attr_name} from 'litestar.contrib.opentelemetry.plugin' is deprecated, please "
+            f"import it from 'litestar.plugins.opentelemetry' instead",
+        )
+        value = globals()[attr_name] = locals()[attr_name]
+        return value
+
+    raise AttributeError(f"module {__name__!r} has no attribute {attr_name!r}")  # pragma: no cover
+
+
+if TYPE_CHECKING:
+    from litestar.plugins.opentelemetry import OpenTelemetryPlugin

tests/unit/test_contrib/test_opentelemetry.py

@@ -0,0 +1,86 @@
+# ruff: noqa: TC004, F401
+import importlib
+import sys
+from importlib.util import cache_from_source
+from pathlib import Path
+from typing import Union
+
+import pytest
+
+
+def purge_module(module_names: "list[str]", path: "Union[str, Path]") -> None:
+    for name in module_names:
+        if name in sys.modules:
+            del sys.modules[name]
+    Path(cache_from_source(str(path))).unlink(missing_ok=True)
+
+
+def test_deprecated_opentelemetry_imports() -> None:
+    purge_module(["litestar.contrib.opentelemetry"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryConfig from 'litestar.contrib.opentelemetry' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry import OpenTelemetryConfig
+
+    purge_module(["litestar.contrib.opentelemetry"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryInstrumentationMiddleware from 'litestar.contrib.opentelemetry' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry import OpenTelemetryInstrumentationMiddleware
+
+    purge_module(["litestar.contrib.opentelemetry"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryPlugin from 'litestar.contrib.opentelemetry' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry import OpenTelemetryPlugin
+
+
+def test_deprecated_opentelemetry_config_imports() -> None:
+    purge_module(["litestar.contrib.opentelemetry.config"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryConfig from 'litestar.contrib.opentelemetry.config' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry.config import OpenTelemetryConfig
+
+
+def test_deprecated_opentelemetry_middleware_imports() -> None:
+    purge_module(["litestar.contrib.opentelemetry.middleware"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryInstrumentationMiddleware from 'litestar.contrib.opentelemetry.middleware' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry.middleware import OpenTelemetryInstrumentationMiddleware
+
+
+def test_deprecated_opentelemetry_plugin_imports() -> None:
+    purge_module(["litestar.contrib.opentelemetry.plugin"], __file__)
+    with pytest.warns(
+        DeprecationWarning,
+        match="importing OpenTelemetryPlugin from 'litestar.contrib.opentelemetry.plugin' is deprecated",
+    ):
+        from litestar.contrib.opentelemetry.plugin import OpenTelemetryPlugin
+
+
+def test_contrib_imports_resolve_to_plugin_objects() -> None:
+    """Sanity check: deprecated symbols are the same object as the plugin location."""
+    purge_module(["litestar.contrib.opentelemetry"], __file__)
+    with pytest.warns(DeprecationWarning):
+        from litestar.contrib.opentelemetry import (
+            OpenTelemetryConfig as ContribConfig,
+            OpenTelemetryInstrumentationMiddleware as ContribMiddleware,
+            OpenTelemetryPlugin as ContribPlugin,
+        )
+
+    from litestar.plugins.opentelemetry import (
+        OpenTelemetryConfig,
+        OpenTelemetryInstrumentationMiddleware,
+        OpenTelemetryPlugin,
+    )
+
+    assert ContribConfig is OpenTelemetryConfig
+    assert ContribMiddleware is OpenTelemetryInstrumentationMiddleware
+    assert ContribPlugin is OpenTelemetryPlugin