refactor: rename _instrumentation to instrumentation, use from-imports, expand slash-normalization comment

Author: ocelotl

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_conversion.py

@@ -11,12 +11,11 @@
 
 from __future__ import annotations
 
-import dataclasses
-import enum
-import types
-import typing
 from collections.abc import Mapping
-from typing import Any, TypeVar, get_args, get_origin
+from dataclasses import fields, is_dataclass
+from enum import Enum
+from types import UnionType
+from typing import Any, TypeVar, Union, get_args, get_origin, get_type_hints
 
 _T = TypeVar("_T")
 
@@ -27,7 +26,7 @@ def _unwrap_optional(type_hint: Any) -> Any:
     Returns the unwrapped type, or the original hint if not a union with None.
     """
     origin = get_origin(type_hint)
-    if origin is types.UnionType or origin is typing.Union:
+    if origin is UnionType or origin is Union:
         non_none = [t for t in get_args(type_hint) if t is not type(None)]
         if len(non_none) == 1:
             return non_none[0]
@@ -58,15 +57,15 @@ def _convert_value(value: Any, type_hint: Any) -> Any:
     # Direct dataclass type — recurse
     if (
         isinstance(unwrapped, type)
-        and dataclasses.is_dataclass(unwrapped)
+        and is_dataclass(unwrapped)
         and isinstance(value, dict)
     ):
         return _dict_to_dataclass(value, unwrapped)
 
     # Enum type — coerce string/value to the Enum member
     if (
         isinstance(unwrapped, type)
-        and issubclass(unwrapped, enum.Enum)
+        and issubclass(unwrapped, Enum)
         and not isinstance(value, unwrapped)
     ):
         return unwrapped(value)
@@ -90,21 +89,24 @@ def _dict_to_dataclass(data: Mapping[str, Any], cls: type[_T]) -> _T:
     Raises:
         TypeError: If ``cls`` is not a dataclass type.
     """
-    if not dataclasses.is_dataclass(cls):
+    if not is_dataclass(cls):
         raise TypeError(f"{cls.__name__} is not a dataclass")
 
     # Annotated as ``dict[str, Any]`` so astroid stops tracing into
-    # ``typing.get_type_hints`` — under pylint 3.x that path leads into
+    # ``get_type_hints`` — under pylint 3.x that path leads into
     # Python 3.14's ``annotationlib`` (which uses t-strings) and crashes.
-    hints: dict[str, Any] = dict(
-        typing.get_type_hints(cls, include_extras=False)
-    )
-    known_fields = {f.name for f in dataclasses.fields(cls)}
+    hints: dict[str, Any] = dict(get_type_hints(cls, include_extras=False))
+    known_fields = {f.name for f in fields(cls)}
     kwargs: dict[str, Any] = {}
 
     for key, value in data.items():
-        # Schema keys like "otlp_file/development" use "/" as a namespace
-        # separator; Python field names use "_".  Normalise before lookup.
+        # The OTel configuration schema uses "/" as a namespace separator for
+        # development/experimental features (e.g. "otlp_file/development",
+        # "instrumentation/development").  Python identifiers cannot contain
+        # "/", so the corresponding dataclass fields use "_" instead (e.g.
+        # "otlp_file_development").  Without this normalisation the key would
+        # not match any known field and would fall through to
+        # additional_properties, causing the factory lookup to fail silently.
         field_key = key.replace("/", "_")
         if field_key in known_fields:
             type_hint = hints.get(field_key)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_sdk.py

@@ -20,7 +20,7 @@
 )
 from opentelemetry.sdk._configuration._propagator import configure_propagator
 from opentelemetry.sdk._configuration._resource import create_resource
-from opentelemetry.sdk._configuration._instrumentation import (
+from opentelemetry.sdk._configuration.instrumentation import (
     configure_instrumentation,
 )
 from opentelemetry.sdk._configuration._tracer_provider import (

…y/sdk/_configuration/_instrumentation.py …ry/sdk/_configuration/instrumentation.pyopentelemetry-sdk/src/opentelemetry/sdk/_configuration/_instrumentation.py renamed to opentelemetry-sdk/src/opentelemetry/sdk/_configuration/instrumentation.py opentelemetry-sdk/src/opentelemetry/sdk/_configuration/_instrumentation.py renamed to opentelemetry-sdk/src/opentelemetry/sdk/_configuration/instrumentation.py

@@ -3,38 +3,39 @@
 
 from __future__ import annotations
 
-import dataclasses
-import logging
+from dataclasses import fields
+from logging import getLogger
 
 from opentelemetry.sdk._configuration._common import load_entry_point
 from opentelemetry.sdk._configuration._conversion import _dict_to_dataclass
 from opentelemetry.sdk._configuration._exceptions import ConfigurationError
 from opentelemetry.sdk._configuration.models import ExperimentalInstrumentation
 
-_logger = logging.getLogger(__name__)
+_logger = getLogger(__name__)
 
 
 def configure_instrumentation(
-    config: ExperimentalInstrumentation | None,
+    configuration: ExperimentalInstrumentation | None,
 ) -> None:
     """Activate instrumentors listed under ``instrumentation/development.python``.
 
-    For each entry in ``config.python`` the matching ``opentelemetry_instrumentor``
-    entry point is loaded.  If the instrumentor class exposes a
-    ``config_dataclass`` attribute, the raw options are validated through
-    ``_dict_to_dataclass`` before being forwarded to ``instrument()``.
-    An ``enabled: false`` value suppresses instrumentation without raising.
+    For each entry in ``configuration.python`` the matching
+    ``opentelemetry_instrumentor`` entry point is loaded.  If the instrumentor
+    class exposes a ``config_dataclass`` attribute, the raw options are
+    validated through ``_dict_to_dataclass`` before being forwarded to
+    ``instrument()``.  An ``enabled: false`` value suppresses instrumentation
+    without raising.
 
     Absent or unknown entry points are logged as warnings; runtime errors from
     an instrumentor are logged as exceptions.  Neither stops the remaining
     instrumentors from being applied.
     """
-    if config is None or config.python is None:
+    if configuration is None or configuration.python is None:
         return
 
-    for name, opts in config.python.items():
-        opts = dict(opts)
-        if not opts.pop("enabled", True):
+    for name, options in configuration.python.items():
+        options = dict(options)
+        if not options.pop("enabled", True):
             _logger.debug(
                 "Instrumentation '%s' is disabled in declarative config; skipping",
                 name,
@@ -43,15 +44,15 @@ def configure_instrumentation(
 
         try:
             cls = load_entry_point("opentelemetry_instrumentor", name)
-            config_cls = getattr(cls, "config_dataclass", None)
-            if config_cls is not None:
-                config_obj = _dict_to_dataclass(opts, config_cls)
-                opts = {
+            configuration_cls = getattr(cls, "config_dataclass", None)
+            if configuration_cls is not None:
+                configuration_obj = _dict_to_dataclass(options, configuration_cls)
+                options = {
                     f.name: v
-                    for f in dataclasses.fields(config_obj)
-                    if (v := getattr(config_obj, f.name)) is not None
+                    for f in fields(configuration_obj)
+                    if (v := getattr(configuration_obj, f.name)) is not None
                 }
-            cls().instrument(**opts)
+            cls().instrument(**options)
             _logger.debug("Instrumented '%s' via declarative config", name)
         except ConfigurationError as exc:
             _logger.warning(

opentelemetry-sdk/tests/_configuration/test_instrumentation.py

@@ -7,12 +7,12 @@
 from unittest.mock import MagicMock, patch
 
 from opentelemetry.sdk._configuration._exceptions import ConfigurationError
-from opentelemetry.sdk._configuration._instrumentation import (
+from opentelemetry.sdk._configuration.instrumentation import (
     configure_instrumentation,
 )
 from opentelemetry.sdk._configuration.models import ExperimentalInstrumentation
 
-_LOAD_EP = "opentelemetry.sdk._configuration._instrumentation.load_entry_point"
+_LOAD_EP = "opentelemetry.sdk._configuration.instrumentation.load_entry_point"
 
 
 def _make_instrumentor_class(instance, config_dataclass=None):
@@ -32,7 +32,7 @@ def test_none_python_is_noop(self):
     @patch(_LOAD_EP, side_effect=ConfigurationError("not found"))
     def test_unknown_instrumentor_logs_warning(self, _mock_load):
         with self.assertLogs(
-            "opentelemetry.sdk._configuration._instrumentation",
+            "opentelemetry.sdk._configuration.instrumentation",
             level=logging.WARNING,
         ) as cm:
             configure_instrumentation(
@@ -136,7 +136,7 @@ def _side_effect(_group, _name):
         mock_load.side_effect = _side_effect
 
         with self.assertLogs(
-            "opentelemetry.sdk._configuration._instrumentation",
+            "opentelemetry.sdk._configuration.instrumentation",
             level=logging.ERROR,
         ):
             configure_instrumentation(
@@ -200,7 +200,7 @@ class StrictConfig:
         )
 
         with self.assertLogs(
-            "opentelemetry.sdk._configuration._instrumentation",
+            "opentelemetry.sdk._configuration.instrumentation",
             level=logging.ERROR,
         ):
             configure_instrumentation(