config.py

# Copyright (c) Microsoft Corporation.
# Licensed under the MIT license.

"""
Dataverse client configuration.

Provides :class:`~PowerPlatform.Dataverse.core.config.DataverseConfig`, a lightweight
immutable container for locale and (reserved) HTTP tuning options plus the
convenience constructor :meth:`~PowerPlatform.Dataverse.core.config.DataverseConfig.from_env`.
"""

from __future__ import annotations

from dataclasses import dataclass
from typing import Optional, TYPE_CHECKING

if TYPE_CHECKING:
    from .telemetry import TelemetryConfig


@dataclass(frozen=True)
class DataverseConfig:
    """
    Configuration settings for Dataverse client operations.

    :param language_code: LCID (Locale ID) for localized labels and messages. Default is 1033 (English - United States).
    :type language_code: :class:`int`
    :param http_retries: Optional maximum number of retry attempts for transient HTTP errors. Reserved for future use.
    :type http_retries: :class:`int` or None
    :param http_backoff: Optional backoff multiplier (in seconds) between retry attempts. Reserved for future use.
    :type http_backoff: :class:`float` or None
    :param http_timeout: Optional request timeout in seconds. Reserved for future use.
    :type http_timeout: :class:`float` or None
    :param telemetry: Optional telemetry configuration for tracing, metrics, logging, and custom hooks.
        When ``None`` (the default) telemetry is disabled with zero overhead.
    :type telemetry: ~PowerPlatform.Dataverse.core.telemetry.TelemetryConfig or None
    """

    language_code: int = 1033

    # Optional HTTP tuning (not yet wired everywhere; reserved for future use)
    http_retries: Optional[int] = None
    http_backoff: Optional[float] = None
    http_timeout: Optional[float] = None

    # Telemetry configuration (opt-in; None = disabled)
    telemetry: Optional[TelemetryConfig] = None

    @classmethod
    def from_env(cls) -> "DataverseConfig":
        """
        Create a configuration instance with default settings.

        :return: Configuration instance with default values.
        :rtype: ~PowerPlatform.Dataverse.core.config.DataverseConfig
        """
        # Environment-free defaults
        return cls(
            language_code=1033,
            http_retries=None,
            http_backoff=None,
            http_timeout=None,
        )