021-python-clients 0.1.0__py3-none-any.whl

clients_021/redis.py

@@ -0,0 +1,124 @@
+"""Redis, observed: JSON values with a TTL, one-time reads, windowed counters and a ping.
+
+    from clients_021.redis import RedisClient
+
+    redis = RedisClient.from_url(obs, settings.redis_url, dependency="redis")
+    await redis.set_json("session:abc", {"user": "ana"}, ttl_seconds=1800)
+    value = await redis.get_json("session:abc")
+
+Needs the `redis` extra. Calls record `db.client.operation.*` with `dependency` and
+`operation` (`get_json`, `set_json`, `take_json`, `delete`, `incr_window`, `ping`).
+Timeouts and connection failures raise DependencyUnavailable; a wrong command or type
+(`ResponseError`) is a bug and keeps its type.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable
+from typing import Any, cast
+
+from observability_021 import Observability
+from observability_021.config import identifier
+from redis.asyncio import Redis
+from redis.exceptions import AuthenticationError, AuthorizationError
+from redis.exceptions import ConnectionError as RedisConnectionError
+from redis.exceptions import TimeoutError as RedisTimeoutError
+
+from clients_021._observe import observed
+from clients_021.errors import DependencyUnavailable
+
+SYSTEM = {"db.system.name": "redis"}
+
+
+def _classify(error: BaseException) -> str | None:
+    # Both inherit ConnectionError, but retrying cannot fix invalid credentials.
+    if isinstance(error, AuthenticationError | AuthorizationError):
+        return None
+    if isinstance(error, RedisTimeoutError):
+        return "timeout"
+    if isinstance(error, RedisConnectionError):
+        return "connection_error"
+    return None
+
+
+class RedisClient:
+    def __init__(self, obs: Observability, redis: Redis, *, dependency: str = "redis") -> None:
+        self._obs = obs
+        self._redis = redis
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def from_url(
+        cls,
+        obs: Observability,
+        url: str,
+        *,
+        dependency: str = "redis",
+        timeout_seconds: float = 1.0,
+    ) -> RedisClient:
+        # redis-py's from_url is only partially typed.
+        redis: Redis = Redis.from_url(  # pyright: ignore[reportUnknownMemberType]
+            url, socket_timeout=timeout_seconds, socket_connect_timeout=timeout_seconds
+        )
+        return cls(obs, redis, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="db",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_classify,
+        )
+
+    async def get_json(self, key: str) -> Any:
+        """The decoded value, or None when the key is missing or expired."""
+        async with self._observed("get_json"):
+            raw = await self._redis.get(key)
+        return None if raw is None else json.loads(raw)
+
+    async def set_json(self, key: str, value: Any, *, ttl_seconds: int) -> None:
+        """Every value expires: there is no way to store one forever by mistake."""
+        if ttl_seconds < 1:
+            raise ValueError("ttl_seconds must be at least 1")
+        data = json.dumps(value, separators=(",", ":"))
+        async with self._observed("set_json"):
+            await self._redis.set(key, data, ex=ttl_seconds)
+
+    async def take_json(self, key: str) -> Any:
+        """Reads and deletes in one step (GETDEL): a second caller gets None."""
+        async with self._observed("take_json"):
+            raw = await cast(Awaitable[Any], self._redis.getdel(key))
+        return None if raw is None else json.loads(raw)
+
+    async def delete(self, key: str) -> None:
+        async with self._observed("delete"):
+            await self._redis.delete(key)
+
+    async def incr_window(self, key: str, *, by: int = 1, ttl_seconds: int) -> int:
+        """Adds `by` and returns the total; the key expires `ttl_seconds` after its first hit.
+
+        INCRBY and EXPIRE NX run in one transaction, so a crash between them cannot leave
+        a counter that never expires.
+        """
+        if ttl_seconds < 1:
+            raise ValueError("ttl_seconds must be at least 1")
+        async with self._observed("incr_window"), self._redis.pipeline(transaction=True) as pipe:
+            pipe.incrby(key, by)
+            pipe.expire(key, ttl_seconds, nx=True)
+            total, _ = await pipe.execute()
+        return int(total)
+
+    async def ping(self) -> bool:
+        """True when Redis answers; False (recorded as an error) when it does not."""
+        try:
+            async with self._observed("ping"):
+                # redis-py types ping() for both clients; the asyncio one returns an awaitable.
+                return bool(await self._redis.ping())  # pyright: ignore[reportUnknownMemberType]
+        except DependencyUnavailable:
+            return False
+
+    async def aclose(self) -> None:
+        await self._redis.aclose()

clients_021/s3.py

@@ -0,0 +1,164 @@
+"""S3 (or any S3-compatible store), observed: put, get, head, delete and presigned URLs.
+
+    from clients_021.s3 import S3Client
+
+    files = S3Client.create(obs, bucket="service-uploads", region="us-east-1")
+    await files.put("reports/2026-10.pdf", data, content_type="application/pdf")
+    data = await files.get("reports/2026-10.pdf")   # None when missing
+
+Needs the `aws` extra. Calls record `storage.client.operation.*` with `dependency` and
+`operation` (`put`, `get`, `head`, `delete`). A missing object is not an error: `get` and
+`head` return None. Timeouts, connection failures, throttling (`SlowDown`) and 5xx raise
+DependencyUnavailable; access denied or a missing bucket keep their botocore type.
+Presigning is local (no request), so it records nothing.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import boto3
+from botocore.exceptions import ClientError
+from observability_021 import Observability
+from observability_021.config import identifier
+
+from clients_021 import _aws
+from clients_021._observe import observed
+
+if TYPE_CHECKING:
+    from mypy_boto3_s3 import S3Client as Boto3S3Client
+else:
+    Boto3S3Client = Any
+
+SYSTEM = {"rpc.system": "aws-api", "rpc.service": "S3"}
+_MISSING = frozenset({"NoSuchKey", "404", "NotFound"})
+MAX_PRESIGN_SECONDS = 7 * 24 * 3600
+
+
+@dataclass(frozen=True)
+class ObjectInfo:
+    key: str
+    size: int
+    content_type: str | None
+    etag: str | None
+    last_modified: datetime | None
+
+
+class S3Client:
+    def __init__(
+        self, obs: Observability, client: Boto3S3Client, bucket: str, *, dependency: str = "s3"
+    ) -> None:
+        self._obs = obs
+        self._client = client
+        self.bucket = bucket
+        self.dependency = identifier(dependency)
+
+    @classmethod
+    def create(
+        cls,
+        obs: Observability,
+        bucket: str,
+        *,
+        region: str | None = None,
+        endpoint_url: str | None = None,
+        dependency: str = "s3",
+        timeout_seconds: float = 10.0,
+    ) -> S3Client:
+        client: Boto3S3Client = boto3.client(  # pyright: ignore[reportUnknownMemberType]
+            "s3",
+            region_name=region,
+            endpoint_url=endpoint_url,
+            config=_aws.config(
+                connect_seconds=min(timeout_seconds, 3.0), read_seconds=timeout_seconds
+            ),
+        )
+        return cls(obs, client, bucket, dependency=dependency)
+
+    def _observed(self, operation: str):  # noqa: ANN202 - an async context manager
+        return observed(
+            self._obs,
+            family="storage",
+            system=SYSTEM,
+            dependency=self.dependency,
+            operation=operation,
+            classify=_aws.classify,
+        )
+
+    async def put(
+        self, key: str, body: bytes, *, content_type: str = "application/octet-stream"
+    ) -> str | None:
+        """Stores the object and returns its ETag."""
+        async with self._observed("put"):
+            response = await asyncio.to_thread(
+                self._client.put_object,
+                Bucket=self.bucket,
+                Key=key,
+                Body=body,
+                ContentType=content_type,
+            )
+        return response.get("ETag")
+
+    async def get(self, key: str) -> bytes | None:
+        """The object's bytes, or None when it does not exist."""
+        async with self._observed("get"):
+            return await asyncio.to_thread(self._read, key)
+
+    def _read(self, key: str) -> bytes | None:
+        try:
+            response = self._client.get_object(Bucket=self.bucket, Key=key)
+        except ClientError as error:
+            if _aws.error_code(error) in _MISSING:
+                return None
+            raise
+        with response["Body"] as stream:
+            return stream.read()
+
+    async def head(self, key: str) -> ObjectInfo | None:
+        """The object's metadata, or None when it does not exist."""
+        async with self._observed("head"):
+            response = await asyncio.to_thread(self._head, key)
+        if response is None:
+            return None
+        return ObjectInfo(
+            key=key,
+            size=int(response.get("ContentLength", 0)),
+            content_type=response.get("ContentType"),
+            etag=response.get("ETag"),
+            last_modified=response.get("LastModified"),
+        )
+
+    def _head(self, key: str) -> dict[str, Any] | None:
+        try:
+            return dict(self._client.head_object(Bucket=self.bucket, Key=key))
+        except ClientError as error:
+            if _aws.error_code(error) in _MISSING:
+                return None
+            raise
+
+    async def delete(self, key: str) -> None:
+        """Deleting a missing object succeeds, as in S3."""
+        async with self._observed("delete"):
+            await asyncio.to_thread(self._client.delete_object, Bucket=self.bucket, Key=key)
+
+    async def aclose(self) -> None:
+        """Release the underlying SDK connection pools after in-flight calls finish."""
+        await asyncio.to_thread(self._client.close)
+
+    def presign_get(self, key: str, *, expires_seconds: int = 900) -> str:
+        return self._presign("get_object", key, expires_seconds, {})
+
+    def presign_put(self, key: str, *, content_type: str, expires_seconds: int = 900) -> str:
+        """The uploader must send the same Content-Type header."""
+        return self._presign("put_object", key, expires_seconds, {"ContentType": content_type})
+
+    def _presign(self, method: str, key: str, expires: int, extra: dict[str, str]) -> str:
+        if not 1 <= expires <= MAX_PRESIGN_SECONDS:
+            raise ValueError(f"expires_seconds must be between 1 and {MAX_PRESIGN_SECONDS}")
+        return self._client.generate_presigned_url(
+            method,
+            Params={"Bucket": self.bucket, "Key": key, **extra},
+            ExpiresIn=expires,
+        )