dash0-opentelemetry-configuration 0.65b0.post1__tar.gz

dash0_opentelemetry_configuration-0.65b0.post1/.gitignore

@@ -0,0 +1,28 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+tests/e2e-kubernetes/uv.lock

dash0_opentelemetry_configuration-0.65b0.post1/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.5
+Name: dash0-opentelemetry-configuration
+Version: 0.65b0.post1
+Summary: Declarative configuration for the Dash0 OpenTelemetry distribution
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api==1.44.0
+Requires-Dist: opentelemetry-sdk==1.44.0
+Requires-Dist: pyyaml
+Description-Content-Type: text/x-rst
+
+Dash0 OpenTelemetry Declarative Configuration
+=============================================
+
+Declarative (file-based) SDK configuration for the Dash0 OpenTelemetry Python
+distribution, read from ``OTEL_CONFIG_FILE``.
+
+The package is experimental, tracking a configuration format that is still at
+``1.0-rc.1``.
+
+Do not edit this package by hand
+--------------------------------
+
+Everything under ``src/`` and the whole of ``pyproject.toml`` are generated by
+``scripts/vendor_configuration.py`` from the ``dash0`` branch of
+https://github.com/dash0hq/opentelemetry-python. The ``UPSTREAM`` file records
+the exact commit. A hand edit here is reverted by the next run of that script,
+and the ``vendored-configuration`` job in CI fails while it is still present.
+
+Two files are exempt, because the script leaves them alone: this README, and
+``src/opentelemetry/_configuration/version/__init__.py``, which holds the
+released version and is advanced by ``scripts/bump_for_release.py``.
+
+Where a change belongs
+----------------------
+
+Changes to how configuration files are parsed, validated or applied go on the
+fork's ``dash0`` branch, as commits on top of an upstream commit. That is what
+makes them survive upstream moving: rebase the branch onto the new upstream
+commit, then run::
+
+    python3 scripts/vendor_configuration.py --commit <new sha>
+
+Changes to how the code is packaged for this distribution go in
+``scripts/vendor_configuration.py``. It owns the rename from
+``opentelemetry.configuration`` to ``opentelemetry._configuration``, the
+re-export shims at the path the SDK imports, and the dependency pins, which it
+copies from the distribution's own pins rather than repeating them.
+
+Why the implementation sits at a private path
+---------------------------------------------
+
+The implementation is installed as ``opentelemetry._configuration``, a path
+upstream does not own, and ``opentelemetry.configuration`` holds only star
+re-export shims. ``opentelemetry/sdk/_configuration/__init__.py`` imports
+``opentelemetry.configuration`` by name, so the shims are what make
+``OTEL_CONFIG_FILE`` work, while the private path means installing this
+alongside a future published ``opentelemetry-configuration`` cannot collide
+file for file. The pyproto exporter packages in this workspace use the same
+arrangement.
+
+What the fork changes
+---------------------
+
+Upstream validates configuration files with ``jsonschema``, which brings
+``attrs``, ``referencing``, ``jsonschema-specifications`` and ``rpds-py``. All
+four would land in the tree the injector adds to an application's
+``sys.path``, and ``rpds-py`` is a compiled extension, so that tree would stop
+being pure Python. The fork compiles the schema to plain Python with
+``fastjsonschema`` at development time instead, leaving a validator that
+imports ``decimal`` and nothing else. The fork's own test suite checks that
+validator against ``jsonschema`` document by document.

dash0_opentelemetry_configuration-0.65b0.post1/README.rst

@@ -0,0 +1,61 @@
+Dash0 OpenTelemetry Declarative Configuration
+=============================================
+
+Declarative (file-based) SDK configuration for the Dash0 OpenTelemetry Python
+distribution, read from ``OTEL_CONFIG_FILE``.
+
+The package is experimental, tracking a configuration format that is still at
+``1.0-rc.1``.
+
+Do not edit this package by hand
+--------------------------------
+
+Everything under ``src/`` and the whole of ``pyproject.toml`` are generated by
+``scripts/vendor_configuration.py`` from the ``dash0`` branch of
+https://github.com/dash0hq/opentelemetry-python. The ``UPSTREAM`` file records
+the exact commit. A hand edit here is reverted by the next run of that script,
+and the ``vendored-configuration`` job in CI fails while it is still present.
+
+Two files are exempt, because the script leaves them alone: this README, and
+``src/opentelemetry/_configuration/version/__init__.py``, which holds the
+released version and is advanced by ``scripts/bump_for_release.py``.
+
+Where a change belongs
+----------------------
+
+Changes to how configuration files are parsed, validated or applied go on the
+fork's ``dash0`` branch, as commits on top of an upstream commit. That is what
+makes them survive upstream moving: rebase the branch onto the new upstream
+commit, then run::
+
+    python3 scripts/vendor_configuration.py --commit <new sha>
+
+Changes to how the code is packaged for this distribution go in
+``scripts/vendor_configuration.py``. It owns the rename from
+``opentelemetry.configuration`` to ``opentelemetry._configuration``, the
+re-export shims at the path the SDK imports, and the dependency pins, which it
+copies from the distribution's own pins rather than repeating them.
+
+Why the implementation sits at a private path
+---------------------------------------------
+
+The implementation is installed as ``opentelemetry._configuration``, a path
+upstream does not own, and ``opentelemetry.configuration`` holds only star
+re-export shims. ``opentelemetry/sdk/_configuration/__init__.py`` imports
+``opentelemetry.configuration`` by name, so the shims are what make
+``OTEL_CONFIG_FILE`` work, while the private path means installing this
+alongside a future published ``opentelemetry-configuration`` cannot collide
+file for file. The pyproto exporter packages in this workspace use the same
+arrangement.
+
+What the fork changes
+---------------------
+
+Upstream validates configuration files with ``jsonschema``, which brings
+``attrs``, ``referencing``, ``jsonschema-specifications`` and ``rpds-py``. All
+four would land in the tree the injector adds to an application's
+``sys.path``, and ``rpds-py`` is a compiled extension, so that tree would stop
+being pure Python. The fork compiles the schema to plain Python with
+``fastjsonschema`` at development time instead, leaving a validator that
+imports ``decimal`` and nothing else. The fork's own test suite checks that
+validator against ``jsonschema`` document by document.

dash0_opentelemetry_configuration-0.65b0.post1/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dash0-opentelemetry-configuration"
+dynamic = ["version"]
+description = "Declarative configuration for the Dash0 OpenTelemetry distribution"
+readme = "README.rst"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+  "opentelemetry-api == 1.44.0",
+  "opentelemetry-sdk == 1.44.0",
+  "pyyaml",
+]
+
+[tool.hatch.version]
+path = "src/opentelemetry/_configuration/version/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = ["/src"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dash0_opentelemetry_configuration-0.65b0.post1/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/
+   ```

dash0_opentelemetry_configuration-0.65b0.post1/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",
+]

dash0_opentelemetry_configuration-0.65b0.post1/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>."
+    )

dash0_opentelemetry_configuration-0.65b0.post1/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)

dash0_opentelemetry_configuration-0.65b0.post1/src/opentelemetry/_configuration/_exceptions.py

@@ -0,0 +1,59 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+
+class ConfigurationError(Exception):
+    """Raised when configuration loading, parsing, validation, or instantiation fails.
+
+    This includes errors from:
+    - File not found or inaccessible
+    - Invalid YAML/JSON syntax
+    - Schema validation failures
+    - Environment variable substitution errors
+    - Missing required SDK extensions (e.g., propagator packages not installed)
+    """
+
+
+class MissingDependencyError(ConfigurationError, ImportError):
+    """Raised when an optional dependency is not installed.
+
+    Inherits from both :class:`ConfigurationError` and :class:`ImportError` to
+    maintain backwards compatibility with callers that catch ``ImportError``.
+
+    Args:
+        package: The name of the missing package.
+        feature: Optional description of the feature that requires the package.
+        install_name: Optional package name used in the pip install command
+            (defaults to ``package``).
+        extras: Optional extras string for the pip install command.
+    """
+
+    def __init__(
+        self,
+        package: str,
+        feature: str | None = None,
+        install_name: str | None = None,
+        extras: str | None = None,
+    ) -> None:
+        self.package = package
+        self.feature = feature
+        self.install_name = install_name or package
+        self.extras = extras
+
+        if extras:
+            install_cmd = f'pip install "{self.install_name}[{extras}]"'
+        else:
+            install_cmd = f"pip install {self.install_name}"
+
+        if feature:
+            message = (
+                f"{feature} requires '{package}'. "
+                f"Install it with: {install_cmd}"
+            )
+        else:
+            message = (
+                f"'{package}' is required but not installed. "
+                f"Install it with: {install_cmd}"
+            )
+
+        super().__init__(message)