recursively convert parsed dicts to typed dataclasses in loader

Adds `_dict_to_dataclass` in `_conversion.py` which walks each field's
type annotation and converts:
- nested dicts → typed dataclass instances
- lists of dicts → lists of typed dataclasses
- string/value → Enum members (e.g. log_level: info)
- unknown keys → routed to the @_additional_properties decorator

The loader's `_dict_to_model` now produces a fully-typed
OpenTelemetryConfiguration tree end-to-end. Factory functions can rely
on typed attribute access (config.tracer_provider.processors[0].batch
.exporter.otlp_http.endpoint) instead of failing on raw dicts.

This closes the gap between load_config_file() and the factory
functions — YAML/JSON config → SDK objects now works end-to-end.

Closes #5127

Assisted-by: Claude Opus 4.6

Author: MikeGoldsmith

.changelog/XXXX.added

@@ -0,0 +1 @@
+`opentelemetry-sdk`: declarative config loader now recursively converts parsed dicts into typed dataclass instances, including nested dataclasses, lists of dataclasses, and enum values. End-to-end YAML/JSON → SDK configuration now works via the factory functions.

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

@@ -0,0 +1,101 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""Recursive dict-to-dataclass conversion for parsed config data.
+
+The YAML/JSON loader produces nested dicts. Factory functions expect typed
+dataclass instances (e.g. ``TracerProvider``, ``SpanProcessor``). This module
+walks each field's type annotation and converts nested dicts into their
+corresponding dataclass types.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import enum
+import types
+import typing
+from typing import Any, Union, get_args, get_origin
+
+
+def _unwrap_optional(type_hint: Any) -> Any:
+    """Strip ``None`` from a ``X | None`` / ``Optional[X]`` annotation.
+
+    Returns the unwrapped type, or the original hint if not a Union with None.
+    """
+    origin = get_origin(type_hint)
+    if origin is Union or origin is types.UnionType:
+        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]
+    return type_hint
+
+
+def _convert_value(value: Any, type_hint: Any) -> Any:
+    """Convert a value according to its type hint.
+
+    Recursively converts dicts to dataclasses and lists of dicts to lists of
+    dataclasses. Other values (primitives, enums, ``dict[str, Any]`` aliases)
+    pass through unchanged.
+    """
+    if value is None:
+        return None
+
+    unwrapped = _unwrap_optional(type_hint)
+    origin = get_origin(unwrapped)
+
+    # list[X] — recurse on each element
+    if origin is list and isinstance(value, list):
+        args = get_args(unwrapped)
+        if args:
+            item_type = args[0]
+            return [_convert_value(item, item_type) for item in value]
+        return value
+
+    # Direct dataclass type — recurse
+    if (
+        isinstance(unwrapped, type)
+        and dataclasses.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 not isinstance(value, unwrapped)
+    ):
+        return unwrapped(value)
+
+    return value
+
+
+def _dict_to_dataclass(data: dict[str, Any], cls: type) -> Any:
+    """Recursively convert a dict to a dataclass instance.
+
+    For each key in ``data``:
+    - If it matches a known dataclass field, the value is converted according
+      to that field's type annotation (recursing for nested dataclasses).
+    - Unknown keys are passed through as kwargs; classes decorated with
+      ``@_additional_properties`` will capture them on the instance's
+      ``additional_properties`` attribute.
+
+    ``ClassVar`` fields (e.g. the ``additional_properties`` annotation on
+    decorated dataclasses) are ignored as expected.
+    """
+    if not dataclasses.is_dataclass(cls):
+        return data
+
+    hints = typing.get_type_hints(cls, include_extras=False)
+    known_fields = {f.name for f in dataclasses.fields(cls)}
+    kwargs: dict[str, Any] = {}
+
+    for key, value in data.items():
+        if key in known_fields:
+            kwargs[key] = _convert_value(value, hints.get(key))
+        else:
+            # Unknown key — @_additional_properties decorator will capture it.
+            kwargs[key] = value
+
+    return cls(**kwargs)

opentelemetry-sdk/src/opentelemetry/sdk/_configuration/file/_loader.py

@@ -9,6 +9,7 @@
 from pathlib import Path
 from typing import Any
 
+from opentelemetry.sdk._configuration._conversion import _dict_to_dataclass
 from opentelemetry.sdk._configuration._exceptions import ConfigurationError
 from opentelemetry.sdk._configuration.file._env_substitution import (
     substitute_env_vars,
@@ -172,10 +173,13 @@ def _validate_schema(data: dict) -> None:
 
 
 def _dict_to_model(data: dict[str, Any]) -> OpenTelemetryConfiguration:
-    """Convert dictionary to OpenTelemetryConfiguration model.
+    """Convert a parsed config dictionary to the full typed model tree.
 
-    Uses the generated dataclass from models.py. This provides basic
-    validation through dataclass field types.
+    Walks each field's type annotation, recursively converting nested
+    dicts to their corresponding dataclass types. The resulting
+    ``OpenTelemetryConfiguration`` is fully typed end-to-end, so factory
+    functions can rely on typed attribute access (e.g. ``config.sampler``,
+    ``config.processors[0].batch.exporter``).
 
     Args:
         data: Parsed configuration dictionary.
@@ -187,15 +191,9 @@ def _dict_to_model(data: dict[str, Any]) -> OpenTelemetryConfiguration:
         TypeError: If data doesn't match expected structure.
         ValueError: If values are invalid.
     """
-    # Construct the top-level model from the validated dict. Nested fields
-    # are stored as dicts rather than their dataclass types; factory functions
-    # in later PRs will handle the full recursive conversion when building
-    # SDK objects.
     try:
-        config = OpenTelemetryConfiguration(**data)
-        return config
+        return _dict_to_dataclass(data, OpenTelemetryConfiguration)
     except TypeError as exc:
-        # Provide more helpful error message
         raise TypeError(
             f"Configuration structure is invalid. "
             f"Check that all required fields are present and correctly typed: {exc}"

opentelemetry-sdk/tests/_configuration/test_conversion.py

@@ -0,0 +1,110 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+# Tests access private members of SDK classes to assert correct configuration.
+# pylint: disable=protected-access
+
+import unittest
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, ClassVar
+
+from opentelemetry.sdk._configuration._common import _additional_properties
+from opentelemetry.sdk._configuration._conversion import _dict_to_dataclass
+
+
+@dataclass
+class _Inner:
+    value: int | None = None
+
+
+@dataclass
+class _Middle:
+    inner: _Inner | None = None
+    items: list[_Inner] | None = None
+
+
+@dataclass
+class _Outer:
+    middle: _Middle | None = None
+    name: str | None = None
+
+
+@_additional_properties
+@dataclass
+class _WithExtras:
+    known: str | None = None
+    additional_properties: ClassVar[dict[str, Any]]
+
+
+class _Level(Enum):
+    info = "info"
+    warn = "warn"
+
+
+@dataclass
+class _WithEnum:
+    level: _Level | None = None
+
+
+class TestDictToDataclass(unittest.TestCase):
+    def test_returns_data_unchanged_for_non_dataclass(self):
+        self.assertEqual(_dict_to_dataclass({"x": 1}, dict), {"x": 1})
+
+    def test_converts_flat_dict(self):
+        result = _dict_to_dataclass({"value": 42}, _Inner)
+        self.assertIsInstance(result, _Inner)
+        self.assertEqual(result.value, 42)
+
+    def test_converts_nested_dataclass(self):
+        result = _dict_to_dataclass(
+            {"middle": {"inner": {"value": 7}}}, _Outer
+        )
+        self.assertIsInstance(result, _Outer)
+        self.assertIsInstance(result.middle, _Middle)
+        self.assertIsInstance(result.middle.inner, _Inner)
+        self.assertEqual(result.middle.inner.value, 7)
+
+    def test_converts_list_of_dataclasses(self):
+        result = _dict_to_dataclass(
+            {"middle": {"items": [{"value": 1}, {"value": 2}]}}, _Outer
+        )
+        self.assertEqual(len(result.middle.items), 2)
+        self.assertIsInstance(result.middle.items[0], _Inner)
+        self.assertEqual(result.middle.items[0].value, 1)
+        self.assertEqual(result.middle.items[1].value, 2)
+
+    def test_none_value_preserved(self):
+        result = _dict_to_dataclass({"middle": None, "name": "test"}, _Outer)
+        self.assertIsNone(result.middle)
+        self.assertEqual(result.name, "test")
+
+    def test_missing_optional_fields_default_to_none(self):
+        result = _dict_to_dataclass({}, _Outer)
+        self.assertIsNone(result.middle)
+        self.assertIsNone(result.name)
+
+    def test_unknown_keys_routed_to_additional_properties(self):
+        result = _dict_to_dataclass(
+            {"known": "yes", "my_plugin": {"opt": True}}, _WithExtras
+        )
+        self.assertEqual(result.known, "yes")
+        self.assertEqual(
+            result.additional_properties, {"my_plugin": {"opt": True}}
+        )
+
+    def test_primitive_values_pass_through(self):
+        result = _dict_to_dataclass({"name": "hello"}, _Outer)
+        self.assertEqual(result.name, "hello")
+
+    def test_empty_list_converted(self):
+        result = _dict_to_dataclass({"middle": {"items": []}}, _Outer)
+        self.assertEqual(result.middle.items, [])
+
+    def test_enum_value_coerced_from_string(self):
+        result = _dict_to_dataclass({"level": "info"}, _WithEnum)
+        self.assertIs(result.level, _Level.info)
+
+    def test_enum_value_already_enum_passes_through(self):
+        result = _dict_to_dataclass({"level": _Level.warn}, _WithEnum)
+        self.assertIs(result.level, _Level.warn)