feat(config): recursively convert parsed dicts to typed dataclasses in loader by MikeGoldsmith · Pull Request #5269 · open-telemetry/opentelemetry-python

MikeGoldsmith · 2026-06-03T09:55:50Z

Description

Closes the gap between load_config_file() and the factory functions: YAML/JSON config → SDK objects now works end-to-end through the typed model tree.

Previously, the loader's _dict_to_model did OpenTelemetryConfiguration(**data) which only constructed the top-level dataclass — nested fields stayed as raw dicts. This meant factory functions like create_tracer_provider(config: TracerProviderConfig) would break trying to access config.sampler as an attribute when it was actually a dict.

Approach

Added _dict_to_dataclass in a new _conversion.py module. It walks each field's type annotation via typing.get_type_hints and recursively converts:

Nested dicts → typed dataclass instances (e.g. dict → TracerProvider → SpanProcessor → BatchSpanProcessor → ...)
Lists of dicts → lists of typed dataclasses (list[SpanProcessor])
String/value → Enum members (e.g. log_level: info → SeverityNumber.info)
Unknown keys → captured by the @_additional_properties decorator (so user-defined plugin names still flow through)

Optional[X] / X | None is unwrapped before checking the inner type. ClassVar fields are skipped (the additional_properties annotation on decorated classes is correctly ignored).

Verified end-to-end

yaml_data = '''
file_format: '1.0-rc.1'
tracer_provider:
  processors:
    - simple:
        exporter:
          console: {}
  sampler:
    parent_based:
      root:
        trace_id_ratio_based: {ratio: 0.5}
  limits:
    attribute_count_limit: 10
'''
config = _dict_to_model(yaml.safe_load(yaml_data))
provider = create_tracer_provider(config.tracer_provider)
# → TracerProvider with ParentBased sampler, 10 attribute limit, etc.

User-defined plugins continue to work — unknown sampler/propagator/exporter names land in additional_properties and are loaded via entry points.

Tests

11 new tests in test_conversion.py covering: flat dicts, nested dataclasses, lists, optionals, missing fields, unknown keys (additional_properties), enum coercion, primitive pass-through.

Closes #5127

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 open-telemetry#5127 Assisted-by: Claude Opus 4.6

- Use TypeVar for _dict_to_dataclass return — callers now get the correct type instead of Any - Use collections.abc.Mapping for input (more permissive than dict) - Add explicit is_dataclass check at entry — raises TypeError with a descriptive message instead of failing later in dataclasses.fields Assisted-by: Claude Opus 4.6

Astroid 3.x (used by pylint 3.x) follows typing.get_type_hints into Python 3.14's annotationlib, which contains t-string literals it can't parse and crashes with AttributeError on 'visit_templatestr'. Wrapping the call in a helper that returns dict[str, Any] stops the inference at the declared return type. Assisted-by: Claude Opus 4.7

Same effect as the prior helper — declaring the local as ``dict[str, Any]`` stops astroid's inference at the annotation rather than tracing into the typing internals. Assisted-by: Claude Opus 4.7

… codespell Replace the bespoke _Level enum (which violated pylint's invalid-name on lowercase members) with the real ExemplarFilter enum from models.py — the generated models use lowercase values verbatim from the JSON schema, so using one of them avoids fighting the linter and exercises the same code path with real data shapes. Add 'astroid' to codespell's ignore-words-list; the prior commit's explanatory comment mentions the library by name and codespell flagged it as a misspelling of 'asteroid'. Assisted-by: Claude Opus 4.7

DylanRussell · 2026-06-03T15:35:55Z

Looks good.. should we have a full e2e test like the one you described in your comment ? That seems useful

The conversion module has unit tests that exercise _dict_to_dataclass in isolation, but nothing verified the full pipeline: load a real YAML file, get back fully-typed nested dataclasses, and feed the result into a downstream factory function. Adds two checks built on a representative nested fixture (tracer provider with a parent-based / trace-id-ratio sampler and a batch processor with console exporter): - nested fields (sampler, processors[*].batch) come back as the expected typed dataclasses, not raw dicts - the typed result is accepted by ``create_tracer_provider`` and produces an SDK ``TracerProvider`` This is the integration coverage requested in PR review feedback; the inline example in the PR description is now an actual regression test. Assisted-by: Claude Opus 4.7

herin049 · 2026-06-06T01:46:49Z

+    dataclasses. Other values (primitives, enums, ``dict[str, Any]`` aliases)
+    pass through unchanged.
+    """
+    if value is None:


Do we want to raise an error if value is None, but type_hint is not optional?

The JSON schmea validator must have been run before handing these to the @DataClass so would have caught any non-null types. This func should only ever be accessible after that, so I don't think we need those checks. I can add them if you think it's worthwhile though.

herin049 · 2026-06-06T01:48:27Z

+    origin = get_origin(unwrapped)
+
+    # list[X] — recurse on each element
+    if origin is list and isinstance(value, list):


Should we raise an error here if origin is a list, but the value is not a list, or iterable?

Same as above

herin049 · 2026-06-06T01:50:23Z

+    ):
+        return unwrapped(value)
+
+    return value


I'm not sure how robust we want this function to be, but at this point the type of value and origin should be a primitive, do we want to validate this and raise an exception if the type of value and origin mismatch, and/or perform a coercion?

Same as above.

DylanRussell · 2026-06-08T13:47:31Z

+    def test_nested_fields_are_typed_dataclasses(self):
+        config = self._load()
+
+        self.assertIsInstance(config.tracer_provider, TracerProviderConfig)


nit: you could construct the TracerProvider and then just do self.assertEqual on the whole object

MikeGoldsmith requested a review from a team as a code owner June 3, 2026 09:55

rename changelog fragment to PR open-telemetry#5269

582c37f

otelbot-python Bot added this to Python PR digest Jun 3, 2026

MikeGoldsmith mentioned this pull request Jun 3, 2026

Add declarative configuration prototype #3631

Open

27 tasks

MikeGoldsmith added 3 commits June 3, 2026 11:16

inline the typing.get_type_hints wrap

131378c

Same effect as the prior helper — declaring the local as ``dict[str, Any]`` stops astroid's inference at the annotation rather than tracing into the typing internals. Assisted-by: Claude Opus 4.7

MikeGoldsmith moved this to Ready for review in Python PR digest Jun 3, 2026

This was referenced Jun 3, 2026

feat(config): add configure_sdk orchestrator for declarative config #5270

Draft

feat(config): honor OTEL_CONFIG_FILE in the SDK configurator #5271

Draft

MikeGoldsmith marked this pull request as draft June 3, 2026 14:29

DylanRussell approved these changes Jun 3, 2026

View reviewed changes

github-project-automation Bot moved this from Ready for review to Approved PRs in Python PR digest Jun 3, 2026

MikeGoldsmith marked this pull request as ready for review June 4, 2026 18:37

MikeGoldsmith mentioned this pull request Jun 5, 2026

feat(config): add public opentelemetry.sdk.configuration namespace #5276

Draft

11 tasks

MikeGoldsmith added 2 commits June 5, 2026 14:38

Merge branch 'main' into mike/config-recursive-dict-conversion

f6e0eac

herin049 reviewed Jun 6, 2026

View reviewed changes

DylanRussell reviewed Jun 8, 2026

View reviewed changes

DylanRussell approved these changes Jun 8, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(config): recursively convert parsed dicts to typed dataclasses in loader#5269

feat(config): recursively convert parsed dicts to typed dataclasses in loader#5269
MikeGoldsmith wants to merge 8 commits into
open-telemetry:mainfrom
MikeGoldsmith:mike/config-recursive-dict-conversion

MikeGoldsmith commented Jun 3, 2026

Uh oh!

DylanRussell commented Jun 3, 2026

Uh oh!

herin049 Jun 6, 2026

Uh oh!

MikeGoldsmith Jun 8, 2026

Uh oh!

herin049 Jun 6, 2026

Uh oh!

MikeGoldsmith Jun 8, 2026

Uh oh!

herin049 Jun 6, 2026

Uh oh!

MikeGoldsmith Jun 8, 2026

Uh oh!

DylanRussell Jun 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

MikeGoldsmith commented Jun 3, 2026

Description

Approach

Verified end-to-end

Tests

Uh oh!

DylanRussell commented Jun 3, 2026

Uh oh!

herin049 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

herin049 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

herin049 Jun 6, 2026

Choose a reason for hiding this comment

Uh oh!

MikeGoldsmith Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

DylanRussell Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants