grpc-client-kit 0.1.2__tar.gz → 0.2.0__tar.gz

{grpc_client_kit-0.1.2 → grpc_client_kit-0.2.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.2.0](https://github.com/bedrock-python/grpc-client-kit/compare/grpc-client-kit-v0.1.2...grpc-client-kit-v0.2.0) (2026-09-14)
+
+
+### Features
+
+* settings models for the environment, mirroring the dataclasses ([edffb5f](https://github.com/bedrock-python/grpc-client-kit/commit/edffb5fdcf934cecd5788a99e37064133383d9cd))
+
 ## [0.1.2](https://github.com/bedrock-python/grpc-client-kit/compare/grpc-client-kit-v0.1.1...grpc-client-kit-v0.1.2) (2026-09-07)
 
 

{grpc_client_kit-0.1.2 → grpc_client_kit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: grpc-client-kit
-Version: 0.1.2
+Version: 0.2.0
 Summary: Batteries-optional async gRPC client toolkit (channel pool, load balancing, health checking, streaming-aware interceptors, observability)
 Project-URL: Repository, https://github.com/bedrock-python/grpc-client-kit
 Project-URL: Documentation, https://bedrock-python.github.io/grpc-client-kit/
@@ -226,6 +226,7 @@ Requires-Dist: deadline-budget<1.0.0,>=0.1.0; extra == 'all'
 Requires-Dist: grpcio-health-checking<2.0.0,>=1.78.0; extra == 'all'
 Requires-Dist: opentelemetry-api<2.0.0,>=1.30.0; extra == 'all'
 Requires-Dist: prometheus-client<1.0.0,>=0.20.0; extra == 'all'
+Requires-Dist: pydantic<3.0,>=2.0.0; extra == 'all'
 Provides-Extra: deadline
 Requires-Dist: deadline-budget<1.0.0,>=0.1.0; extra == 'deadline'
 Provides-Extra: health
@@ -235,6 +236,8 @@ Requires-Dist: prometheus-client<1.0.0,>=0.20.0; extra == 'metrics'
 Provides-Extra: observability
 Requires-Dist: opentelemetry-api<2.0.0,>=1.30.0; extra == 'observability'
 Requires-Dist: prometheus-client<1.0.0,>=0.20.0; extra == 'observability'
+Provides-Extra: settings
+Requires-Dist: pydantic<3.0,>=2.0.0; extra == 'settings'
 Provides-Extra: tracing
 Requires-Dist: opentelemetry-api<2.0.0,>=1.30.0; extra == 'tracing'
 Description-Content-Type: text/markdown
@@ -307,6 +310,7 @@ pip install "grpc-client-kit[health]"             # + grpc.health.v1 monitoring
 pip install "grpc-client-kit[metrics,tracing]"    # + Prometheus + OpenTelemetry
 pip install "grpc-client-kit[observability]"      # + metrics and tracing together
 pip install "grpc-client-kit[deadline]"           # + request budget propagation
+pip install "grpc-client-kit[settings]"           # + pydantic settings models
 pip install "grpc-client-kit[all]"                # everything
 ```
 
@@ -362,7 +366,11 @@ Any object carrying the fields of `GrpcClientSettingsProtocol` works —
 a pydantic model, a dataclass, a plain class. Everything optional
 (`credentials`, `options`, `compression`, `metrics_registry`,
 `sensitive_headers`) is read through `getattr`, so a minimal settings object
-stays valid. See the
+stays valid. Or take the shipped one: `grpc_client_kit.settings.BaseGrpcClientSettings`
+(the `[settings]` extra) is that shape written down once — plain pydantic
+models with the kit's own defaults and bounds, one per upstream, nested under
+your service's `BaseSettings` for loading from the environment, and
+`to_config()` on every section for a hand-built chain. See the
 [configuration guide](https://bedrock-python.github.io/grpc-client-kit/guide/configuration/)
 for the full field list.
 
@@ -511,6 +519,7 @@ names the extra to install.
 | `channel.ChannelPool` | Channels pooled by full identity, idle eviction, health flags | core |
 | `client.GrpcClient` | Stub factory: target selection + channel acquisition | core |
 | `factory.GrpcClientFactory` | Settings → pool, balancer, health checker, per-target chains | core |
+| `settings.BaseGrpcClientSettings` | The settings shape as pydantic models mirroring the dataclasses, `to_config()` on each | `settings` |
 | `balancers.*` | Round-robin / random / weighted selection with health filtering | core |
 | `interceptors.*` | Context, logging, timeout, wait-for-ready, retry, circuit breaker + chain builder | core |
 | `deadline` + `interceptors.deadline` | The request budget in a contextvar, and the layer that trims every call to it | `deadline` |
@@ -530,8 +539,9 @@ with any backend you pass. The `[metrics]` extra only supplies the usual one.
 | `tracing` | `opentelemetry-api` | `AsyncClientTracingInterceptor` (a pass-through without it) |
 | `metrics` | `prometheus-client` | the default metrics backend; a custom registry needs no extra |
 | `deadline` | `deadline-budget` | `AsyncDeadlineBudgetInterceptor` (the layer is skipped without it) |
+| `settings` | `pydantic` | `BaseGrpcClientSettings` and the section models |
 | `observability` | `metrics` + `tracing` | both of the above |
-| `all` | `deadline` + `health` + `metrics` + `tracing` | everything |
+| `all` | `deadline` + `health` + `metrics` + `settings` + `tracing` | everything |
 
 `deadline` is deliberately not part of `observability`: propagating a budget is
 resilience, not telemetry, and an observability extra should not pull in a

{grpc_client_kit-0.1.2 → grpc_client_kit-0.2.0}/README.md

@@ -66,6 +66,7 @@ pip install "grpc-client-kit[health]"             # + grpc.health.v1 monitoring
 pip install "grpc-client-kit[metrics,tracing]"    # + Prometheus + OpenTelemetry
 pip install "grpc-client-kit[observability]"      # + metrics and tracing together
 pip install "grpc-client-kit[deadline]"           # + request budget propagation
+pip install "grpc-client-kit[settings]"           # + pydantic settings models
 pip install "grpc-client-kit[all]"                # everything
 ```
 
@@ -121,7 +122,11 @@ Any object carrying the fields of `GrpcClientSettingsProtocol` works —
 a pydantic model, a dataclass, a plain class. Everything optional
 (`credentials`, `options`, `compression`, `metrics_registry`,
 `sensitive_headers`) is read through `getattr`, so a minimal settings object
-stays valid. See the
+stays valid. Or take the shipped one: `grpc_client_kit.settings.BaseGrpcClientSettings`
+(the `[settings]` extra) is that shape written down once — plain pydantic
+models with the kit's own defaults and bounds, one per upstream, nested under
+your service's `BaseSettings` for loading from the environment, and
+`to_config()` on every section for a hand-built chain. See the
 [configuration guide](https://bedrock-python.github.io/grpc-client-kit/guide/configuration/)
 for the full field list.
 
@@ -270,6 +275,7 @@ names the extra to install.
 | `channel.ChannelPool` | Channels pooled by full identity, idle eviction, health flags | core |
 | `client.GrpcClient` | Stub factory: target selection + channel acquisition | core |
 | `factory.GrpcClientFactory` | Settings → pool, balancer, health checker, per-target chains | core |
+| `settings.BaseGrpcClientSettings` | The settings shape as pydantic models mirroring the dataclasses, `to_config()` on each | `settings` |
 | `balancers.*` | Round-robin / random / weighted selection with health filtering | core |
 | `interceptors.*` | Context, logging, timeout, wait-for-ready, retry, circuit breaker + chain builder | core |
 | `deadline` + `interceptors.deadline` | The request budget in a contextvar, and the layer that trims every call to it | `deadline` |
@@ -289,8 +295,9 @@ with any backend you pass. The `[metrics]` extra only supplies the usual one.
 | `tracing` | `opentelemetry-api` | `AsyncClientTracingInterceptor` (a pass-through without it) |
 | `metrics` | `prometheus-client` | the default metrics backend; a custom registry needs no extra |
 | `deadline` | `deadline-budget` | `AsyncDeadlineBudgetInterceptor` (the layer is skipped without it) |
+| `settings` | `pydantic` | `BaseGrpcClientSettings` and the section models |
 | `observability` | `metrics` + `tracing` | both of the above |
-| `all` | `deadline` + `health` + `metrics` + `tracing` | everything |
+| `all` | `deadline` + `health` + `metrics` + `settings` + `tracing` | everything |
 
 `deadline` is deliberately not part of `observability`: propagating a budget is
 resilience, not telemetry, and an observability extra should not pull in a

grpc_client_kit-0.2.0/grpc_client_kit/__version__.py

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

{grpc_client_kit-0.1.2 → grpc_client_kit-0.2.0}/grpc_client_kit/factory.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from dataclasses import fields
 from typing import TYPE_CHECKING, Any
 
 import grpc.aio
@@ -8,7 +9,7 @@ import grpc.aio
 from .balancers import LoadBalancer, LoadBalancerConfig, LoadBalancingStrategy, create_balancer
 from .channel import ChannelPool
 from .client import GrpcClient
-from .config import GrpcClientConfig
+from .config import ConnectivityConfig, GrpcClientConfig
 from .interceptors import (
     CircuitBreakerConfig,
     DeadlineBudgetConfig,
@@ -35,6 +36,10 @@ logger = logging.getLogger(__name__)
 
 _MISSING_MESSAGE = "Install grpc-client-kit[health] (grpcio-health-checking) to use gRPC health checking"
 
+# What a duck-typed `connectivity` block may carry: the dataclass's own fields, so a knob added there
+# is read from settings without this module having to hear about it.
+_CONNECTIVITY_FIELDS = tuple(field.name for field in fields(ConnectivityConfig))
+
 
 def _validate_settings(settings: object | None) -> None:
     """Refuse a settings object that cannot satisfy the factory, while the mistake is visible.
@@ -306,6 +311,10 @@ class GrpcClientFactory:
                         metrics_registry=metrics_registry,
                         service_name=actual_service_name,
                         sensitive_headers=getattr(self._settings, "sensitive_headers", None),
+                        sensitive_methods=getattr(self._settings, "sensitive_methods", None),
+                        sensitive_patterns=getattr(self._settings, "sensitive_patterns", None),
+                        log_request_payload=getattr(self._settings, "log_request_payload", False),
+                        log_response_payload=getattr(self._settings, "log_response_payload", False),
                         enable_method_label=getattr(self._settings, "enable_method_label", True),
                         success_log_level=getattr(self._settings, "success_log_level", logging.INFO),
                     )
@@ -371,8 +380,8 @@ class GrpcClientFactory:
         Channel construction settings are optional blocks (see `protocols.GrpcChannelExtrasProtocol`)
         and are read with `getattr`, so a settings model that declares none of them still satisfies
         the factory. ``connectivity`` joins them on the same terms: a settings object that carries a
-        `config.ConnectivityConfig` under that name has its channels tuned by it, and one that does
-        not is left with gRPC's defaults.
+        `config.ConnectivityConfig` — or a block with its fields — under that name has its channels
+        tuned by it, and one that does not is left with gRPC's defaults.
         """
         if self._settings:
             actual_target = target or self._settings.target
@@ -380,7 +389,7 @@ class GrpcClientFactory:
             credentials = getattr(self._settings, "credentials", None)
             options = getattr(self._settings, "options", None)
             compression = getattr(self._settings, "compression", None)
-            connectivity = getattr(self._settings, "connectivity", None)
+            connectivity = self._build_connectivity_config(getattr(self._settings, "connectivity", None))
         else:
             actual_target = target
             insecure = False
@@ -422,11 +431,23 @@ class GrpcClientFactory:
             health_checker=self._health_checker,
         )
 
+    def _build_connectivity_config(self, s: Any | None) -> ConnectivityConfig | None:
+        """Build ConnectivityConfig from an optional settings block (duck-typed).
+
+        A ready `config.ConnectivityConfig` is taken as it is. Any other block is read field by
+        field, and a field it does not carry keeps the dataclass's own default.
+        """
+        if not s:
+            return None
+        if isinstance(s, ConnectivityConfig):
+            return s
+        return ConnectivityConfig(**{name: getattr(s, name) for name in _CONNECTIVITY_FIELDS if hasattr(s, name)})
+
     def _build_timeout_config(self, s: TimeoutSettingsProtocol | None) -> TimeoutConfig | None:
-        """Build TimeoutConfig from settings protocol."""
+        """Build TimeoutConfig from settings protocol; per-method budgets are read when the block has them."""
         if not s:
             return None
-        return TimeoutConfig(default=s.default)
+        return TimeoutConfig(default=s.default, per_method=dict(getattr(s, "per_method", None) or {}))
 
     def _build_retry_config(
         self, s: RetrySettingsProtocol | None, metrics: GrpcClientMetricsProtocol | None = None

grpc_client_kit-0.2.0/grpc_client_kit/settings.py

@@ -0,0 +1,418 @@
+"""The settings shape the factory reads, as pydantic models, written down once.
+
+`factory.GrpcClientFactory` reads a settings object structurally — `protocols.GrpcClientSettingsProtocol`
+and the optional blocks around it — so every service used to write its own models for that shape and
+its own mapping onto the kit's dataclasses, and every copy drifted in its own way. These models are
+that shape with the kit's own defaults and bounds; each one that mirrors a dataclass knows how to
+become it (``to_config()``), and the kit's own tests pin the two field sets to each other.
+
+Every class here is a plain :class:`pydantic.BaseModel`, deliberately. A section that were a
+``BaseSettings`` would read the environment on its own, with no prefix, and a bare ``TARGET`` or
+``TIMEOUT`` in a pod would land in it. Nest :class:`BaseGrpcClientSettings` under the service's own
+settings instead, once per upstream, and let that class own the environment::
+
+    from pydantic import Field
+    from pydantic_settings import BaseSettings, SettingsConfigDict
+
+    from grpc_client_kit import GrpcClientFactory
+    from grpc_client_kit.settings import BaseGrpcClientSettings
+
+
+    class Settings(BaseSettings):
+        model_config = SettingsConfigDict(env_nested_delimiter="__")
+
+        users_grpc: BaseGrpcClientSettings = Field(default_factory=BaseGrpcClientSettings)
+
+
+    # USERS_GRPC__TARGET=users.internal:50051 USERS_GRPC__RETRY__MAX_ATTEMPTS=5 python main.py
+    settings = Settings()
+    factory = GrpcClientFactory(settings=settings.users_grpc)
+
+Runtime objects are not settings and have no field here: channel credentials are handed to
+:meth:`BaseGrpcClientSettings.to_config`, metrics registries and retry callbacks to the factory or to
+the chain built from the sections. Unknown fields are refused, so a misspelled variable fails at load
+instead of quietly yielding a default.
+
+This module needs the ``settings`` extra (``grpc-client-kit[settings]``), which pulls in pydantic;
+importing it without raises an ``ImportError`` naming the extra.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import grpc
+
+from .balancers import LoadBalancerConfig, LoadBalancingStrategy
+from .config import ConnectivityConfig, GrpcClientConfig
+from .interceptors import (
+    CircuitBreakerConfig,
+    DeadlineBudgetConfig,
+    RetryConfig,
+    TimeoutConfig,
+    WaitForReadyConfig,
+)
+
+try:
+    from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+except ImportError as exc:
+    raise ImportError("Install grpc-client-kit[settings] (pydantic) to use the settings models") from exc
+
+# The names an operator writes for `grpc.Compression`. "none" is gRPC's explicit no-compression
+# setting, not the absence of one — that is ``None``, which leaves the gRPC default alone.
+_COMPRESSION_BY_NAME: dict[str, grpc.Compression] = {
+    "none": grpc.Compression.NoCompression,
+    "deflate": grpc.Compression.Deflate,
+    "gzip": grpc.Compression.Gzip,
+}
+
+
+def _status_code_by_name(value: object) -> object:
+    """Resolve a status code written by name (``UNAVAILABLE``); anything else is left to pydantic."""
+    if not isinstance(value, str):
+        return value
+    try:
+        return grpc.StatusCode[value.upper()]
+    except KeyError:
+        names = ", ".join(code.name for code in grpc.StatusCode)
+        raise ValueError(f"unknown gRPC status code {value!r}; expected one of {names}") from None
+
+
+class BaseConnectivitySettings(BaseModel):
+    """``connectivity``: keepalive and reconnect backoff in seconds, `config.ConnectivityConfig` by environment.
+
+    Opt-in like the dataclass: an absent block leaves every channel argument at gRPC's own default,
+    and ``None`` in a field does the same for that argument alone.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    keepalive_time: float | None = Field(
+        default=30.0, gt=0, description="Seconds of inactivity before a keepalive ping (None: never ping)"
+    )
+    keepalive_timeout: float | None = Field(default=10.0, gt=0, description="Seconds to wait for the ping's answer")
+    permit_without_calls: bool = Field(default=False, description="Keep pinging while no call is in flight")
+    max_pings_without_data: int | None = Field(
+        default=2, ge=0, description="Pings allowed on a connection carrying no data (0: no limit)"
+    )
+    initial_reconnect_backoff: float | None = Field(
+        default=1.0, gt=0, description="Seconds before the first reconnect attempt"
+    )
+    min_reconnect_backoff: float | None = Field(
+        default=None, gt=0, description="Lower bound between reconnect attempts (None: gRPC's default)"
+    )
+    max_reconnect_backoff: float | None = Field(
+        default=30.0, gt=0, description="Upper bound between reconnect attempts"
+    )
+
+    def to_config(self) -> ConnectivityConfig:
+        """Build the `config.ConnectivityConfig` these fields describe.
+
+        Raises:
+            ValueError: If the reconnect bounds contradict each other; the dataclass keeps that check.
+        """
+        return ConnectivityConfig(**self.model_dump())
+
+
+class BaseChannelPoolSettings(BaseModel):
+    """``pool``: what `channel.ChannelPool` is sized with, read by the factory."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_channels_per_target: int = Field(default=1, ge=1, description="Channels per channel identity")
+    idle_timeout: float = Field(
+        default=300.0, description="Seconds without active RPCs before gRPC parks a connection (0: never)"
+    )
+
+
+class BaseTimeoutSettings(BaseModel):
+    """``timeout``: the budget of a whole call, retries included; `interceptors.TimeoutConfig` by environment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    default: float = Field(
+        default=10.0, ge=0, description="Budget in seconds for methods not listed in per_method (0: no deadline)"
+    )
+    per_method: dict[str, float | None] = Field(
+        default_factory=dict,
+        description='Budgets by full method name, as JSON: {"/pkg.Service/Method": 60} (null: no deadline)',
+    )
+
+    def to_config(self) -> TimeoutConfig:
+        """Build the `interceptors.TimeoutConfig` these fields describe."""
+        return TimeoutConfig(**self.model_dump())
+
+
+class BaseRetrySettings(BaseModel):
+    """``retry``: the retry policy, `interceptors.RetryConfig` by environment.
+
+    Status codes are written by name (``UNAVAILABLE``). ``on_retry`` and ``metrics`` are runtime
+    objects and have no field here; the factory injects the registry, a hand-built chain sets both on
+    the config `to_config` returns.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    max_attempts: int = Field(default=3, ge=1, description="Total attempts, the first one included")
+    initial_backoff: float = Field(default=0.1, ge=0, description="Seconds before the first retry")
+    max_backoff: float = Field(default=10.0, ge=0, description="Upper bound for the wait between retries")
+    backoff_multiplier: float = Field(default=2.0, ge=1, description="Growth factor of the backoff per attempt")
+    jitter: float = Field(default=0.1, ge=0, le=1, description="Random variation applied to the backoff")
+    retryable_codes: set[grpc.StatusCode] | None = Field(
+        default=None, description="Status codes that trigger a retry, by name (None: the kit's default set)"
+    )
+    retry_streaming: bool = Field(default=False, description="Allow retrying unary-stream calls at all")
+    idempotent_methods: set[str] | None = Field(
+        default=None, description="Full method names that may be retried; a whitelist once given"
+    )
+
+    @field_validator("retryable_codes", mode="before")
+    @classmethod
+    def _codes_by_name(cls, value: object) -> object:
+        if isinstance(value, (list, tuple, set, frozenset)):
+            return {_status_code_by_name(item) for item in value}
+        return value
+
+    def to_config(self) -> RetryConfig:
+        """Build the `interceptors.RetryConfig` these fields describe, with no callback and no registry."""
+        return RetryConfig(**self.model_dump())
+
+
+class BaseCircuitBreakerSettings(BaseModel):
+    """``circuit_breaker``: per-method, per-target breaking; `interceptors.CircuitBreakerConfig` by environment.
+
+    ``metrics`` is a runtime object and has no field here; the factory injects the registry.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    fail_threshold: int = Field(default=5, ge=1, description="Consecutive failed attempts that open a circuit")
+    recovery_timeout: float = Field(default=60.0, ge=0, description="Seconds an open circuit waits before a trial")
+    half_open_max_calls: int = Field(default=1, ge=1, description="Trial calls admitted while half-open")
+    max_methods: int = Field(default=1000, ge=1, description="Methods tracked per breaker before the LRU evicts")
+
+    def to_config(self) -> CircuitBreakerConfig:
+        """Build the `interceptors.CircuitBreakerConfig` these fields describe, with no registry."""
+        return CircuitBreakerConfig(**self.model_dump())
+
+
+class BaseWaitForReadySettings(BaseModel):
+    """``wait_for_ready``: wait for a connection instead of failing fast; `interceptors.WaitForReadyConfig`."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    default: bool | None = Field(
+        default=True, description="Value for methods not listed in per_method (None: untouched)"
+    )
+    per_method: dict[str, bool | None] = Field(
+        default_factory=dict, description='Values by full method name, as JSON: {"/pkg.Service/Method": false}'
+    )
+    require_deadline: bool = Field(default=True, description="Wait only on calls that carry a deadline")
+
+    def to_config(self) -> WaitForReadyConfig:
+        """Build the `interceptors.WaitForReadyConfig` these fields describe."""
+        return WaitForReadyConfig(**self.model_dump())
+
+
+class BaseDeadlineBudgetSettings(BaseModel):
+    """``deadline_budget``: request budget propagation; `interceptors.DeadlineBudgetConfig` by environment.
+
+    Needs the ``deadline`` extra to take effect; without it the layer is skipped with a warning.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    reserve_for_next: float = Field(
+        default=0.0, ge=0, description="Seconds every call keeps back for the work that follows it"
+    )
+
+    def to_config(self) -> DeadlineBudgetConfig:
+        """Build the `interceptors.DeadlineBudgetConfig` these fields describe."""
+        return DeadlineBudgetConfig(**self.model_dump())
+
+
+class BaseLoadBalancerSettings(BaseModel):
+    """``balancer``: how a target is picked from ``targets``; `balancers.LoadBalancerConfig` by environment."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    strategy: LoadBalancingStrategy = Field(
+        default=LoadBalancingStrategy.ROUND_ROBIN, description="round_robin, random or weighted"
+    )
+    weights: dict[str, float] | None = Field(
+        default=None, description='Weights by target for the weighted strategy, as JSON: {"host:50051": 2.0}'
+    )
+
+    def to_config(self) -> LoadBalancerConfig:
+        """Build the `balancers.LoadBalancerConfig` these fields describe."""
+        return LoadBalancerConfig(**self.model_dump())
+
+
+class BaseHealthCheckerSettings(BaseModel):
+    """``health_checker``: active ``grpc.health.v1`` probing of ``targets``, read by the factory.
+
+    Needs the ``health`` extra: the factory raises ``ImportError`` naming it when this block is set.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    check_interval: float = Field(default=30.0, gt=0, description="Seconds between probes of a healthy target")
+    timeout: float = Field(default=5.0, gt=0, description="Seconds one probe may take")
+    service: str = Field(default="", description="Service name probed; empty asks about the server as a whole")
+
+
+class BaseGrpcClientSettings(BaseModel):
+    """One upstream's client settings: what the factory reads, and `config.GrpcClientConfig` by `to_config`.
+
+    Satisfies `protocols.GrpcClientSettingsProtocol` and carries every optional block the factory
+    reads, so an instance is handed to `factory.GrpcClientFactory` as it is. The observability flags
+    are flat because that is how the protocol spells them; the rest of
+    `interceptors.ObservabilityConfig` sits next to them under the dataclass's own names, minus
+    ``service_name`` (the factory names each client after its stub) and the registry.
+
+    Two blocks are present by default: ``pool``, at the pool's own defaults, and ``timeout``, because
+    a client without a deadline is the one default this kit will not ship — ``TIMEOUT__DEFAULT=0``
+    switches it off. Everything that adds a layer or needs an extra — retries, the breaker,
+    wait-for-ready, budget propagation, balancing, health checks, connectivity tuning — is ``None``
+    until configured; with pydantic-settings a nested block is created the moment one of its
+    variables is set. Subclass it to change a default or add fields of your own::
+
+        class UsersGrpcSettings(BaseGrpcClientSettings):
+            retry: BaseRetrySettings | None = Field(default_factory=BaseRetrySettings)
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    # Channel
+    target: str | None = Field(
+        default=None, description="Single target, host:port or a gRPC resolver URI; exclusive with targets"
+    )
+    targets: list[str] | None = Field(default=None, description="Targets to balance across; exclusive with target")
+    insecure: bool = Field(
+        default=False,
+        description="Plaintext channel (False: TLS, from the system trust store or to_config's credentials)",
+    )
+    options: list[tuple[str, Any]] | None = Field(
+        default=None, description='Raw channel arguments, as JSON pairs: [["grpc.max_receive_message_length", 8388608]]'
+    )
+    compression: grpc.Compression | None = Field(
+        default=None, description="Channel compression by name: none, deflate or gzip (None: the gRPC default)"
+    )
+    connectivity: BaseConnectivitySettings | None = Field(
+        default=None, description="Keepalive and reconnect tuning (None: gRPC's defaults)"
+    )
+
+    # Observability, flat: this is how GrpcClientSettingsProtocol spells the flags
+    tracing_enabled: bool = Field(default=False, description="Add the tracing layer (needs the tracing extra)")
+    metrics_enabled: bool = Field(default=False, description="Add the metrics layer (needs a registry)")
+    logging_enabled: bool = Field(default=True, description="Add the structured logging layer")
+    sensitive_headers: set[str] | None = Field(
+        default=None, description="Header names redacted in logged metadata (None: the kit's default set)"
+    )
+    sensitive_methods: set[str] | None = Field(
+        default=None, description="Full method names whose payloads and errors are kept out of the logs"
+    )
+    sensitive_patterns: list[str] | None = Field(
+        default=None, description="Regex patterns marking methods as sensitive"
+    )
+    log_request_payload: bool = Field(default=False, description="Log request payloads, truncated")
+    log_response_payload: bool = Field(default=False, description="Log response payloads, truncated")
+    enable_method_label: bool = Field(
+        default=True, description="Label metrics by method (off for services with thousands of methods)"
+    )
+    success_log_level: int = Field(
+        default=logging.INFO, description="Level of the record a successful call emits, by name or number"
+    )
+
+    # The blocks the factory maps onto the pool, the chain, the balancer and the health checker
+    pool: BaseChannelPoolSettings | None = Field(
+        default_factory=BaseChannelPoolSettings, description="Channel pool sizing"
+    )
+    timeout: BaseTimeoutSettings | None = Field(
+        default_factory=BaseTimeoutSettings, description="Call budgets (None: no timeout layer, so no deadline at all)"
+    )
+    retry: BaseRetrySettings | None = Field(default=None, description="Retry policy (None: no retry layer)")
+    circuit_breaker: BaseCircuitBreakerSettings | None = Field(
+        default=None, description="Circuit breaker (None: no breaker layer)"
+    )
+    wait_for_ready: BaseWaitForReadySettings | None = Field(
+        default=None, description="Wait for a connection instead of failing fast (None: gRPC's fail-fast)"
+    )
+    deadline_budget: BaseDeadlineBudgetSettings | None = Field(
+        default=None, description="Request budget propagation (None: none; needs the deadline extra)"
+    )
+    balancer: BaseLoadBalancerSettings | None = Field(
+        default=None, description="Strategy over targets (None: round-robin)"
+    )
+    health_checker: BaseHealthCheckerSettings | None = Field(
+        default=None, description="Active probing of targets (None: none; needs the health extra)"
+    )
+
+    @field_validator("compression", mode="before")
+    @classmethod
+    def _compression_by_name(cls, value: object) -> object:
+        if not isinstance(value, str):
+            return value
+        try:
+            return _COMPRESSION_BY_NAME[value.lower()]
+        except KeyError:
+            names = ", ".join(_COMPRESSION_BY_NAME)
+            raise ValueError(f"unknown compression {value!r}; expected one of {names}") from None
+
+    @field_validator("success_log_level", mode="before")
+    @classmethod
+    def _level_by_name(cls, value: object) -> object:
+        # An environment hands over strings, so a numeric one is left to pydantic's int coercion.
+        if not isinstance(value, str) or value.isdecimal():
+            return value
+        try:
+            return logging.getLevelNamesMapping()[value.upper()]
+        except KeyError:
+            raise ValueError(f"unknown log level {value!r}") from None
+
+    @model_validator(mode="after")
+    def _one_way_to_name_the_backend(self) -> BaseGrpcClientSettings:
+        if self.target is not None and self.targets:
+            raise ValueError("target and targets are mutually exclusive: one address, or a list to balance across")
+        return self
+
+    def to_config(self, *, credentials: grpc.ChannelCredentials | None = None) -> GrpcClientConfig:
+        """Build the `config.GrpcClientConfig` these fields describe.
+
+        The chain is built from the sections (``settings.retry.to_config()`` and so on, into
+        `interceptors.build_interceptors`); the factory does both from the same instance.
+
+        Args:
+            credentials: TLS credentials for the channel. A credentials object is built in code, not
+                read from an environment, so it is handed in here — and ``insecure=True`` together with
+                credentials is refused by the dataclass, exactly as it always was.
+
+        Returns:
+            The channel configuration.
+
+        Raises:
+            ValueError: If the configuration contradicts itself; the dataclasses keep those checks.
+        """
+        return GrpcClientConfig(
+            target=self.target,
+            insecure=self.insecure,
+            credentials=credentials,
+            options=self.options,
+            compression=self.compression,
+            connectivity=self.connectivity.to_config() if self.connectivity is not None else None,
+        )
+
+
+__all__ = [
+    "BaseChannelPoolSettings",
+    "BaseCircuitBreakerSettings",
+    "BaseConnectivitySettings",
+    "BaseDeadlineBudgetSettings",
+    "BaseGrpcClientSettings",
+    "BaseHealthCheckerSettings",
+    "BaseLoadBalancerSettings",
+    "BaseRetrySettings",
+    "BaseTimeoutSettings",
+    "BaseWaitForReadySettings",
+]

{grpc_client_kit-0.1.2 → grpc_client_kit-0.2.0}/pyproject.toml

@@ -41,11 +41,14 @@ metrics = [
 deadline = [
     "deadline-budget>=0.1.0,<1.0.0",
 ]
+settings = [
+    "pydantic>=2.0.0,<3.0",
+]
 observability = [
     "grpc-client-kit[metrics,tracing]",
 ]
 all = [
-    "grpc-client-kit[deadline,health,metrics,tracing]",
+    "grpc-client-kit[deadline,health,metrics,settings,tracing]",
 ]
 
 [dependency-groups]
@@ -55,6 +58,7 @@ test = [
     "pytest-cov>=7.0.0",
     "pytest-lazy-fixtures>=1.1.1",
     "freezegun>=1.5.5",
+    "pydantic-settings>=2.0.0,<3.0",
 ]
 docs = [
     "zensical>=0.0.37",

grpc_client_kit-0.1.2/grpc_client_kit/__version__.py

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