redis-client-kit 0.2.0__tar.gz → 0.3.0__tar.gz

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.3.0](https://github.com/bedrock-python/redis-client-kit/compare/redis-client-kit-v0.2.0...redis-client-kit-v0.3.0) (2026-09-15)
+
+
+### Features
+
+* ship PrometheusRedisMetricsProvider and a cached get_redis_metrics ([fbe8feb](https://github.com/bedrock-python/redis-client-kit/commit/fbe8feba0b3041d6af4744482419156e7b1ca8e7))
+
 ## [0.2.0](https://github.com/bedrock-python/redis-client-kit/compare/redis-client-kit-v0.1.5...redis-client-kit-v0.2.0) (2026-09-07)
 
 

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: redis-client-kit
-Version: 0.2.0
+Version: 0.3.0
 Summary: Redis client with optional Pydantic, Prometheus, and Dishka support
 Project-URL: Repository, https://github.com/bedrock-python/redis-client-kit
 Project-URL: Documentation, https://bedrock-python.github.io/redis-client-kit/
@@ -425,14 +425,19 @@ client = create_async_redis_client(settings, metrics=metrics)
 # - myapp_redis_connection_errors_total{error_type}
 ```
 
+Prometheus registers a metric name once per process, so a second `RedisMetrics(prefix="myapp")`
+raises `ValueError`. `get_redis_metrics(prefix="myapp")` returns the one instance per prefix
+instead, which is what a test suite that rebuilds its container per test wants.
+
 ### With Dishka DI
 
 ```python
 from dishka import make_async_container
-from redis_client_kit.providers import AsyncRedisProvider
+from redis_client_kit.providers import AsyncRedisProvider, PrometheusRedisMetricsProvider
 
 container = make_async_container(
-    AsyncRedisProvider(),
+    AsyncRedisProvider(provide_default_metrics=False),
+    PrometheusRedisMetricsProvider(),  # RedisMetrics when settings.metrics_enabled, else None
     SettingsProvider(),  # Your settings provider
 )
 

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/README.md

@@ -185,14 +185,19 @@ client = create_async_redis_client(settings, metrics=metrics)
 # - myapp_redis_connection_errors_total{error_type}
 ```
 
+Prometheus registers a metric name once per process, so a second `RedisMetrics(prefix="myapp")`
+raises `ValueError`. `get_redis_metrics(prefix="myapp")` returns the one instance per prefix
+instead, which is what a test suite that rebuilds its container per test wants.
+
 ### With Dishka DI
 
 ```python
 from dishka import make_async_container
-from redis_client_kit.providers import AsyncRedisProvider
+from redis_client_kit.providers import AsyncRedisProvider, PrometheusRedisMetricsProvider
 
 container = make_async_container(
-    AsyncRedisProvider(),
+    AsyncRedisProvider(provide_default_metrics=False),
+    PrometheusRedisMetricsProvider(),  # RedisMetrics when settings.metrics_enabled, else None
     SettingsProvider(),  # Your settings provider
 )
 

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/redis_client_kit/__init__.py

@@ -24,7 +24,7 @@ from .utils import build_base_redis_kwargs, build_redis_retry, parse_redis_url_n
 try:
     __version__ = version("redis-client-kit")
 except PackageNotFoundError:  # pragma: no cover
-    __version__ = "0.2.0"
+    __version__ = "0.3.0"
 
 # ruff: noqa: RUF022
 __all__ = [

redis_client_kit-0.3.0/redis_client_kit/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.3.0"

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/redis_client_kit/config.py

@@ -89,3 +89,4 @@ class RedisSettingsProtocol(Protocol):
     ssl: RedisSSLProtocol
     response: RedisResponseProtocol
     health_check_interval: int | None
+    metrics_enabled: bool

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/redis_client_kit/metrics/__init__.py

@@ -5,6 +5,6 @@ from ._deps import HAS_PROMETHEUS
 if not HAS_PROMETHEUS:
     raise ImportError("prometheus-client not installed. Install redis-client-kit[metrics] to use metrics.")
 
-from .redis import REDIS_COMMAND_DURATION_BUCKETS, RedisMetrics
+from .redis import REDIS_COMMAND_DURATION_BUCKETS, RedisMetrics, get_redis_metrics
 
-__all__ = ["REDIS_COMMAND_DURATION_BUCKETS", "RedisMetrics"]
+__all__ = ["REDIS_COMMAND_DURATION_BUCKETS", "RedisMetrics", "get_redis_metrics"]

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/redis_client_kit/metrics/redis.py

@@ -30,6 +30,9 @@ class RedisMetrics:
         >>> metrics = RedisMetrics(prefix="myapp")
         >>> metrics.record_command("GET", "success", 0.001)
         >>> metrics.record_pool_stats(pool_size=10, pool_checked_out=3)
+
+    Prometheus registers a metric name once per registry, so a second instance with the
+    same prefix raises ``ValueError``; ``get_redis_metrics`` hands back the first one instead.
     """
 
     def __init__(self, prefix: str | None = None) -> None:
@@ -37,6 +40,10 @@ class RedisMetrics:
 
         Args:
             prefix: Optional metric name prefix (e.g., "myapp" -> "myapp_redis_pool_size")
+
+        Raises:
+            ValueError: If a metric of the same name is already registered on the default
+                registry -- see ``get_redis_metrics`` for the second instance.
         """
         metric_prefix = f"{prefix}_" if prefix else ""
 
@@ -95,4 +102,27 @@ class RedisMetrics:
         self.pool_checked_out.set(float(pool_checked_out))
 
 
-__all__ = ["REDIS_COMMAND_DURATION_BUCKETS", "RedisMetrics"]
+_REDIS_METRICS_CACHE: dict[str | None, RedisMetrics] = {}
+
+
+def get_redis_metrics(prefix: str | None = None) -> RedisMetrics:
+    """Get (or lazily create) the cached ``RedisMetrics`` 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; ``""`` and
+            ``None`` are the same unprefixed instance.
+
+    Returns:
+        The one instance for that prefix.
+    """
+    key = prefix or None
+    metrics = _REDIS_METRICS_CACHE.get(key)
+    if metrics is None:
+        metrics = _REDIS_METRICS_CACHE[key] = RedisMetrics(prefix=key)
+    return metrics
+
+
+__all__ = ["REDIS_COMMAND_DURATION_BUCKETS", "RedisMetrics", "get_redis_metrics"]

{redis_client_kit-0.2.0 → redis_client_kit-0.3.0}/redis_client_kit/providers/__init__.py

@@ -5,6 +5,7 @@ from ._deps import HAS_DISHKA
 if not HAS_DISHKA:
     raise ImportError("dishka not installed. Install redis-client-kit[providers] to use AsyncRedisProvider.")
 
+from .metrics import PrometheusRedisMetricsProvider
 from .redis import AsyncRedisProvider
 
-__all__ = ["AsyncRedisProvider"]
+__all__ = ["AsyncRedisProvider", "PrometheusRedisMetricsProvider"]

redis_client_kit-0.3.0/redis_client_kit/providers/metrics.py

@@ -0,0 +1,44 @@
+"""Dishka provider for the Prometheus Redis metrics collector."""
+
+from ..config import RedisSettingsProtocol
+from ..protocols import RedisMetricsProtocol
+from ._deps import Provider, Scope, provide
+
+
+class PrometheusRedisMetricsProvider(Provider):  # type: ignore[misc]
+    """Dishka provider for the collector ``AsyncRedisProvider`` records into.
+
+    Provides ``RedisMetricsProtocol | None`` -- the key ``AsyncRedisProvider`` reads -- as
+    ``get_redis_metrics(prefix)`` when ``settings.metrics_enabled`` and ``None`` otherwise,
+    so the client is instrumented exactly when the settings say so. Register it with
+    ``AsyncRedisProvider(provide_default_metrics=False)``, or after ``AsyncRedisProvider()``,
+    since the last provider of a type wins.
+
+    The collector comes from ``get_redis_metrics``: one instance per prefix on the default
+    registry, so a container rebuilt per test never asks Prometheus to register the same
+    series twice. Resolving it with metrics on needs the ``metrics`` extra; without it the
+    import raises ``ImportError`` naming the extra.
+    """
+
+    scope = Scope.APP  # type: ignore[misc]
+
+    def __init__(self, *, prefix: str | None = None) -> None:
+        """Remember the prefix the collector is created with.
+
+        Args:
+            prefix: Metric name prefix (``"myapp"`` gives ``myapp_redis_pool_size``)
+        """
+        super().__init__()
+        self._prefix = prefix
+
+    @provide
+    def get_metrics(self, redis_settings: RedisSettingsProtocol) -> RedisMetricsProtocol | None:
+        """Provide the collector when ``metrics_enabled`` is on, ``None`` otherwise."""
+        if not redis_settings.metrics_enabled:
+            return None
+        from ..metrics import get_redis_metrics  # noqa: PLC0415 - lazy: needs the [metrics] extra
+
+        return get_redis_metrics(self._prefix)
+
+
+__all__ = ["PrometheusRedisMetricsProvider"]

redis_client_kit-0.2.0/redis_client_kit/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"