clientwright 0.2.2__tar.gz → 0.3.0__tar.gz

{clientwright-0.2.2 → clientwright-0.3.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/bedrock-python/clientwright/compare/clientwright-v0.2.2...clientwright-v0.3.0) (2026-09-14)
+
+
+### Features
+
+* pydantic settings models for ClientConfig behind the settings extra ([3c5006f](https://github.com/bedrock-python/clientwright/commit/3c5006f3b61e50266d6f266ea1e997dbc80d5535))
+
 ## [0.2.2](https://github.com/bedrock-python/clientwright/compare/clientwright-v0.2.1...clientwright-v0.2.2) (2026-09-06)
 
 

{clientwright-0.2.2 → clientwright-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: clientwright
-Version: 0.2.2
+Version: 0.3.0
 Summary: HTTP client platform: one resilience and observability core with adapters for httpx, aiohttp, requests, urllib3 and friends
 Project-URL: Repository, https://github.com/bedrock-python/clientwright
 Project-URL: Documentation, https://bedrock-python.github.io/clientwright/
@@ -32,6 +32,8 @@ Requires-Dist: httpx2<3,>=2; extra == 'all'
 Requires-Dist: httpx<1,>=0.28; extra == 'all'
 Requires-Dist: opentelemetry-api>=1.26; extra == 'all'
 Requires-Dist: prometheus-client>=0.20; extra == 'all'
+Requires-Dist: pydantic-settings<3,>=2.3; extra == 'all'
+Requires-Dist: pydantic<3,>=2; extra == 'all'
 Requires-Dist: requests<3,>=2.32; extra == 'all'
 Requires-Dist: urllib3<3,>=2.2; extra == 'all'
 Provides-Extra: deadline
@@ -49,6 +51,9 @@ Requires-Dist: opentelemetry-api>=1.26; extra == 'observability'
 Requires-Dist: prometheus-client>=0.20; extra == 'observability'
 Provides-Extra: requests
 Requires-Dist: requests<3,>=2.32; extra == 'requests'
+Provides-Extra: settings
+Requires-Dist: pydantic-settings<3,>=2.3; extra == 'settings'
+Requires-Dist: pydantic<3,>=2; extra == 'settings'
 Provides-Extra: tracing
 Requires-Dist: opentelemetry-api>=1.26; extra == 'tracing'
 Provides-Extra: urllib3
@@ -134,6 +139,7 @@ pip install clientwright[httpx]            # httpx adapter (sync + async)
 pip install clientwright[aiohttp]          # aiohttp adapter (async)
 pip install clientwright[httpx,metrics]    # + Prometheus backend
 pip install clientwright[httpx,tracing]    # + OpenTelemetry backend
+pip install clientwright[httpx,settings]   # + ClientConfig from the environment
 ```
 
 ## Sync twin
@@ -202,6 +208,28 @@ with use_budget(BudgetContext.create(total_seconds=5.0)):
     await client.get("/users")  # runs with what is left of those 5 seconds
 ```
 
+## From the environment
+
+With `clientwright[settings]`, `ClientConfig` and every sub-config exist as pydantic
+models with the same fields and defaults. They are plain `BaseModel`s — nest them in
+your own settings, so a bare `BASE_URL` in a pod can never reach a section:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from clientwright.contrib.settings import BaseClientSettings
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_nested_delimiter="__")
+
+    warehouse: BaseClientSettings = BaseClientSettings()
+
+
+# WAREHOUSE__BASE_URL=https://wh.example.com WAREHOUSE__TIMEOUT__TOTAL=10 WAREHOUSE__POOL__HTTP2=true
+config = Settings().warehouse.to_config("warehouse")
+```
+
 ## Adapters
 
 | adapter | modes | notes |

{clientwright-0.2.2 → clientwright-0.3.0}/README.md

@@ -77,6 +77,7 @@ pip install clientwright[httpx]            # httpx adapter (sync + async)
 pip install clientwright[aiohttp]          # aiohttp adapter (async)
 pip install clientwright[httpx,metrics]    # + Prometheus backend
 pip install clientwright[httpx,tracing]    # + OpenTelemetry backend
+pip install clientwright[httpx,settings]   # + ClientConfig from the environment
 ```
 
 ## Sync twin
@@ -145,6 +146,28 @@ with use_budget(BudgetContext.create(total_seconds=5.0)):
     await client.get("/users")  # runs with what is left of those 5 seconds
 ```
 
+## From the environment
+
+With `clientwright[settings]`, `ClientConfig` and every sub-config exist as pydantic
+models with the same fields and defaults. They are plain `BaseModel`s — nest them in
+your own settings, so a bare `BASE_URL` in a pod can never reach a section:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from clientwright.contrib.settings import BaseClientSettings
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_nested_delimiter="__")
+
+    warehouse: BaseClientSettings = BaseClientSettings()
+
+
+# WAREHOUSE__BASE_URL=https://wh.example.com WAREHOUSE__TIMEOUT__TOTAL=10 WAREHOUSE__POOL__HTTP2=true
+config = Settings().warehouse.to_config("warehouse")
+```
+
 ## Adapters
 
 | adapter | modes | notes |

clientwright-0.3.0/clientwright/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"  # x-release-please-version

clientwright-0.3.0/clientwright/contrib/settings.py

@@ -0,0 +1,316 @@
+"""Settings models for ``ClientConfig`` (``[settings]`` extra).
+
+One pydantic model per config dataclass - the same field names, the same
+defaults - and ``to_config()`` on each, so the translation from an
+environment-loaded settings shape to a ``ClientConfig`` is written here, once,
+instead of in every service that uses the library.
+
+Every class here is a plain ``BaseModel``, never a ``BaseSettings``: a section
+is reachable only through the settings object you nest it in, so a bare
+``BASE_URL`` or ``TIMEOUT`` in a pod cannot reach it. The parent - its prefix,
+its nesting delimiter, its ``.env`` file - stays yours::
+
+    from pydantic_settings import BaseSettings, SettingsConfigDict
+
+    from clientwright.contrib.settings import BaseClientSettings
+
+
+    class Settings(BaseSettings):
+        model_config = SettingsConfigDict(env_nested_delimiter="__")
+
+        warehouse: BaseClientSettings = BaseClientSettings()
+
+
+    # WAREHOUSE__BASE_URL=https://wh.example.com WAREHOUSE__TIMEOUT__TOTAL=10 WAREHOUSE__POOL__HTTP2=true
+    config = Settings().warehouse.to_config("warehouse")
+
+``UNSET`` survives the trip: a knob the config leaves ``UNSET`` by default
+(``timeout.read``, ``pool.http2``, ...) reaches the config as ``UNSET`` unless
+you set it, and an explicit ``null`` is the dataclass' explicit "unbounded" -
+the models tell the two apart with ``model_fields_set``. Two things are not
+environment-shaped and are not here: ``service_name`` is the argument of
+:meth:`BaseClientSettings.to_config`, and ``observability.url_masker`` is a
+callable to set on the config afterwards.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Final
+
+from ..core.config import (
+    DEFAULT_RETRYABLE_KINDS,
+    DEFAULT_RETRYABLE_STATUS,
+    DEFAULT_SENSITIVE_QUERY_PARAMS,
+    DEFAULT_TRIP_KINDS,
+    UNSET,
+    CallerOverride,
+    CircuitBreakerConfig,
+    ClientConfig,
+    NativeOptions,
+    ObservabilityConfig,
+    PoolConfig,
+    ProxyConfig,
+    RedirectMode,
+    RetryConfig,
+    RetryMode,
+    TimeoutConfig,
+    TlsConfig,
+    UnsupportedPolicy,
+)
+from ..core.model import IDEMPOTENT_METHODS, CircuitKey, FailureKind
+
+try:
+    from pydantic import BaseModel, Field, field_validator, model_validator
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError("Settings models require clientwright[settings]; install it.") from exc
+
+
+def _maybe(model: BaseModel, name: str) -> Any:
+    """The field's value if it was given, else UNSET - the adapter's native default."""
+    return getattr(model, name) if name in model.model_fields_set else UNSET
+
+
+class BaseTimeoutSettings(BaseModel):
+    """``TimeoutConfig`` as settings.
+
+    A phase you do not set stays ``UNSET`` in the config, exactly as in
+    ``TimeoutConfig()``; an explicit ``null`` is the explicit "unbounded".
+    """
+
+    total: float | None = Field(
+        default=30.0, gt=0, description="Wall clock for the whole logical call; null = unbounded"
+    )
+    attempt: float | None = Field(default=None, gt=0, description="Ceiling for one attempt")
+    connect: float | None = Field(default=5.0, gt=0, description="Connect phase")
+    read: float | None = Field(default=None, gt=0, description="Read phase")
+    write: float | None = Field(default=None, gt=0, description="Write phase")
+    pool_acquire: float | None = Field(default=None, gt=0, description="Wait for a pooled connection")
+
+    def to_config(self) -> TimeoutConfig:
+        return TimeoutConfig(
+            total=self.total,
+            attempt=_maybe(self, "attempt"),
+            connect=self.connect,
+            read=_maybe(self, "read"),
+            write=_maybe(self, "write"),
+            pool_acquire=_maybe(self, "pool_acquire"),
+        )
+
+
+class BasePoolSettings(BaseModel):
+    """``PoolConfig`` as settings; ``max_connections_per_host`` and ``http2`` stay ``UNSET`` until set."""
+
+    max_connections: int | None = Field(default=100, gt=0, description="Pool-wide connection cap; null = unbounded")
+    max_keepalive: int | None = Field(default=20, gt=0, description="Idle connections kept open")
+    keepalive_expiry: float | None = Field(default=30.0, gt=0, description="Seconds an idle connection is kept")
+    max_connections_per_host: int | None = Field(default=None, gt=0, description="Per-origin connection cap")
+    http2: bool | None = Field(default=None, description="HTTP/2 where the adapter can honour it")
+
+    def to_config(self) -> PoolConfig:
+        return PoolConfig(
+            max_connections=self.max_connections,
+            max_keepalive=self.max_keepalive,
+            keepalive_expiry=self.keepalive_expiry,
+            max_connections_per_host=_maybe(self, "max_connections_per_host"),
+            http2=UNSET if self.http2 is None else self.http2,
+        )
+
+
+class BaseRetrySettings(BaseModel):
+    """``RetryConfig`` as settings; the sets take JSON lists, ``mode`` its value (``owned`` / ``delegated``)."""
+
+    max_attempts: int = Field(default=3, ge=1, description="Attempts per redirect hop, the first included")
+    initial_backoff: float = Field(default=0.1, gt=0, description="First backoff, seconds")
+    max_backoff: float = Field(default=10.0, gt=0, description="Backoff ceiling, seconds")
+    multiplier: float = Field(default=2.0, ge=1, description="Backoff growth per attempt")
+    jitter: float = Field(default=0.2, ge=0, le=1, description="Multiplicative jitter within [0, 1]")
+    retryable_kinds: frozenset[FailureKind] = Field(
+        default=DEFAULT_RETRYABLE_KINDS, description="Failure kinds worth a retry"
+    )
+    retryable_status: frozenset[int] = Field(default=DEFAULT_RETRYABLE_STATUS, description="Statuses worth a retry")
+    methods: frozenset[str] = Field(default=IDEMPOTENT_METHODS, description="Methods retried without a per-call flag")
+    respect_retry_after: bool = Field(default=True, description="A Retry-After header replaces the computed backoff")
+    retry_after_max: float = Field(default=60.0, description="Cap on what a server may ask for, seconds")
+    budget_ratio: float | None = Field(
+        default=0.1, gt=0, le=1, description="Share of an origin's traffic that may be retries; null = no budget"
+    )
+    require_replayable_body: bool = Field(default=True, description="Refuse to retry a body that cannot be replayed")
+    mode: RetryMode = Field(default=RetryMode.OWNED, description="owned by the engine, or delegated (urllib3 only)")
+
+    def to_config(self) -> RetryConfig:
+        return RetryConfig(
+            max_attempts=self.max_attempts,
+            initial_backoff=self.initial_backoff,
+            max_backoff=self.max_backoff,
+            multiplier=self.multiplier,
+            jitter=self.jitter,
+            retryable_kinds=self.retryable_kinds,
+            retryable_status=self.retryable_status,
+            methods=self.methods,
+            respect_retry_after=self.respect_retry_after,
+            retry_after_max=self.retry_after_max,
+            budget_ratio=self.budget_ratio,
+            require_replayable_body=self.require_replayable_body,
+            mode=self.mode,
+        )
+
+
+class BaseCircuitBreakerSettings(BaseModel):
+    """``CircuitBreakerConfig`` as settings; ``key`` by value: ``origin``, ``origin_route``, ``origin_method``."""
+
+    fail_threshold: int = Field(default=5, ge=1, description="Consecutive tripping calls before the circuit opens")
+    recovery_timeout: float = Field(default=60.0, gt=0, description="Seconds open before the next call is a probe")
+    half_open_max_calls: int = Field(default=1, ge=1, description="Concurrent probes while half-open")
+    max_keys: int = Field(default=512, ge=1, description="LRU cap on tracked circuits")
+    key: CircuitKey = Field(default=CircuitKey.ORIGIN, description="What one circuit stands for")
+    trip_kinds: frozenset[FailureKind] = Field(default=DEFAULT_TRIP_KINDS, description="Failure kinds that count")
+
+    def to_config(self) -> CircuitBreakerConfig:
+        return CircuitBreakerConfig(
+            fail_threshold=self.fail_threshold,
+            recovery_timeout=self.recovery_timeout,
+            half_open_max_calls=self.half_open_max_calls,
+            max_keys=self.max_keys,
+            key=self.key,
+            trip_kinds=self.trip_kinds,
+        )
+
+
+class BaseTlsSettings(BaseModel):
+    """``TlsConfig`` as settings; ``cert`` is a PEM path, or a JSON list of two or three paths."""
+
+    verify: bool = Field(default=True, description="Verify the server certificate")
+    ca_bundle: str | None = Field(default=None, description="Path to a private CA bundle")
+    cert: str | tuple[str, str] | tuple[str, str, str] | None = Field(
+        default=None, description="Client certificate: a PEM path, (cert, key) or (cert, key, password)"
+    )
+
+    def to_config(self) -> TlsConfig:
+        return TlsConfig(verify=self.verify, ca_bundle=self.ca_bundle, cert=self.cert)
+
+
+class BaseProxySettings(BaseModel):
+    """``ProxyConfig`` as settings: an explicit URL or the environment's proxies, not both."""
+
+    url: str | None = Field(default=None, description="Explicit proxy URL")
+    from_env: bool = Field(default=False, description="Read HTTP(S)_PROXY / NO_PROXY instead")
+
+    @model_validator(mode="after")
+    def _exclusive(self) -> BaseProxySettings:
+        if self.url is not None and self.from_env:
+            raise ValueError("proxy.url and proxy.from_env are mutually exclusive")
+        return self
+
+    def to_config(self) -> ProxyConfig:
+        return ProxyConfig(url=self.url, from_env=self.from_env)
+
+
+# Module attribute captured before the class: the field named ``logging``
+# shadows the module inside the class body, as in ``ObservabilityConfig``.
+_INFO_LEVEL: Final = logging.INFO
+
+
+class BaseObservabilitySettings(BaseModel):
+    """``ObservabilityConfig`` as settings, minus ``url_masker``: a callable belongs on the config.
+
+    ``success_log_level`` takes a level name (``DEBUG``) as well as a number.
+    """
+
+    logging: bool = Field(default=True, description="Emit log records")
+    metrics: bool = Field(default=True, description="Record metrics")
+    tracing: bool = Field(default=True, description="Open spans")
+    success_log_level: int = Field(default=_INFO_LEVEL, description="Level of the record for a successful call")
+    sensitive_query_params: frozenset[str] = Field(
+        default=DEFAULT_SENSITIVE_QUERY_PARAMS, description="Query parameters redacted by name in URLs"
+    )
+
+    @field_validator("success_log_level", mode="before")
+    @classmethod
+    def _level_by_name(cls, value: object) -> object:
+        if not isinstance(value, str):
+            return value
+        level = logging.getLevelNamesMapping().get(value.upper())
+        if level is None:
+            raise ValueError(f"unknown log level {value!r}")
+        return level
+
+    def to_config(self) -> ObservabilityConfig:
+        return ObservabilityConfig(
+            logging=self.logging,
+            metrics=self.metrics,
+            tracing=self.tracing,
+            success_log_level=self.success_log_level,
+            sensitive_query_params=self.sensitive_query_params,
+        )
+
+
+class BaseClientSettings(BaseModel):
+    """``ClientConfig`` as settings: the whole client, one section per sub-config.
+
+    Nest it in your own settings object; ``service_name`` is not environment-shaped
+    and is the argument of :meth:`to_config`. ``retry`` and ``circuit_breaker``
+    are on by default and go off with ``retry: None = None`` in a subclass (or
+    ``RETRY=null`` in the environment); ``proxy`` is off until any of its
+    fields is set.
+    """
+
+    base_url: str | None = Field(
+        default=None,
+        pattern=r"^https?://",
+        description="Origin every relative URL joins; unset means absolute URLs per call, "
+        "the only mode the requests and urllib3 adapters support",
+    )
+    timeout: BaseTimeoutSettings = Field(default_factory=BaseTimeoutSettings)
+    pool: BasePoolSettings = Field(default_factory=BasePoolSettings)
+    retry: BaseRetrySettings | None = Field(default_factory=BaseRetrySettings)
+    circuit_breaker: BaseCircuitBreakerSettings | None = Field(default_factory=BaseCircuitBreakerSettings)
+    tls: BaseTlsSettings = Field(default_factory=BaseTlsSettings)
+    proxy: BaseProxySettings | None = None
+    headers: dict[str, str] = Field(default_factory=dict, description="Headers injected with setdefault semantics")
+    redirects: RedirectMode = Field(default=RedirectMode.OWNED, description="owned by the engine, or native")
+    max_redirects: int = Field(default=5, ge=0, description="Hops before TooManyRedirectsError")
+    caller_override: CallerOverride = Field(
+        default=CallerOverride.CALLER_WINS, description="What a per-call timeout does: caller_wins, config_wins, raise"
+    )
+    deadline_header: str | None = Field(default=None, description="Header stamped with the remaining budget, in ms")
+    observability: BaseObservabilitySettings = Field(default_factory=BaseObservabilitySettings)
+    native: dict[str, dict[str, Any]] = Field(
+        default_factory=dict, description="Raw passthrough: {slot: {kwarg: value}}"
+    )
+    on_unsupported: UnsupportedPolicy = Field(
+        default=UnsupportedPolicy.WARN, description="What a knob the adapter cannot express does: ignore, warn, strict"
+    )
+
+    def to_config(self, service_name: str) -> ClientConfig:
+        """The ``ClientConfig`` these settings describe, labelled ``service_name``."""
+        return ClientConfig(
+            service_name=service_name,
+            base_url=self.base_url,
+            timeout=self.timeout.to_config(),
+            pool=self.pool.to_config(),
+            retry=None if self.retry is None else self.retry.to_config(),
+            circuit_breaker=None if self.circuit_breaker is None else self.circuit_breaker.to_config(),
+            tls=self.tls.to_config(),
+            proxy=None if self.proxy is None else self.proxy.to_config(),
+            headers=self.headers,
+            redirects=self.redirects,
+            max_redirects=self.max_redirects,
+            caller_override=self.caller_override,
+            deadline_header=self.deadline_header,
+            observability=self.observability.to_config(),
+            native=NativeOptions(slots=self.native),
+            on_unsupported=self.on_unsupported,
+        )
+
+
+__all__ = [
+    "BaseCircuitBreakerSettings",
+    "BaseClientSettings",
+    "BaseObservabilitySettings",
+    "BasePoolSettings",
+    "BaseProxySettings",
+    "BaseRetrySettings",
+    "BaseTimeoutSettings",
+    "BaseTlsSettings",
+]

{clientwright-0.2.2 → clientwright-0.3.0}/pyproject.toml

@@ -57,7 +57,8 @@ tracing = ["opentelemetry-api>=1.26"]
 observability = ["clientwright[metrics,tracing]"]
 deadline = ["deadline-budget>=0.1,<1"]
 dishka = ["dishka>=1.4"]
-all = ["clientwright[httpx,httpx2,aiohttp,requests,urllib3,observability,deadline,dishka]"]
+settings = ["pydantic>=2,<3", "pydantic-settings>=2.3,<3"]
+all = ["clientwright[httpx,httpx2,aiohttp,requests,urllib3,observability,deadline,dishka,settings]"]
 
 [dependency-groups]
 test = [

{clientwright-0.2.2 → clientwright-0.3.0}/tests/unit/adapters/test_bare_install.py

@@ -23,6 +23,8 @@ BLOCKED = (
     "opentelemetry",
     "dishka",
     "deadline_budget",
+    "pydantic",
+    "pydantic_settings",
 )
 
 BLOCKER = """
@@ -147,3 +149,17 @@ def test__zero_dep_surface__config_engine_and_testing_tools_work() -> None:
         """
     )
     assert output == "core usable"
+
+
+def test__settings_models_without_the_extra__fail_with_the_install_hint() -> None:
+    output = run_probe(
+        """
+        try:
+            import clientwright.contrib.settings
+        except ImportError as error:
+            print(error)
+        else:
+            print("NO ERROR")
+        """
+    )
+    assert "clientwright[settings]" in output

clientwright-0.3.0/tests/unit/contrib/test_settings.py

@@ -0,0 +1,213 @@
+"""contrib units: the settings models and their translation into ClientConfig."""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+
+import pytest
+
+pytest.importorskip("pydantic", reason="requires the [settings] extra")
+
+from pydantic import ValidationError
+
+from clientwright import (
+    UNSET,
+    CircuitBreakerConfig,
+    CircuitKey,
+    ClientConfig,
+    FailureKind,
+    NativeOptions,
+    ObservabilityConfig,
+    PoolConfig,
+    ProxyConfig,
+    RetryConfig,
+    RetryMode,
+    TimeoutConfig,
+    TlsConfig,
+    UnsupportedPolicy,
+    build_sync,
+)
+from clientwright.contrib import settings as settings_module
+from clientwright.contrib.settings import (
+    BaseCircuitBreakerSettings,
+    BaseClientSettings,
+    BaseObservabilitySettings,
+    BasePoolSettings,
+    BaseProxySettings,
+    BaseRetrySettings,
+    BaseTimeoutSettings,
+    BaseTlsSettings,
+)
+
+# --- the models are the dataclasses, written once ---
+
+PAIRS = [
+    (BaseTimeoutSettings, TimeoutConfig, set()),
+    (BasePoolSettings, PoolConfig, set()),
+    (BaseRetrySettings, RetryConfig, set()),
+    (BaseCircuitBreakerSettings, CircuitBreakerConfig, set()),
+    (BaseTlsSettings, TlsConfig, set()),
+    (BaseProxySettings, ProxyConfig, set()),
+    (BaseObservabilitySettings, ObservabilityConfig, {"url_masker"}),
+    (BaseClientSettings, ClientConfig, {"service_name"}),
+]
+
+
+@pytest.mark.parametrize(("model", "dataclass", "not_env_shaped"), PAIRS, ids=[m.__name__ for m, _, _ in PAIRS])
+def test__every_model__names_exactly_the_dataclass_fields(
+    model: type, dataclass: type, not_env_shaped: set[str]
+) -> None:
+    assert set(model.model_fields) == {f.name for f in dataclasses.fields(dataclass)} - not_env_shaped
+
+
+def test__defaults__are_the_dataclass_defaults() -> None:
+    assert BaseClientSettings().to_config("orders") == ClientConfig(service_name="orders")
+
+
+def test__no_model__is_a_base_settings() -> None:
+    pydantic_settings = pytest.importorskip("pydantic_settings", reason="requires the [settings] extra")
+    for name in settings_module.__all__:
+        assert not issubclass(getattr(settings_module, name), pydantic_settings.BaseSettings), name
+
+
+# --- the environment ---
+
+
+def test__nested_in_a_base_settings__reads_the_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    pydantic_settings = pytest.importorskip("pydantic_settings", reason="requires the [settings] extra")
+
+    class Settings(pydantic_settings.BaseSettings):
+        model_config = pydantic_settings.SettingsConfigDict(env_nested_delimiter="__")
+
+        warehouse: BaseClientSettings = BaseClientSettings()
+
+    monkeypatch.setenv("WAREHOUSE__BASE_URL", "https://wh.example.com")
+    monkeypatch.setenv("WAREHOUSE__TIMEOUT__TOTAL", "10")
+    monkeypatch.setenv("WAREHOUSE__TIMEOUT__CONNECT", "2")
+    monkeypatch.setenv("WAREHOUSE__POOL__HTTP2", "true")
+    monkeypatch.setenv("WAREHOUSE__RETRY__MAX_ATTEMPTS", "5")
+    monkeypatch.setenv("WAREHOUSE__RETRY__RETRYABLE_STATUS", "[429, 500]")
+    monkeypatch.setenv("WAREHOUSE__CIRCUIT_BREAKER__FAIL_THRESHOLD", "2")
+    monkeypatch.setenv("WAREHOUSE__TLS__CERT", '["client.pem", "client.key"]')
+    monkeypatch.setenv("WAREHOUSE__PROXY__URL", "http://proxy:3128")
+    monkeypatch.setenv("WAREHOUSE__ON_UNSUPPORTED", "strict")
+
+    config = Settings().warehouse.to_config("warehouse")
+
+    assert config == ClientConfig(
+        service_name="warehouse",
+        base_url="https://wh.example.com",
+        timeout=TimeoutConfig(total=10.0, connect=2.0),
+        pool=PoolConfig(http2=True),
+        retry=RetryConfig(max_attempts=5, retryable_status=frozenset({429, 500})),
+        circuit_breaker=CircuitBreakerConfig(fail_threshold=2),
+        tls=TlsConfig(cert=("client.pem", "client.key")),
+        proxy=ProxyConfig(url="http://proxy:3128"),
+        on_unsupported=UnsupportedPolicy.STRICT,
+    )
+
+
+def test__bare_variables__cannot_reach_a_section(monkeypatch: pytest.MonkeyPatch) -> None:
+    pydantic_settings = pytest.importorskip("pydantic_settings", reason="requires the [settings] extra")
+
+    class Settings(pydantic_settings.BaseSettings):
+        model_config = pydantic_settings.SettingsConfigDict(env_nested_delimiter="__")
+
+        warehouse: BaseClientSettings = BaseClientSettings()
+
+    class LeakySection(pydantic_settings.BaseSettings):
+        base_url: str | None = None
+
+    monkeypatch.setenv("BASE_URL", "https://leak.example.com")
+    monkeypatch.setenv("TIMEOUT", "1")
+    monkeypatch.setenv("TOTAL", "1")
+    monkeypatch.setenv("MAX_ATTEMPTS", "9")
+    monkeypatch.setenv("HTTP2", "true")
+    monkeypatch.setenv("VERIFY", "false")
+
+    assert LeakySection().base_url == "https://leak.example.com"  # what a BaseSettings section would do
+    assert Settings().warehouse.to_config("warehouse") == ClientConfig(service_name="warehouse")
+
+
+def test__null_in_the_environment__disables_a_section_and_unbounds_a_phase(monkeypatch: pytest.MonkeyPatch) -> None:
+    pydantic_settings = pytest.importorskip("pydantic_settings", reason="requires the [settings] extra")
+
+    class Settings(pydantic_settings.BaseSettings):
+        model_config = pydantic_settings.SettingsConfigDict(env_nested_delimiter="__", env_parse_none_str="null")
+
+        warehouse: BaseClientSettings = BaseClientSettings()
+
+    monkeypatch.setenv("WAREHOUSE__RETRY", "null")
+    monkeypatch.setenv("WAREHOUSE__TIMEOUT__READ", "null")
+
+    config = Settings().warehouse.to_config("warehouse")
+
+    assert config.retry is None
+    assert config.timeout.read is None
+    assert config.timeout.write is UNSET
+
+
+# --- UNSET, None and the env spellings ---
+
+
+def test__an_unset_knob__stays_unset_and_null_is_unbounded() -> None:
+    assert BaseTimeoutSettings().to_config().read is UNSET
+    assert BaseTimeoutSettings(read=None).to_config().read is None
+    assert BaseTimeoutSettings(read=2.0).to_config().read == 2.0
+    assert BasePoolSettings().to_config().max_connections_per_host is UNSET
+    assert BasePoolSettings().to_config().http2 is UNSET
+    assert BasePoolSettings(http2=False).to_config().http2 is False
+
+
+def test__enums_sets_and_levels__are_coerced_from_their_env_spellings() -> None:
+    retry = BaseRetrySettings(mode="delegated", retryable_kinds=["dns_error"], methods=["GET"]).to_config()
+    assert retry.mode is RetryMode.DELEGATED
+    assert retry.retryable_kinds == frozenset({FailureKind.DNS_ERROR})
+    assert retry.methods == frozenset({"GET"})
+    assert BaseCircuitBreakerSettings(key="origin_route").to_config().key is CircuitKey.ORIGIN_ROUTE
+    assert BaseObservabilitySettings(success_log_level="debug").to_config().success_log_level == logging.DEBUG
+    assert BaseObservabilitySettings(success_log_level=30).to_config().success_log_level == logging.WARNING
+    with pytest.raises(ValidationError, match="unknown log level"):
+        BaseObservabilitySettings(success_log_level="LOUD")
+
+
+def test__sections__disable_with_none_and_proxy_appears_on_demand() -> None:
+    class Batch(BaseClientSettings):
+        retry: None = None
+        circuit_breaker: None = None
+
+    config = Batch().to_config("batch")
+    assert config.retry is None
+    assert config.circuit_breaker is None
+    assert config.proxy is None
+    assert BaseClientSettings(proxy=BaseProxySettings(from_env=True)).to_config("x").proxy == ProxyConfig(from_env=True)
+
+
+def test__headers_and_native__reach_the_config() -> None:
+    config = BaseClientSettings(headers={"User-Agent": "svc/1"}, native={"client": {"trust_env": False}}).to_config(
+        "svc"
+    )
+    assert config.headers == {"User-Agent": "svc/1"}
+    assert config.native == NativeOptions.of(client={"trust_env": False})
+
+
+def test__bad_values__fail_at_load_with_the_field_path() -> None:
+    with pytest.raises(ValidationError, match=r"timeout\.total"):
+        BaseClientSettings(timeout={"total": 0})
+    with pytest.raises(ValidationError, match="base_url"):
+        BaseClientSettings(base_url="ftp://nope")
+    with pytest.raises(ValidationError, match="max_attempts"):
+        BaseRetrySettings(max_attempts=0)
+    with pytest.raises(ValidationError, match="mutually exclusive"):
+        BaseProxySettings(url="http://proxy:3128", from_env=True)
+
+
+def test__a_config_from_settings__builds_the_native_client() -> None:
+    httpx = pytest.importorskip("httpx", reason="requires the [httpx] extra")
+    config = BaseClientSettings(base_url="https://api.example.com", pool={"http2": False}).to_config("api")
+    client = build_sync("httpx", config)
+    try:
+        assert type(client) is httpx.Client
+    finally:
+        client.close()