opentelemetry-configuration 0.65b0__tar.gz

opentelemetry_configuration-0.65b0/.gitignore

@@ -0,0 +1,73 @@
+*.py[cod]
+*.sw[op]
+
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+include
+var
+sdist
+develop-eggs
+.installed.cfg
+pyvenv.cfg
+lib
+share/
+lib64
+__pycache__
+venv*/
+.venv*/
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+coverage.xml
+.coverage
+.nox
+.tox
+.cache
+htmlcov
+
+.agent/
+
+# Translations
+*.mo
+
+# Mac
+.DS_Store
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# JetBrains
+.idea
+
+# VSCode
+.vscode
+
+# Sphinx
+_build/
+
+# mypy
+.mypy_cache/
+target
+
+# Django example
+
+docs/examples/django/db.sqlite3
+
+# Semantic conventions
+scripts/semconv/semantic-conventions
+
+# Benchmark result files
+*-benchmark.json

opentelemetry_configuration-0.65b0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: opentelemetry-configuration
+Version: 0.65b0
+Summary: OpenTelemetry Python Declarative Configuration (experimental)
+Project-URL: Homepage, https://github.com/open-telemetry/opentelemetry-python/tree/main/opentelemetry-configuration
+Project-URL: Repository, https://github.com/open-telemetry/opentelemetry-python
+Author-email: OpenTelemetry Authors <cncf-opentelemetry-contributors@lists.cncf.io>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: OpenTelemetry
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: opentelemetry-api==1.44.0
+Requires-Dist: opentelemetry-sdk==1.44.0
+Requires-Dist: pyyaml>=5.4
+Description-Content-Type: text/x-rst
+
+OpenTelemetry Python SDK Declarative Configuration
+===================================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-configuration.svg
+    :target: https://pypi.org/project/opentelemetry-configuration/
+
+.. warning::
+
+   This package is **experimental**. The API surface, type names, and behaviour
+   may change between minor versions. Pin a specific version in production.
+
+This package implements the `OpenTelemetry declarative configuration
+specification <https://opentelemetry.io/docs/specs/otel/configuration/>`_ for
+the Python SDK. It parses a YAML or JSON configuration file (or
+programmatically-constructed configuration model) into typed dataclasses and
+applies the result to the global SDK providers.
+
+The standard activation path is the ``OTEL_CONFIG_FILE`` environment variable,
+which the SDK's configurator picks up automatically. Set the variable and run
+your app under ``opentelemetry-instrument``; no code change is required.
+
+For programmatic use:
+
+.. code-block:: python
+
+    from opentelemetry.configuration import configure_sdk, load_config_file
+
+    config = load_config_file("otel-config.yaml")
+    configure_sdk(config)
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-configuration
+
+References
+----------
+
+* `OpenTelemetry declarative configuration specification
+  <https://opentelemetry.io/docs/specs/otel/configuration/>`_
+* `Language support status matrix
+  <https://github.com/open-telemetry/opentelemetry-configuration/blob/main/language-support-status.md#python>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

opentelemetry_configuration-0.65b0/README.rst

@@ -0,0 +1,47 @@
+OpenTelemetry Python SDK Declarative Configuration
+===================================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/opentelemetry-configuration.svg
+    :target: https://pypi.org/project/opentelemetry-configuration/
+
+.. warning::
+
+   This package is **experimental**. The API surface, type names, and behaviour
+   may change between minor versions. Pin a specific version in production.
+
+This package implements the `OpenTelemetry declarative configuration
+specification <https://opentelemetry.io/docs/specs/otel/configuration/>`_ for
+the Python SDK. It parses a YAML or JSON configuration file (or
+programmatically-constructed configuration model) into typed dataclasses and
+applies the result to the global SDK providers.
+
+The standard activation path is the ``OTEL_CONFIG_FILE`` environment variable,
+which the SDK's configurator picks up automatically. Set the variable and run
+your app under ``opentelemetry-instrument``; no code change is required.
+
+For programmatic use:
+
+.. code-block:: python
+
+    from opentelemetry.configuration import configure_sdk, load_config_file
+
+    config = load_config_file("otel-config.yaml")
+    configure_sdk(config)
+
+Installation
+------------
+
+::
+
+    pip install opentelemetry-configuration
+
+References
+----------
+
+* `OpenTelemetry declarative configuration specification
+  <https://opentelemetry.io/docs/specs/otel/configuration/>`_
+* `Language support status matrix
+  <https://github.com/open-telemetry/opentelemetry-configuration/blob/main/language-support-status.md#python>`_
+* `OpenTelemetry Project <https://opentelemetry.io/>`_

opentelemetry_configuration-0.65b0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opentelemetry-configuration"
+dynamic = ["version"]
+description = "OpenTelemetry Python Declarative Configuration (experimental)"
+readme = "README.rst"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+  { name = "OpenTelemetry Authors", email = "cncf-opentelemetry-contributors@lists.cncf.io" },
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: OpenTelemetry",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "opentelemetry-api == 1.44.0",
+  "opentelemetry-sdk == 1.44.0",
+  "pyyaml >= 5.4",
+  "jsonschema >= 4.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/open-telemetry/opentelemetry-python/tree/main/opentelemetry-configuration"
+Repository = "https://github.com/open-telemetry/opentelemetry-python"
+
+[tool.hatch.version]
+path = "src/opentelemetry/configuration/version/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]

opentelemetry_configuration-0.65b0/src/opentelemetry/configuration/README.md

@@ -0,0 +1,28 @@
+# SDK Declarative Configuration
+
+This package implements [OpenTelemetry file-based configuration](https://opentelemetry.io/docs/specs/otel/configuration).
+
+## Files
+
+- `schema.json`: vendored copy of the [OpenTelemetry configuration JSON schema](https://github.com/open-telemetry/opentelemetry-configuration)
+- `models.py`: Python dataclasses generated from `schema.json` by [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator), using a custom template from `opentelemetry-configuration/codegen/` (see that directory's README for details)
+
+## Spec conformance
+
+Which fields of the configuration schema the Python SDK actually applies at runtime is tracked in the shared [language support status matrix](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/language-support-status.md#python) in the `opentelemetry-configuration` repository. The Python column is the source of truth; update [`schema/meta_schema_language_python.yaml`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema/meta_schema_language_python.yaml) there when wiring lands or changes, and the matrix regenerates.
+
+## Updating the schema
+
+1. Pick the desired release tag from the [opentelemetry-configuration releases](https://github.com/open-telemetry/opentelemetry-configuration/releases) and overwrite `opentelemetry-configuration/src/opentelemetry/configuration/schema.json` with the `opentelemetry_configuration.json` published on that release.
+
+2. Regenerate `models.py`:
+
+   ```sh
+   tox -e generate-config-from-jsonschema
+   ```
+
+3. Update any version string references in tests and source:
+
+   ```sh
+   grep -r "OLD_VERSION" opentelemetry-configuration/
+   ```

opentelemetry_configuration-0.65b0/src/opentelemetry/configuration/__init__.py

@@ -0,0 +1,42 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""OpenTelemetry SDK Declarative Configuration.
+
+This package implements the OpenTelemetry declarative configuration
+specification for the Python SDK. Load a YAML or JSON configuration file
+(or build a configuration model programmatically) and apply it to the
+process-global SDK providers.
+
+The standard activation path is the ``OTEL_CONFIG_FILE`` environment
+variable, which the SDK's configurator picks up automatically. For
+programmatic use:
+
+>>> from opentelemetry.configuration import (
+...     load_config_file, configure_sdk,
+... )
+>>> config = load_config_file("otel-config.yaml")
+>>> configure_sdk(config)
+
+Construct a configuration programmatically and apply it:
+
+>>> from opentelemetry.configuration import (
+...     OpenTelemetryConfiguration, configure_sdk,
+... )
+>>> configure_sdk(OpenTelemetryConfiguration(file_format="1.0-rc.1"))
+
+This package is **experimental**. The API surface, type names, and
+behaviour may change between minor versions.
+"""
+
+from opentelemetry.configuration._exceptions import ConfigurationError
+from opentelemetry.configuration._sdk import configure_sdk
+from opentelemetry.configuration.file._loader import load_config_file
+from opentelemetry.configuration.models import OpenTelemetryConfiguration
+
+__all__ = [
+    "ConfigurationError",
+    "OpenTelemetryConfiguration",
+    "configure_sdk",
+    "load_config_file",
+]

opentelemetry_configuration-0.65b0/src/opentelemetry/configuration/_common.py

@@ -0,0 +1,238 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import dataclasses
+import inspect
+import logging
+from collections.abc import Callable
+from typing import Any, Protocol
+from urllib.parse import urlparse
+
+from opentelemetry.configuration._exceptions import ConfigurationError
+from opentelemetry.util._importlib_metadata import entry_points
+
+_logger = logging.getLogger(__name__)
+
+
+def _additional_properties(cls):
+    """Decorator for dataclasses whose JSON Schema sets additionalProperties.
+
+    Wraps the dataclass-generated ``__init__`` so that extra keyword
+    arguments are captured into an ``additional_properties`` instance
+    attribute instead of raising ``TypeError``.  This lets user-defined
+    component names flow through the config pipeline without modifying
+    the codegen output for built-in fields.
+
+    Applied automatically by the custom template in ``opentelemetry-sdk/codegen/``
+    when ``additionalPropertiesType`` is present in the template context
+    (set by ``datamodel-codegen`` for schema types with ``additionalProperties``).
+    """
+    original_init = cls.__init__
+    original_sig = inspect.signature(original_init)
+    known_fields = frozenset(f.name for f in dataclasses.fields(cls))
+
+    def _init(self, **kwargs):
+        known = {k: v for k, v in kwargs.items() if k in known_fields}
+        extra = {k: v for k, v in kwargs.items() if k not in known_fields}
+        original_init(self, **known)
+        self.additional_properties = extra
+
+    # Preserve the original parameter list for IDE autocompletion and
+    # inspect.signature(), adding **kwargs to signal extras are accepted.
+    # setattr used because pyright rejects direct __signature__ assignment.
+    params = list(original_sig.parameters.values())
+    params.append(inspect.Parameter("kwargs", inspect.Parameter.VAR_KEYWORD))
+    setattr(_init, "__signature__", original_sig.replace(parameters=params))  # noqa: B010
+
+    cls.__init__ = _init
+    return cls
+
+
+def load_entry_point(group: str, name: str) -> type:
+    """Load a plugin class from an entry point group by name.
+
+    Returns the loaded class — callers are responsible for instantiation
+    with whatever arguments their config requires.
+
+    Raises:
+        ConfigurationError: If the entry point is not found or fails to load.
+    """
+    try:
+        ep = next(iter(entry_points(group=group, name=name)), None)
+        if ep is None:
+            raise ConfigurationError(
+                f"Plugin '{name}' not found in group '{group}'. "
+                "Make sure the package providing this plugin is installed."
+            )
+        return ep.load()
+    except ConfigurationError:
+        raise
+    except Exception as exc:
+        raise ConfigurationError(
+            f"Failed to load plugin '{name}' from group '{group}': {exc}"
+        ) from exc
+
+
+class _ComponentConfig(Protocol):
+    """Protocol for config dataclasses decorated with @_additional_properties.
+
+    Values in ``additional_properties`` are nested config dicts (suitable
+    for ``**kwargs`` splatting to the user-defined component class) or
+    ``None`` (when the YAML uses ``my_plugin:`` or ``my_plugin: null``).
+
+    Note: the generated models declare ``additional_properties`` as a
+    ``ClassVar`` even though the decorator assigns it as an instance
+    attribute at runtime. This is tolerated by pyright in ``standard``
+    mode but flagged in ``strict`` mode. See #5268.
+    """
+
+    additional_properties: dict[str, dict[str, Any] | None]
+
+
+def _resolve_component(
+    config: _ComponentConfig,
+    registry: dict[str, Callable[[Any], Any]],
+    entry_point_group: str,
+    component_type: str,
+) -> Any:
+    """Resolve a config dataclass to a component instance.
+
+    Checks built-in factories in ``registry`` first (by matching typed
+    field names on ``config``), then falls back to entry point loading
+    for plugin components found in ``config.additional_properties``.
+
+    The JSON schema enforces exactly one component per config block
+    (``minProperties: 1, maxProperties: 1``). If multiple typed fields or
+    ``additional_properties`` entries are set (e.g. when schema validation
+    is bypassed), the first registry match wins.
+
+    Args:
+        config: A dataclass with ``additional_properties`` (from the
+            ``@_additional_properties`` decorator).
+        registry: Mapping of built-in component names to factory
+            callables. Each factory receives the field value from config.
+        entry_point_group: The entry point group name for plugin loading.
+        component_type: Human-readable name for error messages
+            (e.g. "span exporter").
+
+    Returns:
+        The resolved component instance.
+
+    Raises:
+        ConfigurationError: If no component type is specified in config.
+    """
+    for name, factory in registry.items():
+        value = getattr(config, name, None)
+        if value is not None:
+            return factory(value)
+    if config.additional_properties:
+        name, plugin_config = next(iter(config.additional_properties.items()))
+        return load_entry_point(entry_point_group, name)(
+            **(plugin_config or {})
+        )
+    raise ConfigurationError(f"No {component_type} type specified in config.")
+
+
+def _parse_headers(
+    headers: list | None,
+    headers_list: str | None,
+) -> dict[str, str] | None:
+    """Merge headers struct and headers_list into a dict.
+
+    Returns None if neither is set, letting the exporter read env vars.
+    headers struct takes priority over headers_list for the same key.
+    """
+    if headers is None and headers_list is None:
+        return None
+    result: dict[str, str] = {}
+    if headers_list:
+        for item in headers_list.split(","):
+            item = item.strip()
+            if "=" in item:
+                key, value = item.split("=", 1)
+                result[key.strip()] = value.strip()
+            elif item:
+                _logger.warning(
+                    "Invalid header pair in headers_list (missing '='): %s",
+                    item,
+                )
+    if headers:
+        for pair in headers:
+            if isinstance(pair, dict):
+                result[pair["name"]] = pair.get("value") or ""
+            else:
+                result[pair.name] = pair.value or ""
+    return result
+
+
+def _map_compression(
+    value: str | None,
+    compression_enum: type,
+    *,
+    allow_deflate: bool = False,
+) -> object | None:
+    """Map a compression string to the given Compression enum value."""
+    if value is None:
+        return None
+
+    value_lower = value.lower()
+    supports_deflate = hasattr(compression_enum, "Deflate")
+
+    if value_lower == "none":
+        return None
+    if value_lower == "gzip":
+        return compression_enum.Gzip  # type: ignore[attr-defined]
+    if value_lower == "deflate" and allow_deflate and supports_deflate:
+        return compression_enum.Deflate  # type: ignore[attr-defined]
+
+    supported_values = ["'gzip'", "'none'"]
+    if allow_deflate and supports_deflate:
+        supported_values.insert(1, "'deflate'")
+
+    raise ConfigurationError(
+        f"Unsupported compression value '{value}'. Supported values: "
+        f"{', '.join(supported_values)}."
+    )
+
+
+def _parse_otlp_file_output_stream(output_stream: str | None) -> str | None:
+    """Resolve an output_stream value to a file path, or None for stdout.
+
+    Per the OTel file exporter spec, output_stream is "stdout" (or
+    None, which means the same), or a "file://" URI giving a path.
+    """
+    if output_stream is None or output_stream == "stdout":
+        return None
+    try:
+        parsed = urlparse(output_stream)
+    except ValueError as exc:
+        raise ConfigurationError(
+            f"Failed to parse output_stream '{output_stream}' for "
+            f"otlp_file_development exporter: {exc}"
+        ) from exc
+    is_local_file_uri = (
+        parsed.scheme == "file"
+        and parsed.netloc in ("", "localhost")
+        and bool(parsed.path)
+    )
+    has_extra_components = parsed.params or parsed.query or parsed.fragment
+    if is_local_file_uri and not has_extra_components:
+        path = parsed.path
+        if not path.startswith("/"):
+            raise ConfigurationError(
+                f"Unsupported output_stream '{output_stream}' for "
+                "otlp_file_development exporter. Path must be absolute."
+            )
+        if path.endswith("/"):
+            raise ConfigurationError(
+                f"Unsupported output_stream '{output_stream}' for "
+                "otlp_file_development exporter. Path must be a file, "
+                "not a directory."
+            )
+        return path
+    raise ConfigurationError(
+        f"Unsupported output_stream '{output_stream}' for otlp_file_development "
+        "exporter. Supported values: stdout, file://<path>."
+    )

opentelemetry_configuration-0.65b0/src/opentelemetry/configuration/_conversion.py

@@ -0,0 +1,118 @@
+# 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
+
+from collections.abc import Mapping
+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")
+
+
+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 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]
+    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 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)
+        and not isinstance(value, unwrapped)
+    ):
+        return unwrapped(value)
+
+    return value
+
+
+def _dict_to_dataclass(data: Mapping[str, Any], cls: type[_T]) -> _T:
+    """Recursively convert a mapping 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.
+
+    Raises:
+        TypeError: If ``cls`` is not a dataclass type.
+    """
+    if not is_dataclass(cls):
+        raise TypeError(f"{cls.__name__} is not a dataclass")
+
+    # Annotated as ``dict[str, Any]`` so astroid stops tracing 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(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():
+        # 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)
+            kwargs[field_key] = _convert_value(value, type_hint)
+        else:
+            # Unknown key — @_additional_properties decorator will capture it.
+            kwargs[key] = value
+
+    return cls(**kwargs)