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

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

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.0](https://github.com/bedrock-python/grpc-client-kit/compare/grpc-client-kit-v0.3.0...grpc-client-kit-v0.4.0) (2026-09-14)
+
+
+### Features
+
+* a container-owned channel pool for the Dishka providers, shared by every upstream told to borrow it ([ecdc4e2](https://github.com/bedrock-python/grpc-client-kit/commit/ecdc4e264bdad2b80311f25bfd922ad15ea2db07)), closes [#31](https://github.com/bedrock-python/grpc-client-kit/issues/31)
+
+## [0.3.0](https://github.com/bedrock-python/grpc-client-kit/compare/grpc-client-kit-v0.2.0...grpc-client-kit-v0.3.0) (2026-09-14)
+
+
+### Features
+
+* Prometheus collector for the metrics protocol and Dishka providers for the client lifecycle ([6dfdb44](https://github.com/bedrock-python/grpc-client-kit/commit/6dfdb44f2f818c6036f465844c96c2151ee511db)), closes [#28](https://github.com/bedrock-python/grpc-client-kit/issues/28)
+
 ## [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)
 
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: grpc-client-kit
-Version: 0.2.0
+Version: 0.4.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/
@@ -223,12 +223,15 @@ Requires-Python: >=3.12
 Requires-Dist: grpcio<2.0.0,>=1.78.0
 Provides-Extra: all
 Requires-Dist: deadline-budget<1.0.0,>=0.1.0; extra == 'all'
+Requires-Dist: dishka<2.0.0,>=1.4.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: dishka
+Requires-Dist: dishka<2.0.0,>=1.4.0; extra == 'dishka'
 Provides-Extra: health
 Requires-Dist: grpcio-health-checking<2.0.0,>=1.78.0; extra == 'health'
 Provides-Extra: metrics
@@ -311,6 +314,7 @@ 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[dishka]"             # + Dishka providers
 pip install "grpc-client-kit[all]"                # everything
 ```
 
@@ -525,7 +529,9 @@ names the extra to install.
 | `deadline` + `interceptors.deadline` | The request budget in a contextvar, and the layer that trims every call to it | `deadline` |
 | `interceptors.tracing` | OpenTelemetry CLIENT spans and `traceparent` injection | `tracing` |
 | `interceptors.metrics` | Counters, latency histograms and an in-flight gauge | core¹ |
+| `metrics.GrpcClientMetrics` | The Prometheus collector for them, shaped to join `grpc-server-kit`'s series | `metrics` |
 | `health.HealthChecker` | Background `grpc.health.v1` probing with per-target backoff | `health` |
+| `dishka.*` | Dishka providers owning the factory's lifecycle, one component per upstream, one pool shared by several | `dishka` |
 | `protocols` / `validation` / `utils` | Settings seams, target validation, channel and metadata helpers | core |
 
 ¹ The metrics interceptor records through `GrpcClientMetricsProtocol` and works
@@ -537,11 +543,12 @@ with any backend you pass. The `[metrics]` extra only supplies the usual one.
 | :--- | :--- | :--- |
 | `health` | `grpcio-health-checking` | `HealthChecker`, health-aware balancing and pooling |
 | `tracing` | `opentelemetry-api` | `AsyncClientTracingInterceptor` (a pass-through without it) |
-| `metrics` | `prometheus-client` | the default metrics backend; a custom registry needs no extra |
+| `metrics` | `prometheus-client` | `GrpcClientMetrics`, the Prometheus collector; a custom registry needs no extra |
 | `deadline` | `deadline-budget` | `AsyncDeadlineBudgetInterceptor` (the layer is skipped without it) |
 | `settings` | `pydantic` | `BaseGrpcClientSettings` and the section models |
+| `dishka` | `dishka` | `grpc_client_providers`, the three providers behind it, and the pool provider several upstreams share |
 | `observability` | `metrics` + `tracing` | both of the above |
-| `all` | `deadline` + `health` + `metrics` + `settings` + `tracing` | everything |
+| `all` | `deadline` + `dishka` + `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
@@ -575,7 +582,8 @@ Full documentation at [bedrock-python.github.io/grpc-client-kit](https://bedrock
 | [Load balancing](https://bedrock-python.github.io/grpc-client-kit/guide/load-balancing/) | round-robin, random and weighted selection with health filtering |
 | [Health](https://bedrock-python.github.io/grpc-client-kit/guide/health/) | `grpc.health.v1` probing, per-target backoff and cold starts |
 | [Observability](https://bedrock-python.github.io/grpc-client-kit/guide/observability/) | log records, CLIENT spans and the metrics an RPC emits |
-| [Advanced](https://bedrock-python.github.io/grpc-client-kit/guide/advanced/) | interceptors that re-issue calls, target validation, ownership and DI wiring |
+| [Dependency injection](https://bedrock-python.github.io/grpc-client-kit/guide/dependency-injection/) | the Dishka providers, what they own, one component per upstream, one pool shared by several |
+| [Advanced](https://bedrock-python.github.io/grpc-client-kit/guide/advanced/) | interceptors that re-issue calls, target validation and ownership |
 | [API reference](https://bedrock-python.github.io/grpc-client-kit/reference/) | generated from the source |
 | [For AI agents](https://bedrock-python.github.io/grpc-client-kit/agents/) | the whole API surface, the rules that break code when broken and a map of the rest, on one page to hand to a coding assistant |
 

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

@@ -67,6 +67,7 @@ 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[dishka]"             # + Dishka providers
 pip install "grpc-client-kit[all]"                # everything
 ```
 
@@ -281,7 +282,9 @@ names the extra to install.
 | `deadline` + `interceptors.deadline` | The request budget in a contextvar, and the layer that trims every call to it | `deadline` |
 | `interceptors.tracing` | OpenTelemetry CLIENT spans and `traceparent` injection | `tracing` |
 | `interceptors.metrics` | Counters, latency histograms and an in-flight gauge | core¹ |
+| `metrics.GrpcClientMetrics` | The Prometheus collector for them, shaped to join `grpc-server-kit`'s series | `metrics` |
 | `health.HealthChecker` | Background `grpc.health.v1` probing with per-target backoff | `health` |
+| `dishka.*` | Dishka providers owning the factory's lifecycle, one component per upstream, one pool shared by several | `dishka` |
 | `protocols` / `validation` / `utils` | Settings seams, target validation, channel and metadata helpers | core |
 
 ¹ The metrics interceptor records through `GrpcClientMetricsProtocol` and works
@@ -293,11 +296,12 @@ with any backend you pass. The `[metrics]` extra only supplies the usual one.
 | :--- | :--- | :--- |
 | `health` | `grpcio-health-checking` | `HealthChecker`, health-aware balancing and pooling |
 | `tracing` | `opentelemetry-api` | `AsyncClientTracingInterceptor` (a pass-through without it) |
-| `metrics` | `prometheus-client` | the default metrics backend; a custom registry needs no extra |
+| `metrics` | `prometheus-client` | `GrpcClientMetrics`, the Prometheus collector; a custom registry needs no extra |
 | `deadline` | `deadline-budget` | `AsyncDeadlineBudgetInterceptor` (the layer is skipped without it) |
 | `settings` | `pydantic` | `BaseGrpcClientSettings` and the section models |
+| `dishka` | `dishka` | `grpc_client_providers`, the three providers behind it, and the pool provider several upstreams share |
 | `observability` | `metrics` + `tracing` | both of the above |
-| `all` | `deadline` + `health` + `metrics` + `settings` + `tracing` | everything |
+| `all` | `deadline` + `dishka` + `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
@@ -331,7 +335,8 @@ Full documentation at [bedrock-python.github.io/grpc-client-kit](https://bedrock
 | [Load balancing](https://bedrock-python.github.io/grpc-client-kit/guide/load-balancing/) | round-robin, random and weighted selection with health filtering |
 | [Health](https://bedrock-python.github.io/grpc-client-kit/guide/health/) | `grpc.health.v1` probing, per-target backoff and cold starts |
 | [Observability](https://bedrock-python.github.io/grpc-client-kit/guide/observability/) | log records, CLIENT spans and the metrics an RPC emits |
-| [Advanced](https://bedrock-python.github.io/grpc-client-kit/guide/advanced/) | interceptors that re-issue calls, target validation, ownership and DI wiring |
+| [Dependency injection](https://bedrock-python.github.io/grpc-client-kit/guide/dependency-injection/) | the Dishka providers, what they own, one component per upstream, one pool shared by several |
+| [Advanced](https://bedrock-python.github.io/grpc-client-kit/guide/advanced/) | interceptors that re-issue calls, target validation and ownership |
 | [API reference](https://bedrock-python.github.io/grpc-client-kit/reference/) | generated from the source |
 | [For AI agents](https://bedrock-python.github.io/grpc-client-kit/agents/) | the whole API surface, the rules that break code when broken and a map of the rest, on one page to hand to a coding assistant |
 

grpc_client_kit-0.4.0/grpc_client_kit/__version__.py

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

grpc_client_kit-0.4.0/grpc_client_kit/dishka.py

@@ -0,0 +1,277 @@
+"""Dishka providers owning the client lifecycle (``[dishka]`` extra).
+
+What an application otherwise writes by hand — build the factory from the settings, start the health
+checker with the container, close the pool with it — lives here as providers, one per thing a
+container hands out, and a bundle registering the three of one upstream::
+
+    from dishka import make_async_container
+
+    from grpc_client_kit import GrpcClientFactory
+    from grpc_client_kit.dishka import grpc_client_providers
+
+    container = make_async_container(*grpc_client_providers(settings.users_grpc))
+    factory = await container.get(GrpcClientFactory)
+    users = factory.create_client(UserStub)
+    ...
+    await container.close()  # stops the checker, closes the pool
+
+- `GrpcClientSettingsProvider` holds the settings object and provides it as
+  `protocols.GrpcClientSettingsProtocol`, so `settings.BaseGrpcClientSettings` or anything structural
+  works.
+- `PrometheusGrpcClientMetricsProvider` provides ``GrpcClientMetricsProtocol | None``: the cached
+  `metrics.GrpcClientMetrics` when ``settings.metrics_enabled``, ``None`` otherwise — ``None`` being
+  the kit's own spelling of "no metrics", which the factory leaves the layer out for.
+- `AsyncGrpcClientProvider` provides `factory.GrpcClientFactory` in APP scope from an async generator,
+  entered when first resolved and left when the container closes.
+- `AsyncChannelPoolProvider` provides `channel.ChannelPool` the same way, for the upstreams that share
+  one; a factory with ``shared_pool=True`` borrows it instead of building its own.
+
+Several upstreams in one container are Dishka components: every provider takes ``component=``, so
+one bundle per upstream, each in its own component, is one factory per upstream::
+
+    container = make_async_container(
+        *grpc_client_providers(settings.users_grpc, component="users"),
+        *grpc_client_providers(settings.orders_grpc, component="orders"),
+    )
+    users = await container.get(GrpcClientFactory, component="users")
+
+Dishka resolves a component's dependencies inside that component, which is why each one carries its
+own three providers; the collector they hand out is the same instance, cached per prefix, and its
+series are told apart by ``service``. A single upstream uses the default component and needs none of
+this.
+
+One pool for all of them is `AsyncChannelPoolProvider` in the default component and ``shared_pool=True``
+on every bundle: each factory then borrows that `channel.ChannelPool` instead of building its own, and
+the container closes it once, after the factories, with the pool provider's grace::
+
+    container = make_async_container(
+        AsyncChannelPoolProvider(settings.grpc_pool, metrics=get_grpc_client_metrics()),
+        *grpc_client_providers(settings.users_grpc, component="users", shared_pool=True),
+        *grpc_client_providers(settings.orders_grpc, component="orders", shared_pool=True),
+    )
+
+This module needs the ``dishka`` extra (``grpc-client-kit[dishka]``); importing it without raises an
+``ImportError`` naming the extra.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from typing import Annotated
+
+try:
+    from dishka import DEFAULT_COMPONENT, FromComponent, Provider, Scope, provide
+except ImportError as exc:
+    raise ImportError("Install grpc-client-kit[dishka] (dishka) to use the Dishka providers") from exc
+
+from .channel import ChannelPool
+from .factory import GrpcClientFactory
+from .interceptors.metrics import HAS_METRICS
+from .protocols import ChannelPoolSettingsProtocol, GrpcClientMetricsProtocol, GrpcClientSettingsProtocol
+
+logger = logging.getLogger(__name__)
+
+
+class GrpcClientSettingsProvider(Provider):
+    """Provide one upstream's settings object as ``GrpcClientSettingsProtocol``.
+
+    Construct it with anything structurally satisfying the protocol — `settings.BaseGrpcClientSettings`,
+    a dataclass, a plain class. The other providers request the settings through the protocol, which
+    is what lets a second upstream be a second component rather than a second container.
+    """
+
+    scope = Scope.APP
+
+    def __init__(self, settings: GrpcClientSettingsProtocol, *, component: str | None = None) -> None:
+        super().__init__(component=component)
+        self._settings = settings
+
+    @provide
+    def settings(self) -> GrpcClientSettingsProtocol:
+        """Provide the settings object as it was given."""
+        return self._settings
+
+
+class PrometheusGrpcClientMetricsProvider(Provider):
+    """Provide the registry the factory records into: `metrics.GrpcClientMetrics`, or ``None``.
+
+    ``None`` when ``settings.metrics_enabled`` is off, and ``None`` with a warning when it is on but
+    the ``[metrics]`` extra is absent — the degradation the chain builder applies, so the provider can
+    always be registered. The collector comes from `metrics.get_grpc_client_metrics`, one instance per
+    prefix on the default registry, so a container rebuilt per test never asks Prometheus to register
+    the same series twice.
+    """
+
+    scope = Scope.APP
+
+    def __init__(self, *, prefix: str | None = None, component: str | None = None) -> None:
+        super().__init__(component=component)
+        self._prefix = prefix
+
+    @provide
+    def metrics(self, settings: GrpcClientSettingsProtocol) -> GrpcClientMetricsProtocol | None:
+        """Provide the collector when metrics are enabled and the extra is installed, ``None`` otherwise."""
+        if not settings.metrics_enabled:
+            return None
+        if not HAS_METRICS:
+            logger.warning("Metrics requested but grpc-client-kit[metrics] is not installed; metrics are disabled")
+            return None
+        from .metrics import get_grpc_client_metrics  # noqa: PLC0415 - lazy: needs the [metrics] extra
+
+        return get_grpc_client_metrics(self._prefix)
+
+
+class AsyncChannelPoolProvider(Provider):
+    """Provide one `channel.ChannelPool` in APP scope, built on first use and drained with the container.
+
+    The pool several upstreams share: registered in the default component, it is what every
+    `AsyncGrpcClientProvider` with ``shared_pool=True`` borrows, and the container closes it once —
+    ``close_all(grace=shutdown_grace)``, after the factories that used it have left. Sized from a
+    `protocols.ChannelPoolSettingsProtocol` — `settings.BaseChannelPoolSettings` nested at the top of
+    the service's settings is one deployment-wide section — and at the pool's own defaults without one.
+
+    ``metrics`` is the registry the pool statistics are recorded into. It is handed in here, the way
+    `factory.GrpcClientFactory` takes it, rather than requested from the container: a container with
+    one component per upstream has a registry per component and none in the default one, so there is
+    no single seam for the pool to ask. `metrics.get_grpc_client_metrics` returns the instance the
+    bundles hand out.
+    """
+
+    scope = Scope.APP
+
+    def __init__(
+        self,
+        settings: ChannelPoolSettingsProtocol | None = None,
+        *,
+        metrics: GrpcClientMetricsProtocol | None = None,
+        shutdown_grace: float | None = 5.0,
+        component: str | None = None,
+    ) -> None:
+        super().__init__(component=component)
+        self._settings = settings
+        self._metrics = metrics
+        self._shutdown_grace = shutdown_grace
+
+    @provide
+    async def pool(self) -> AsyncIterator[ChannelPool]:
+        """Build the pool from the settings and the registry, and drain it with the container."""
+        if self._settings is not None:
+            pool = ChannelPool(
+                max_channels_per_target=self._settings.max_channels_per_target,
+                idle_timeout=self._settings.idle_timeout,
+                metrics=self._metrics,
+            )
+        else:
+            pool = ChannelPool(metrics=self._metrics)
+        try:
+            yield pool
+        finally:
+            await pool.close_all(grace=self._shutdown_grace)
+
+
+class AsyncGrpcClientProvider(Provider):
+    """Provide `factory.GrpcClientFactory` in APP scope, entered on first use and closed with the container.
+
+    The factory builds and owns the pool and the health checker: resolving it starts the checker and
+    waits for its first pass (``ready_timeout``); closing the container stops the checker and closes
+    the pool, giving in-flight RPCs ``shutdown_grace`` — exactly what ``async with factory`` does.
+    Clients come from the factory as usual, ``factory.create_client(UserStub)``, and are cheap enough
+    to be request-scoped.
+
+    With ``shared_pool=True`` the factory borrows the `channel.ChannelPool` of the default component —
+    an `AsyncChannelPoolProvider` there, or anything providing ``ChannelPool`` — instead of building
+    one, and owns nothing but its health checker: closing the container still stops the checker,
+    while the pool is closed by whoever provided it, once, after every factory that borrowed it.
+    ``shutdown_grace`` then has nothing to apply to; the pool provider carries its own. A container
+    with such a factory and no ``ChannelPool`` in the default component is refused when it is built.
+    """
+
+    scope = Scope.APP
+
+    def __init__(
+        self,
+        *,
+        shutdown_grace: float | None = 5.0,
+        ready_timeout: float | None = 10.0,
+        shared_pool: bool = False,
+        component: str | None = None,
+    ) -> None:
+        super().__init__(component=component)
+        self._shutdown_grace = shutdown_grace
+        self._ready_timeout = ready_timeout
+        # One key, two sources, chosen here: a Dishka dependency cannot be optional, so a factory that
+        # asked for the pool would refuse every container without one.
+        self.provide(self.shared_factory if shared_pool else self.factory)
+
+    async def factory(
+        self,
+        settings: GrpcClientSettingsProtocol,
+        metrics: GrpcClientMetricsProtocol | None,
+    ) -> AsyncIterator[GrpcClientFactory]:
+        """Build the factory from the settings and the registry, and close it with the container."""
+        async with GrpcClientFactory(
+            settings=settings,
+            shutdown_grace=self._shutdown_grace,
+            ready_timeout=self._ready_timeout,
+            metrics=metrics,
+        ) as factory:
+            yield factory
+
+    async def shared_factory(
+        self,
+        settings: GrpcClientSettingsProtocol,
+        metrics: GrpcClientMetricsProtocol | None,
+        pool: Annotated[ChannelPool, FromComponent(DEFAULT_COMPONENT)],
+    ) -> AsyncIterator[GrpcClientFactory]:
+        """Build the factory on the default component's pool, which it borrows and never closes."""
+        async with GrpcClientFactory(
+            settings=settings,
+            pool=pool,
+            ready_timeout=self._ready_timeout,
+            metrics=metrics,
+        ) as factory:
+            yield factory
+
+
+def grpc_client_providers(
+    settings: GrpcClientSettingsProtocol,
+    *,
+    component: str | None = None,
+    metrics_prefix: str | None = None,
+    shutdown_grace: float | None = 5.0,
+    ready_timeout: float | None = 10.0,
+    shared_pool: bool = False,
+) -> tuple[Provider, ...]:
+    """Return the three providers of one upstream, for one-line registration.
+
+    Args:
+        settings: The upstream's settings object; anything satisfying `protocols.GrpcClientSettingsProtocol`.
+        component: The Dishka component to register the providers in — one per upstream when a
+            container serves several, the default component otherwise.
+        metrics_prefix: Prefix for the Prometheus metric names.
+        shutdown_grace: Seconds in-flight RPCs get to finish when the container closes; the pool
+            provider's own grace applies instead with ``shared_pool``.
+        ready_timeout: Seconds the factory waits for the first health check pass when resolved.
+        shared_pool: Borrow the ``ChannelPool`` of the default component — an `AsyncChannelPoolProvider`
+            registered there — instead of building one for this upstream.
+
+    Returns:
+        The providers, to unpack into ``make_async_container``.
+    """
+    return (
+        GrpcClientSettingsProvider(settings, component=component),
+        PrometheusGrpcClientMetricsProvider(prefix=metrics_prefix, component=component),
+        AsyncGrpcClientProvider(
+            shutdown_grace=shutdown_grace, ready_timeout=ready_timeout, shared_pool=shared_pool, component=component
+        ),
+    )
+
+
+__all__ = [
+    "AsyncChannelPoolProvider",
+    "AsyncGrpcClientProvider",
+    "GrpcClientSettingsProvider",
+    "PrometheusGrpcClientMetricsProvider",
+    "grpc_client_providers",
+]

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

@@ -98,6 +98,7 @@ class GrpcClientFactory:
         pool: ChannelProviderProtocol | None = None,
         shutdown_grace: float | None = 5.0,
         ready_timeout: float | None = 10.0,
+        metrics: GrpcClientMetricsProtocol | None = None,
     ) -> None:
         """Initialize the factory.
 
@@ -118,6 +119,12 @@ class GrpcClientFactory:
                 that pass every target reads unhealthy, so entering the context without waiting
                 would make the first call of every freshly started pod fail deterministically.
                 ``None`` waits indefinitely; only relevant when health checking is configured.
+            metrics: The registry RPC metrics, retries, breaker state and pool statistics are
+                recorded into: the default for every client this factory creates, and the one
+                the pool it creates reports to. Wins over ``settings.metrics_registry``;
+                `create_client(metrics=...)` wins over it per client. The shipped settings
+                models carry no registry, a registry being a runtime object, so this is where
+                one meets them.
 
         Raises:
             TypeError: If `settings` does not satisfy `GrpcClientSettingsProtocol`. Validated
@@ -135,21 +142,24 @@ class GrpcClientFactory:
         # reuse the same interceptor instances, or every create_client would mint a fresh channel
         # identity and a per-request client pattern would open a connection per request.
         self._chains: dict[tuple[str, str], list[grpc.aio.ClientInterceptor]] = {}
+        # The registry every client and the owned pool default to: the explicit one, else the
+        # settings' own — the shipped settings models carry none, a registry being a runtime object.
+        settings_registry = getattr(settings, "metrics_registry", None) if settings else None
+        self._metrics: GrpcClientMetricsProtocol | None = metrics if metrics is not None else settings_registry
 
         if pool:
             self._pool = pool
         else:
             self._owns_pool = True
-            metrics = getattr(settings, "metrics_registry", None) if settings else None
 
             if settings and settings.pool:
                 self._pool = ChannelPool(
                     max_channels_per_target=settings.pool.max_channels_per_target,
                     idle_timeout=settings.pool.idle_timeout,
-                    metrics=metrics,
+                    metrics=self._metrics,
                 )
             else:
-                self._pool = ChannelPool(metrics=metrics)
+                self._pool = ChannelPool(metrics=self._metrics)
 
         # Build and start HealthChecker if configured and we have targets
         if settings and settings.health_checker and settings.targets:
@@ -252,7 +262,8 @@ class GrpcClientFactory:
             stub_class: The gRPC stub class to instantiate.
             target: Optional target override. If not provided, uses target from settings.
             service_name: Name of the service for observability. Defaults to stub class name.
-            metrics: Optional metrics registry, overriding `settings.metrics_registry`.
+            metrics: Optional metrics registry for this client alone, overriding the factory's
+                ``metrics`` and `settings.metrics_registry`.
             interceptors: Optional list of additional custom interceptors. These instances are
                 shared by every target, unlike the chain the factory builds around them.
 
@@ -353,8 +364,9 @@ class GrpcClientFactory:
     def _resolve_metrics_registry(self, metrics: GrpcClientMetricsProtocol | None) -> GrpcClientMetricsProtocol | None:
         """Pick the registry RPC metrics are recorded into.
 
-        An explicit argument wins over `settings.metrics_registry`, which otherwise only fed pool
-        statistics and left `metrics_enabled` clients recording nothing at all.
+        An explicit argument wins over the factory's default — its own ``metrics`` argument, else
+        `settings.metrics_registry`, which otherwise only fed pool statistics and left
+        `metrics_enabled` clients recording nothing at all.
 
         Args:
             metrics: The registry passed to `create_client`, if any.
@@ -362,13 +374,12 @@ class GrpcClientFactory:
         Returns:
             The registry to use, or None if metrics cannot be recorded.
         """
-        settings_registry = getattr(self._settings, "metrics_registry", None) if self._settings else None
-        registry: GrpcClientMetricsProtocol | None = metrics if metrics is not None else settings_registry
+        registry: GrpcClientMetricsProtocol | None = metrics if metrics is not None else self._metrics
 
         if registry is None and self._settings and self._settings.metrics_enabled:
             logger.warning(
                 "metrics_enabled is set but no metrics registry is available. "
-                "Pass 'metrics=' to create_client() or set 'metrics_registry' in settings; "
+                "Pass 'metrics=' to the factory or to create_client(), or set 'metrics_registry' in settings; "
                 "gRPC client metrics are disabled."
             )
 

grpc_client_kit-0.4.0/grpc_client_kit/metrics.py

@@ -0,0 +1,229 @@
+"""The Prometheus collector for the client metrics protocols (``[metrics]`` extra).
+
+`GrpcClientMetrics` is the collector the kit's own layers record into. It satisfies
+`protocols.GrpcClientMetricsProtocol` and the two extension protocols the retry layer and the
+circuit breaker look for, `protocols.RetryMetricsProtocol` and
+`protocols.CircuitBreakerMetricsProtocol`, so a factory given one instance measures RPCs, retries,
+breaker state and the pool through it — the extensions are what make a retry storm visible, which the
+base protocol alone cannot show.
+
+It is shaped after ``grpc_server_kit.observability.metrics.GrpcServerMetrics`` on purpose: the same
+histogram buckets, and the server's label names in the server's order with ``rpc_type`` added after
+``method``. A dashboard therefore joins the caller's ``grpc_client_requests_total`` with the callee's
+``grpc_requests_total`` on ``service``, ``method``, ``status`` and ``grpc_code``, and compares the two
+latency histograms bucket for bucket.
+
+Prometheus registers a metric name once per registry, so a second ``GrpcClientMetrics()`` on the
+default registry raises ``ValueError`` — what a test suite runs into when it rebuilds a container.
+`get_grpc_client_metrics` is the answer: it caches one instance per prefix, and it is what the Dishka
+provider calls. A test that wants isolation passes a fresh ``registry=CollectorRegistry()`` instead.
+
+This module needs the ``metrics`` extra (``grpc-client-kit[metrics]``), which pulls in
+prometheus-client; importing it without raises an ``ImportError`` naming the extra.
+"""
+
+from __future__ import annotations
+
+import re
+
+try:
+    from prometheus_client import REGISTRY, CollectorRegistry, Counter, Enum, Gauge, Histogram
+except ImportError as exc:
+    raise ImportError("Install grpc-client-kit[metrics] (prometheus-client) to use the Prometheus collector") from exc
+
+from .interceptors.circuit_breaker import CircuitState
+
+# The server kit's buckets, so the two duration histograms compare bucket for bucket (seconds).
+DEFAULT_GRPC_BUCKETS: tuple[float, ...] = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
+
+_PREFIX_PATTERN = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+def _make_metric_name(name: str, prefix: str | None) -> str:
+    """Prefix a metric name, refusing a prefix that is not a valid metric name fragment.
+
+    Args:
+        name: The metric name without a prefix.
+        prefix: The prefix to put in front of it, or None for none.
+
+    Returns:
+        The name Prometheus is asked to register.
+
+    Raises:
+        ValueError: If the prefix is not a valid metric name fragment.
+    """
+    if not prefix:
+        return name
+    if not _PREFIX_PATTERN.match(prefix):
+        raise ValueError(
+            f"Invalid metric prefix: {prefix!r}. Prefixes must start with a letter or underscore and "
+            "contain only letters, numbers, or underscores."
+        )
+    return f"{prefix}_{name}"
+
+
+class GrpcClientMetrics:
+    """gRPC client metrics as Prometheus collectors, one instance per registry.
+
+    Metrics:
+        - ``grpc_client_requests_total`` (Counter) — labels: service, method, rpc_type, status, grpc_code
+        - ``grpc_client_request_duration_seconds`` (Histogram) — labels: service, method, rpc_type
+        - ``grpc_client_requests_in_flight`` (Gauge) — labels: service, method, rpc_type
+        - ``grpc_client_pool_channels`` (Gauge) — pooled channels
+        - ``grpc_client_pool_targets`` (Gauge) — distinct addresses the pooled channels lead to
+        - ``grpc_client_retries_total`` (Counter) — labels: service, method, grpc_code
+        - ``grpc_client_circuit_breaker_state`` (Enum: closed, open, half-open) — labels: method
+        - ``grpc_client_circuit_breaker_rejections_total`` (Counter) — labels: method
+
+    The label values are recorded as the kit's layers hand them over: ``service`` and ``method``
+    are the short names parsed from the method path for requests, and the full method path for
+    the breaker; ``status`` is ``success``, ``error``, ``rejected`` or ``cancelled``.
+    """
+
+    def __init__(
+        self,
+        prefix: str | None = None,
+        buckets: tuple[float, ...] = DEFAULT_GRPC_BUCKETS,
+        registry: CollectorRegistry | None = None,
+    ) -> None:
+        """Register the collectors.
+
+        Args:
+            prefix: Optional metric name prefix (``myapp`` gives ``myapp_grpc_client_requests_total``).
+            buckets: Histogram buckets for the request duration, in seconds.
+            registry: The registry to register with; the process-wide default when None.
+
+        Raises:
+            ValueError: If the prefix is invalid, or a metric of the same name is already
+                registered there — see `get_grpc_client_metrics` for the second instance.
+        """
+        self.buckets: tuple[float, ...] = tuple(buckets)
+        reg = registry if registry is not None else REGISTRY
+        self.requests_total = Counter(
+            _make_metric_name("grpc_client_requests_total", prefix),
+            "Total number of gRPC client requests",
+            ["service", "method", "rpc_type", "status", "grpc_code"],
+            registry=reg,
+        )
+        self.request_duration = Histogram(
+            _make_metric_name("grpc_client_request_duration_seconds", prefix),
+            "gRPC client request duration in seconds, retries and their backoff included",
+            ["service", "method", "rpc_type"],
+            buckets=list(buckets),
+            registry=reg,
+        )
+        self.requests_in_flight = Gauge(
+            _make_metric_name("grpc_client_requests_in_flight", prefix),
+            "gRPC client requests currently in progress",
+            ["service", "method", "rpc_type"],
+            registry=reg,
+        )
+        self.pool_channels = Gauge(
+            _make_metric_name("grpc_client_pool_channels", prefix),
+            "Channels currently held by the channel pool",
+            registry=reg,
+        )
+        self.pool_targets = Gauge(
+            _make_metric_name("grpc_client_pool_targets", prefix),
+            "Distinct target addresses the pooled channels lead to",
+            registry=reg,
+        )
+        self.retries_total = Counter(
+            _make_metric_name("grpc_client_retries_total", prefix),
+            "Total number of scheduled gRPC client retries",
+            ["service", "method", "grpc_code"],
+            registry=reg,
+        )
+        self.circuit_breaker_state = Enum(
+            _make_metric_name("grpc_client_circuit_breaker_state", prefix),
+            "State of the circuit breaker of a method",
+            ["method"],
+            states=[state.value for state in CircuitState],
+            registry=reg,
+        )
+        self.circuit_breaker_rejections_total = Counter(
+            _make_metric_name("grpc_client_circuit_breaker_rejections_total", prefix),
+            "Total number of gRPC client calls refused locally by an open circuit breaker",
+            ["method"],
+            registry=reg,
+        )
+
+    def record_request(
+        self,
+        service: str,
+        method: str,
+        rpc_type: str,
+        status: str,
+        grpc_code: str,
+        duration: float,
+    ) -> None:
+        """Record a completed gRPC request."""
+        self.requests_total.labels(
+            service=service, method=method, rpc_type=rpc_type, status=status, grpc_code=grpc_code
+        ).inc()
+        self.request_duration.labels(service=service, method=method, rpc_type=rpc_type).observe(duration)
+
+    def record_inflight_delta(self, service: str, method: str, rpc_type: str, delta: int) -> None:
+        """Move the in-flight gauge by ``delta``."""
+        self.requests_in_flight.labels(service=service, method=method, rpc_type=rpc_type).inc(delta)
+
+    def record_pool_stats(self, active_channels: int, idle_targets: int) -> None:
+        """Record the channel pool's size."""
+        self.pool_channels.set(active_channels)
+        self.pool_targets.set(idle_targets)
+
+    def record_retry(self, service: str, method: str, attempt: int, grpc_code: str) -> None:
+        """Count one scheduled retry; the attempt number is not a label, it would multiply the series."""
+        self.retries_total.labels(service=service, method=method, grpc_code=grpc_code).inc()
+
+    def record_circuit_state(self, method: str, state: str) -> None:
+        """Record a circuit state transition."""
+        self.circuit_breaker_state.labels(method=method).state(state)
+
+    def record_circuit_rejection(self, method: str) -> None:
+        """Count one call refused locally by an open circuit."""
+        self.circuit_breaker_rejections_total.labels(method=method).inc()
+
+
+_CLIENT_METRICS_CACHE: dict[str | None, GrpcClientMetrics] = {}
+
+
+def get_grpc_client_metrics(
+    prefix: str | None = None,
+    buckets: tuple[float, ...] | None = None,
+) -> GrpcClientMetrics:
+    """Get (or lazily create) the cached ``GrpcClientMetrics`` for a prefix, on the default registry.
+
+    Caching by prefix is what lets a container be rebuilt — a test suite does it per test —
+    without Prometheus refusing the second registration of the same series.
+
+    Args:
+        prefix: The metric name prefix the instance was, or is, created with.
+        buckets: Histogram buckets for a new instance; None takes the default.
+
+    Returns:
+        The one instance for that prefix.
+
+    Raises:
+        ValueError: If the prefix is already cached with DIFFERENT buckets — silently returning
+            the old instance would record latencies into the wrong histogram bounds with no error.
+    """
+    requested = tuple(buckets) if buckets is not None else DEFAULT_GRPC_BUCKETS
+    cached = _CLIENT_METRICS_CACHE.get(prefix)
+    if cached is not None:
+        if buckets is not None and requested != cached.buckets:
+            raise ValueError(
+                f"GrpcClientMetrics for prefix {prefix!r} already exists with buckets "
+                f"{cached.buckets}; cannot re-create it with {requested}"
+            )
+        return cached
+    metrics = GrpcClientMetrics(prefix=prefix, buckets=requested)
+    _CLIENT_METRICS_CACHE[prefix] = metrics
+    return metrics
+
+
+__all__ = [
+    "DEFAULT_GRPC_BUCKETS",
+    "GrpcClientMetrics",
+    "get_grpc_client_metrics",
+]

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

@@ -44,11 +44,14 @@ deadline = [
 settings = [
     "pydantic>=2.0.0,<3.0",
 ]
+dishka = [
+    "dishka>=1.4.0,<2.0.0",
+]
 observability = [
     "grpc-client-kit[metrics,tracing]",
 ]
 all = [
-    "grpc-client-kit[deadline,health,metrics,settings,tracing]",
+    "grpc-client-kit[deadline,dishka,health,metrics,settings,tracing]",
 ]
 
 [dependency-groups]

grpc_client_kit-0.2.0/grpc_client_kit/__version__.py

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