honeyhive.config.resolved

The resolved HoneyHive connection settings: the API keys and the API URL.

Three parts of the SDK send requests to HoneyHive on their own: the HoneyHive client, the tracer (its OTLP export), and the CLI. Each is an entry point that takes the keys and the URL as arguments and otherwise reads them from the environment, and each used to do that reading itself, with its own variable names in its own order, so one process could authenticate with one key in evaluate() and another in a tracer, or send runs to one host and spans to another, with no error anywhere. Now each entry point calls ResolvedConfig.resolve once with the arguments it received, and everything beneath it is handed the result; nothing below an entry point reads these variables or resolves them again. The configuration models get their connection fields from the environment_* functions here when a caller constructs one directly, and from the tracer's resolved values when the tracer builds them.

Each setting has one preferred variable, HH_<SETTING>. The alternates in _SETTINGS stay supported because shipped code read them and the changelog of the release that added them names them. They are kept out of the README and the docs site, reading one emits a DeprecationWarning once per process, and removing one is a breaking change.

The ingestion API key and the data plane API key are typed: a present value that is not an hh_ingst_ or an hh_fgdp_ key respectively raises here, at resolution, whether or not the run goes on to send anything with it. The project API key has no shape rule and is forwarded as given.

This type holds HoneyHive's canonical connection settings and nothing else. A new field is a deliberate decision about a canonical setting, never a convenience for a caller.

logger module-attribute

logger = logging.getLogger(__name__)

DEFAULT_API_URL module-attribute

DEFAULT_API_URL = 'https://api.dp1.us.honeyhive.ai'

INGESTION_API_KEY_PREFIX module-attribute

INGESTION_API_KEY_PREFIX = 'hh_ingst_'

DATA_PLANE_API_KEY_PREFIX module-attribute

DATA_PLANE_API_KEY_PREFIX = 'hh_fgdp_'

ResolvedConfig dataclass

The API keys and API URL after precedence has been applied.

api_key, ingestion_api_key, and data_plane_api_key are None when nothing supplied them; whether that is an error is the consumer's decision, since a tracer can run on an ingestion key alone while a Data Plane call cannot.

Source code in src/honeyhive/config/resolved.py

@dataclass(frozen=True)
class ResolvedConfig:
    """The API keys and API URL after precedence has been applied.

    ``api_key``, ``ingestion_api_key``, and ``data_plane_api_key`` are None when
    nothing supplied them; whether that is an error is the consumer's decision,
    since a tracer can run on an ingestion key alone while a Data Plane call
    cannot.
    """

    api_key: Optional[str]
    ingestion_api_key: Optional[str]
    data_plane_api_key: Optional[str]
    api_url: str

    @classmethod
    def resolve(
        cls,
        *,
        api_key: Optional[str] = None,
        ingestion_api_key: Optional[str] = None,
        data_plane_api_key: Optional[str] = None,
        api_url: Optional[str] = None,
    ) -> "ResolvedConfig":
        """Merge an entry point's explicit arguments with the environment.

        For each setting: the explicit argument if it is set, else the preferred
        variable, else the alternates in order. None and blank strings count as
        unset at every step. A present typed key is checked for shape,
        whichever step supplied it.

        Raises:
            TypeError: An explicit argument is neither None nor a string.
            ValueError: A typed key, explicit or from the environment, is not a
                key of its kind. The message names its source.
        """
        resolved_key = _present(api_key, "api_key")
        if resolved_key is None:
            resolved_key = environment_api_key()

        # The shape checks run for every caller, including one that will never
        # send the key (the CLI, a client used only for Data Plane reads, a
        # tracer whose environment carries a data plane key): a typed credential
        # that is present and malformed is a deployment error, and surfacing it
        # from every entry point beats a user learning of it only when the path
        # that sends it runs somewhere else.
        explicit_ingestion_key = _present(ingestion_api_key, "ingestion_api_key")
        if explicit_ingestion_key is not None:
            resolved_ingestion_key: Optional[str] = check_ingestion_api_key(
                explicit_ingestion_key, "ingestion_api_key"
            )
        else:
            resolved_ingestion_key = environment_ingestion_api_key()

        explicit_data_plane_key = _present(data_plane_api_key, "data_plane_api_key")
        if explicit_data_plane_key is not None:
            resolved_data_plane_key: Optional[str] = check_data_plane_api_key(
                explicit_data_plane_key, "data_plane_api_key"
            )
        else:
            resolved_data_plane_key = environment_data_plane_api_key()

        explicit_url = _present(api_url, "api_url")
        if explicit_url is not None:
            resolved_url = normalize_api_url(explicit_url, "api_url")
        else:
            resolved_url = environment_api_url()

        return cls(
            api_key=resolved_key,
            ingestion_api_key=resolved_ingestion_key,
            data_plane_api_key=resolved_data_plane_key,
            api_url=resolved_url,
        )

api_key instance-attribute

api_key: Optional[str]

ingestion_api_key instance-attribute

ingestion_api_key: Optional[str]

data_plane_api_key instance-attribute

data_plane_api_key: Optional[str]

api_url instance-attribute

api_url: str

resolve classmethod

resolve(
    *,
    api_key: Optional[str] = None,
    ingestion_api_key: Optional[str] = None,
    data_plane_api_key: Optional[str] = None,
    api_url: Optional[str] = None
) -> ResolvedConfig

Merge an entry point's explicit arguments with the environment.

For each setting: the explicit argument if it is set, else the preferred variable, else the alternates in order. None and blank strings count as unset at every step. A present typed key is checked for shape, whichever step supplied it.

Raises:

Type	Description
TypeError	An explicit argument is neither None nor a string.
ValueError	A typed key, explicit or from the environment, is not a key of its kind. The message names its source.

Source code in src/honeyhive/config/resolved.py

@classmethod
def resolve(
    cls,
    *,
    api_key: Optional[str] = None,
    ingestion_api_key: Optional[str] = None,
    data_plane_api_key: Optional[str] = None,
    api_url: Optional[str] = None,
) -> "ResolvedConfig":
    """Merge an entry point's explicit arguments with the environment.

    For each setting: the explicit argument if it is set, else the preferred
    variable, else the alternates in order. None and blank strings count as
    unset at every step. A present typed key is checked for shape,
    whichever step supplied it.

    Raises:
        TypeError: An explicit argument is neither None nor a string.
        ValueError: A typed key, explicit or from the environment, is not a
            key of its kind. The message names its source.
    """
    resolved_key = _present(api_key, "api_key")
    if resolved_key is None:
        resolved_key = environment_api_key()

    # The shape checks run for every caller, including one that will never
    # send the key (the CLI, a client used only for Data Plane reads, a
    # tracer whose environment carries a data plane key): a typed credential
    # that is present and malformed is a deployment error, and surfacing it
    # from every entry point beats a user learning of it only when the path
    # that sends it runs somewhere else.
    explicit_ingestion_key = _present(ingestion_api_key, "ingestion_api_key")
    if explicit_ingestion_key is not None:
        resolved_ingestion_key: Optional[str] = check_ingestion_api_key(
            explicit_ingestion_key, "ingestion_api_key"
        )
    else:
        resolved_ingestion_key = environment_ingestion_api_key()

    explicit_data_plane_key = _present(data_plane_api_key, "data_plane_api_key")
    if explicit_data_plane_key is not None:
        resolved_data_plane_key: Optional[str] = check_data_plane_api_key(
            explicit_data_plane_key, "data_plane_api_key"
        )
    else:
        resolved_data_plane_key = environment_data_plane_api_key()

    explicit_url = _present(api_url, "api_url")
    if explicit_url is not None:
        resolved_url = normalize_api_url(explicit_url, "api_url")
    else:
        resolved_url = environment_api_url()

    return cls(
        api_key=resolved_key,
        ingestion_api_key=resolved_ingestion_key,
        data_plane_api_key=resolved_data_plane_key,
        api_url=resolved_url,
    )

EnvSettingsSourceWithout

Bases: EnvSettingsSource

The built-in environment source, minus the fields the resolver owns.

Without this, pydantic-settings would read HH_API_KEY and, through the prefix, HH_SERVER_URL on its own, and the latter would beat HH_API_URL instead of ranking below it.

Source code in src/honeyhive/config/resolved.py

class EnvSettingsSourceWithout(EnvSettingsSource):
    """The built-in environment source, minus the fields the resolver owns.

    Without this, pydantic-settings would read ``HH_API_KEY`` and, through the
    prefix, ``HH_SERVER_URL`` on its own, and the latter would beat
    ``HH_API_URL`` instead of ranking below it.
    """

    def __init__(
        self, settings_cls: type[BaseSettings], excluded: FrozenSet[str]
    ) -> None:
        super().__init__(settings_cls)
        self._excluded = excluded

    def get_field_value(
        self, field: FieldInfo, field_name: str
    ) -> Tuple[Any, str, bool]:
        if field_name in self._excluded:
            return None, field_name, False
        return super().get_field_value(field, field_name)

get_field_value

get_field_value(
    field: FieldInfo, field_name: str
) -> Tuple[Any, str, bool]

Source code in src/honeyhive/config/resolved.py

def get_field_value(
    self, field: FieldInfo, field_name: str
) -> Tuple[Any, str, bool]:
    if field_name in self._excluded:
        return None, field_name, False
    return super().get_field_value(field, field_name)

normalize_api_url

normalize_api_url(value: str, source: str) -> str

Apply the one shape rule for the API URL.

A value that is not an HTTP or HTTPS URL is malformed; the setting has a default, so the default is used with a warning rather than raising. A trailing slash is removed so request paths join without a double slash.

Parameters:

Name	Type	Description	Default
value	str	A non-blank URL candidate.	required
source	str	The parameter or variable it came from, named in the warning.	required

Source code in src/honeyhive/config/resolved.py

def normalize_api_url(value: str, source: str) -> str:
    """Apply the one shape rule for the API URL.

    A value that is not an HTTP or HTTPS URL is malformed; the setting has a
    default, so the default is used with a warning rather than raising. A
    trailing slash is removed so request paths join without a double slash.

    Args:
        value: A non-blank URL candidate.
        source: The parameter or variable it came from, named in the warning.
    """
    if not value.startswith(("http://", "https://")):
        logger.warning(
            "Invalid %s: must be an HTTP or HTTPS URL. Using the default.",
            source,
            extra={"honeyhive_data": {"field": source}},
        )
        return DEFAULT_API_URL
    return value.rstrip("/")

check_ingestion_api_key

check_ingestion_api_key(value: str, source: str) -> str

Return value if it is a well-formed ingestion API key.

Parameters:

Name	Type	Description	Default
value	str	The candidate key, already known to be a non-blank string.	required
source	str	Where the value came from, named in the error, for example "HH_INGESTION_API_KEY" or "ingestion_api_key".	required

Returns:

Type	Description
str	The key with surrounding whitespace removed.

Raises:

Type	Description
ValueError	value is not an ingestion API key. The message says what the value looks like instead and never echoes the value itself.

Source code in src/honeyhive/config/resolved.py

def check_ingestion_api_key(value: str, source: str) -> str:
    """Return ``value`` if it is a well-formed ingestion API key.

    Args:
        value: The candidate key, already known to be a non-blank string.
        source: Where the value came from, named in the error, for example
            ``"HH_INGESTION_API_KEY"`` or ``"ingestion_api_key"``.

    Returns:
        The key with surrounding whitespace removed.

    Raises:
        ValueError: ``value`` is not an ingestion API key. The message says what
            the value looks like instead and never echoes the value itself.
    """
    return _check_typed_api_key(
        value, source, INGESTION_API_KEY_PREFIX, "an ingestion API key"
    )

check_data_plane_api_key

check_data_plane_api_key(value: str, source: str) -> str

Return value if it is a well-formed fine-grained data plane API key.

Parameters:

Name	Type	Description	Default
value	str	The candidate key, already known to be a non-blank string.	required
source	str	Where the value came from, named in the error, for example "HH_DATA_PLANE_API_KEY" or "data_plane_api_key".	required

Returns:

Type	Description
str	The key with surrounding whitespace removed.

Raises:

Type	Description
ValueError	value is not a fine-grained data plane API key. The message says what the value looks like instead and never echoes the value itself.

Source code in src/honeyhive/config/resolved.py

def check_data_plane_api_key(value: str, source: str) -> str:
    """Return ``value`` if it is a well-formed fine-grained data plane API key.

    Args:
        value: The candidate key, already known to be a non-blank string.
        source: Where the value came from, named in the error, for example
            ``"HH_DATA_PLANE_API_KEY"`` or ``"data_plane_api_key"``.

    Returns:
        The key with surrounding whitespace removed.

    Raises:
        ValueError: ``value`` is not a fine-grained data plane API key. The
            message says what the value looks like instead and never echoes the
            value itself.
    """
    return _check_typed_api_key(
        value, source, DATA_PLANE_API_KEY_PREFIX, "a fine-grained data plane API key"
    )

environment_api_key

environment_api_key() -> Optional[str]

The project API key from the environment alone, or None when unset.

Source code in src/honeyhive/config/resolved.py

def environment_api_key() -> Optional[str]:
    """The project API key from the environment alone, or None when unset."""
    value, _ = _from_environment("api_key")
    return value

environment_ingestion_api_key

environment_ingestion_api_key() -> Optional[str]

The ingestion API key from the environment alone, checked; None when unset.

Raises:

Type	Description
ValueError	The variable is set to something other than an ingestion key.

Source code in src/honeyhive/config/resolved.py

def environment_ingestion_api_key() -> Optional[str]:
    """The ingestion API key from the environment alone, checked; None when unset.

    Raises:
        ValueError: The variable is set to something other than an ingestion key.
    """
    value, source = _from_environment("ingestion_api_key")
    if value is None:
        return None
    return check_ingestion_api_key(value, source)

environment_data_plane_api_key

environment_data_plane_api_key() -> Optional[str]

The data plane API key from the environment alone, checked; None when unset.

Raises:

Type	Description
ValueError	The variable is set to something other than a fine-grained data plane API key.

Source code in src/honeyhive/config/resolved.py

def environment_data_plane_api_key() -> Optional[str]:
    """The data plane API key from the environment alone, checked; None when unset.

    Raises:
        ValueError: The variable is set to something other than a fine-grained
            data plane API key.
    """
    value, source = _from_environment("data_plane_api_key")
    if value is None:
        return None
    return check_data_plane_api_key(value, source)

environment_api_url

environment_api_url() -> str

The API URL from the environment alone, normalized; the default when unset.

Source code in src/honeyhive/config/resolved.py

def environment_api_url() -> str:
    """The API URL from the environment alone, normalized; the default when unset."""
    value, source = _from_environment("api_url")
    if value is None:
        return DEFAULT_API_URL
    return normalize_api_url(value, source)

settings_sources

settings_sources(
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
    *,
    excluded: FrozenSet[str]
) -> Tuple[PydanticBaseSettingsSource, ...]

The source order for every HoneyHive configuration model.

Source code in src/honeyhive/config/resolved.py

def settings_sources(
    settings_cls: type[BaseSettings],
    init_settings: PydanticBaseSettingsSource,
    dotenv_settings: PydanticBaseSettingsSource,
    file_secret_settings: PydanticBaseSettingsSource,
    *,
    excluded: FrozenSet[str],
) -> Tuple[PydanticBaseSettingsSource, ...]:
    """The source order for every HoneyHive configuration model."""
    return (
        init_settings,
        EnvSettingsSourceWithout(settings_cls, excluded),
        dotenv_settings,
        file_secret_settings,
    )