ClientConfig and friends have no env-facing layer, so each consumer writes the settings models again

[AlexeyShalaev]

The resilience and observability configs are dataclasses with no env-facing layer, so every
consumer writes the same settings models and maps them by hand.

What happens

clientwright ships ClientConfig, CircuitBreakerConfig, ObservabilityConfig, NativeOptions,
CallOptions and friends as dataclasses. There are no pydantic models in the package:

import pkgutil, importlib, inspect
from pydantic import BaseModel
import clientwright

found = []
for m in pkgutil.walk_packages(clientwright.__path__, prefix="clientwright."):
    mod = importlib.import_module(m.name)
    found += [n for n, o in vars(mod).items()
              if inspect.isclass(o) and issubclass(o, BaseModel)]
found   # []

Why it matters

The configuration a REST client actually needs per environment — base URL, connect and total
timeouts, pool sizing, HTTP/2, retry and circuit-breaker policy — is exactly the part that differs
between dev, stage and prod, and therefore exactly the part that has to come from the environment.
With only dataclasses, each consumer writes its own pydantic layer and its own mapping onto yours.

In our monorepo that layer sits alongside a dozen client sections and is the last piece of a
settings library we have otherwise been able to delete: everything else now comes from the library
that reads it — sqlalchemy-foundation-kit, redis-client-kit, aiokafka-foundation-kit,
omni-box, pg-partsmith, idempotency-kit, deadline-budget, servicewright. clientwright
and grpc-client-kit are the two that still need a local model.

Precedent: servicewright#22 raised the same gap for the observability sections and was resolved by
shipping the models in 0.7.0.

A specific hazard worth designing against

Consumer-written sections tend to subclass BaseSettings, which makes each one scrape the
environment with no prefix — a bare BASE_URL in a pod can reach a nested client section the
parent settings did not fill. Shipping plain BaseModel sections, reachable only through their
parent, removes that for everyone. servicewright hit the same thing before 0.7.0.

What would help

Some sanctioned path from environment to ClientConfig. Pydantic models mirroring the dataclasses,
a from_settings() constructor, or a documented protocol you accept would all work for us. What we
care about is that there is exactly one such path, owned here, so the mapping of your field set is
not re-derived in every repo that uses the library.

Versions

clientwright 0.2.2, pydantic 2.13, pydantic-settings 2.13, CPython 3.14.

[AlexeyShalaev]

Agreed on the shape, and on the hazard. Plan before the code:

The gap as I read it: ClientSettingsProtocol + client_config_from_settings exist, but they name only the legacy flat surface (timeout_seconds, enable_http2, a four-field retry, a three-field breaker). Anyone who wants pool.max_connections_per_host, retry.retryable_status, tls.cert or proxy from the environment is back to writing the model and the mapping by hand, and the model they write is a BaseSettings per section because that is the path of least resistance. Nothing in the library owns the translation from a settings shape to the full ClientConfig.

Design: clientwright[settings] → clientwright.contrib.settings, one pydantic model per config dataclass, same field names, same defaults, to_config() on each:

from pydantic_settings import BaseSettings, SettingsConfigDict

from clientwright.contrib.settings import BaseClientSettings


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_nested_delimiter="__")

    warehouse: BaseClientSettings = BaseClientSettings()
    identity: BaseClientSettings = BaseClientSettings()


settings = Settings()  # WAREHOUSE__BASE_URL=... WAREHOUSE__TIMEOUT__TOTAL=10 WAREHOUSE__POOL__HTTP2=true
config = settings.warehouse.to_config("warehouse")  # -> ClientConfig

• BaseClientSettings, BaseTimeoutSettings, BasePoolSettings, BaseRetrySettings, BaseCircuitBreakerSettings, BaseTlsSettings, BaseProxySettings, BaseObservabilitySettings — all plain BaseModel, none a BaseSettings. They are reachable only through whatever parent you nest them in, so a bare BASE_URL or TIMEOUT in the pod cannot reach a section; a test with exactly those variables in the environment pins that. The parent, its prefix and its delimiter stay yours — one root settings holding a dozen client sections is the layout this is shaped for, and a per-client BaseSettings would have got it wrong.
• The field set is the dataclasses' field set minus two things that are not environment-shaped: service_name is the argument of to_config(service_name) (the metric label is code identity, same as client_config_from_settings(settings, service_name) today), and observability.url_masker is a callable — set it on the config afterwards. Everything else is there: native as {slot: {kwarg: value}}, the frozenset fields as JSON lists, enums by value, success_log_level by name or number.
• UNSET stays UNSET. A phase knob you do not set (timeout.read, pool.http2, pool.max_connections_per_host, ...) reaches the config as UNSET — the adapter's native default, exactly as when you construct TimeoutConfig() yourself — and an explicit null is the dataclass' explicit "unbounded". The models use model_fields_set to tell the two apart, so the settings layer does not quietly collapse the three states that rule 3 of the agents page exists for.
• Sections the config disables with None (retry, circuit_breaker, proxy) are Model | None here too: proxy defaults to None and appears when any PROXY__* variable is set; the other two default on and go off with retry: None = None in a subclass.
• Defaults are checked against the dataclasses in the tests: BaseClientSettings().to_config("x") == ClientConfig(service_name="x") is one assertion over every default in the library, and the field names of each model/dataclass pair are compared in another, so the models cannot drift from the dataclasses without a red build.
• The extra pins pydantic>=2,<3 and pydantic-settings>=2.3,<3. The module imports only pydantic; pydantic-settings is in the extra the way deadline-budget is in [deadline] — the library this module is built to be nested in. Missing extra → ImportError naming clientwright[settings], like every other contrib.

client_config_from_settings and the flat protocol stay as they are — a service with an existing flat settings model still has its path — but the docs will point new code at the models.

Rejected: widening the structural protocol to the full field set (you would still write the model and the mapping, and the BaseSettings-per-section hazard is untouched); a ClientConfig.from_mapping(dict) in the core (stdlib-only and source-agnostic, but the field set is still re-derived on your side, with no validation and no defaults — the obstacle you named); shipping a BaseSettings parent (it would own the prefix and the delimiter, which are the root settings' business, and it is the very thing the hazard is about); anything in core (the import-linter contract forbids pydantic there, and should).

[AlexeyShalaev]

Shipped in #33 — clientwright[settings] → clientwright.contrib.settings.

What it maps to on your side: each client section on your root settings becomes a BaseClientSettings field (with env_nested_delimiter="__" on the root), and the local models plus the mapping go — settings.warehouse.to_config("warehouse") is the whole translation. Eight models, one per dataclass, same field names and defaults. service_name is the argument of to_config, not a field: it is the metric label, code identity rather than a deployment value.

The hazard is closed by construction. Nothing in the module is a BaseSettings, and the suite sets BASE_URL, TIMEOUT, TOTAL, MAX_ATTEMPTS, HTTP2 and VERIFY in the environment and asserts a nested section stays at its defaults — next to a BaseSettings negative control that does pick BASE_URL up.

Two things to know. UNSET survives the trip: a knob you leave alone (timeout.read, pool.http2, pool.max_connections_per_host, ...) reaches the config as UNSET, the adapter's native default, and an explicit null is the explicit "unbounded" — for a scalar that needs env_parse_none_str="null" on your root settings, while a whole section (WAREHOUSE__RETRY=null) is parsed as JSON and needs nothing. And observability.url_masker is not a field, it is a callable: set it on the config after to_config().

The extra pins pydantic>=2,<3 and pydantic-settings>=2.3,<3, so your 2.13 / 2.13 are in range. Field names and defaults are asserted against the dataclasses on every run (BaseClientSettings().to_config("x") == ClientConfig(service_name="x") is one of the tests), so the models cannot drift from the config without a red build here rather than a surprise in your repo. The guide is guide/settings.md once the release is out; client_config_from_settings stays for the flat legacy shape, new code should use the models.