codex-platform 0.1.0__py3-none-any.whl

codex_platform/redis_service/operations/string.py

@@ -0,0 +1,318 @@
+"""
+codex_platform.redis_service.operations.string
+===============================================
+Redis String/Key operations.
+"""
+
+import logging
+from typing import Any
+
+from redis.asyncio import Redis
+
+from codex_platform.redis_service.base import catch_redis_errors
+from codex_platform.redis_service.keys import BaseRedisKey, resolve_key
+
+log = logging.getLogger(__name__)
+
+
+class StringOperations:
+    """Redis String and key-level operations (SET / GET / EXPIRE / TTL and more).
+
+    Accepts an already-constructed ``redis.asyncio.Redis`` client.
+    All methods wrap Redis errors in typed exceptions.
+
+    Example::
+
+        ops = StringOperations(client)
+        await ops.set("session:abc", "token-value", ttl=3600)
+        token = await ops.get("session:abc")
+    """
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    @catch_redis_errors
+    async def set(self, key: "str | BaseRedisKey", value: str, ttl: int | None = None, **kwargs: Any) -> None:
+        """Set a string value (SET).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            value: String value to store.
+            ttl: Expiry in seconds. ``None`` means no expiry.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        await self.client.set(real_key, value, ex=ttl)
+
+    @catch_redis_errors
+    async def setnx(self, key: "str | BaseRedisKey", value: str, ttl: int | None = None, **kwargs: Any) -> bool:
+        """Set a value only if the key does not exist (SET NX).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            value: String value to store.
+            ttl: Expiry in seconds. ``None`` means no expiry.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            ``True`` if the value was set, ``False`` if the key already existed.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return bool(await self.client.set(real_key, value, ex=ttl, nx=True))
+
+    @catch_redis_errors
+    async def get(self, key: "str | BaseRedisKey", **kwargs: Any) -> str | None:
+        """Retrieve a string value (GET).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            String value, or ``None`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        val = await self.client.get(real_key)
+        return str(val) if val is not None else None
+
+    @catch_redis_errors
+    async def getset(self, key: "str | BaseRedisKey", value: str, **kwargs: Any) -> str | None:
+        """Atomically set a new value and return the previous one (GETSET).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            value: New value to store.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Previous value, or ``None`` if the key did not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        val = await self.client.getset(real_key, value)
+        return str(val) if val is not None else None
+
+    @catch_redis_errors
+    async def mget(self, *keys: str) -> list[str | None]:
+        """Retrieve values for multiple keys in a single request (MGET).
+
+        Args:
+            *keys: Redis key strings.
+
+        Returns:
+            List of values in the same order as ``keys``.
+            ``None`` for keys that do not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        values = await self.client.mget(list(keys))
+        return [str(v) if v is not None else None for v in values]
+
+    @catch_redis_errors
+    async def mset(self, mapping: dict[str, str]) -> None:
+        """Set values for multiple keys in a single call (MSET).
+
+        Args:
+            mapping: Dict of ``{key: value}`` pairs to write.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        await self.client.mset(mapping)
+
+    @catch_redis_errors
+    async def incr(self, key: "str | BaseRedisKey", **kwargs: Any) -> int:
+        """Increment a numeric value by 1 (INCR).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New value after incrementing.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.incr(real_key))
+
+    @catch_redis_errors
+    async def incrby(self, key: "str | BaseRedisKey", amount: int, **kwargs: Any) -> int:
+        """Increment a numeric value by a given amount (INCRBY).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            amount: Increment step.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New value after incrementing.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.incrby(real_key, amount))
+
+    @catch_redis_errors
+    async def append(self, key: "str | BaseRedisKey", value: str, **kwargs: Any) -> int:
+        """Append a string to an existing value (APPEND).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            value: String to append.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New total length of the value after appending.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.append(real_key, value))
+
+    @catch_redis_errors
+    async def delete(self, key: "str | BaseRedisKey", **kwargs: Any) -> None:
+        """Delete a key (DEL).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        await self.client.delete(real_key)
+
+    @catch_redis_errors
+    async def delete_by_pattern(self, pattern: str) -> int:
+        """Delete all keys matching a glob pattern (SCAN + DEL).
+
+        Args:
+            pattern: Glob pattern, e.g. ``"session:*"``.
+
+        Returns:
+            Number of keys deleted.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        keys = [k async for k in self.client.scan_iter(match=pattern)]
+        if not keys:
+            return 0
+        return int(await self.client.delete(*keys))
+
+    @catch_redis_errors
+    async def expire(self, key: "str | BaseRedisKey", ttl: int, **kwargs: Any) -> bool:
+        """Set a TTL (expiry) on a key in seconds (EXPIRE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            ttl: Time-to-live in seconds.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            ``True`` if the TTL was set, ``False`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return bool(await self.client.expire(real_key, ttl))
+
+    @catch_redis_errors
+    async def ttl(self, key: "str | BaseRedisKey", **kwargs: Any) -> int:
+        """Return the remaining TTL of a key in seconds (TTL).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Remaining TTL in seconds. ``-1`` if no TTL is set, ``-2`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.ttl(real_key))
+
+    @catch_redis_errors
+    async def exists(self, key: "str | BaseRedisKey", **kwargs: Any) -> bool:
+        """Check whether a key exists (EXISTS).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            ``True`` if the key exists, ``False`` otherwise.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return bool(await self.client.exists(real_key))
+
+    @catch_redis_errors
+    async def rename(self, key: "str | BaseRedisKey", new_key: str, **kwargs: Any) -> None:
+        """Rename a key (RENAME).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            new_key: Target key name.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        await self.client.rename(real_key, new_key)
+
+    @catch_redis_errors
+    async def key_type(self, key: "str | BaseRedisKey", **kwargs: Any) -> str:
+        """Return the data type stored at a key (TYPE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            One of: ``"string"``, ``"list"``, ``"set"``, ``"zset"``, ``"hash"``, ``"stream"``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return await self.client.type(real_key)

codex_platform/redis_service/operations/zset.py

@@ -0,0 +1,277 @@
+"""
+codex_platform.redis_service.operations.zset
+=============================================
+Redis Sorted Set (ZSet) operations.
+
+A Sorted Set is a set where every member has an associated float score.
+Use it for leaderboards, priority queues, and time-based event indexes.
+"""
+
+import logging
+from typing import Any
+
+from redis.asyncio import Redis
+
+from codex_platform.redis_service.base import catch_redis_errors
+from codex_platform.redis_service.keys import BaseRedisKey, resolve_key
+
+log = logging.getLogger(__name__)
+
+
+class ZSetOperations:
+    """Redis Sorted Set operations (ZADD / ZRANGE / ZRANGEBYSCORE / ZREM and more).
+
+    Accepts an already-constructed ``redis.asyncio.Redis`` client.
+    All methods wrap Redis errors in typed exceptions.
+
+    Example::
+
+        ops = ZSetOperations(client)
+        await ops.add("leaderboard", {"alice": 1500.0, "bob": 1200.0})
+        top = await ops.range("leaderboard", 0, 9, reverse=True, with_scores=True)
+    """
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    @catch_redis_errors
+    async def add(self, key: "str | BaseRedisKey", mapping: dict[str, float], **kwargs: Any) -> int:
+        """Add members with scores to a sorted set (ZADD).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            mapping: Dict of ``{member: score}`` pairs.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of new members added (existing members with updated scores are not counted).
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zadd(real_key, mapping))
+
+    @catch_redis_errors
+    async def score(self, key: "str | BaseRedisKey", member: str, **kwargs: Any) -> float | None:
+        """Return the score of a member in a sorted set (ZSCORE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            member: Member name.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Float score of the member, or ``None`` if the member does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        val = await self.client.zscore(real_key, member)
+        return float(val) if val is not None else None
+
+    @catch_redis_errors
+    async def rank(self, key: "str | BaseRedisKey", member: str, reverse: bool = False, **kwargs: Any) -> int | None:
+        """Return the rank (position) of a member in a sorted set (ZRANK / ZREVRANK).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            member: Member name.
+            reverse: If ``True``, use ZREVRANK (rank by descending score). Defaults to ``False``.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Zero-based rank of the member, or ``None`` if the member does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        fn = self.client.zrevrank if reverse else self.client.zrank
+        result = await fn(real_key, member)
+        return int(result) if result is not None else None
+
+    @catch_redis_errors
+    async def range(
+        self,
+        key: "str | BaseRedisKey",
+        start: int = 0,
+        end: int = -1,
+        reverse: bool = False,
+        with_scores: bool = False,
+        **kwargs: Any,
+    ) -> list[str] | list[tuple[str, float]]:
+        """Return a range of members by rank (ZRANGE / ZREVRANGE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            start: Start rank (0-based).
+            end: End rank inclusive. ``-1`` means the last member.
+            reverse: If ``True``, return members in descending score order (ZREVRANGE).
+            with_scores: If ``True``, return ``[(member, score), ...]`` tuples.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            List of member strings, or list of ``(member, score)`` tuples if ``with_scores=True``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        if reverse:
+            result = await self.client.zrevrange(real_key, start, end, withscores=with_scores)
+        else:
+            result = await self.client.zrange(real_key, start, end, withscores=with_scores)
+        return result
+
+    @catch_redis_errors
+    async def range_by_score(
+        self,
+        key: "str | BaseRedisKey",
+        min_score: float,
+        max_score: float,
+        with_scores: bool = False,
+        **kwargs: Any,
+    ) -> list[str] | list[tuple[str, float]]:
+        """Return members within a score range (ZRANGEBYSCORE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            min_score: Minimum score (inclusive).
+            max_score: Maximum score (inclusive).
+            with_scores: If ``True``, return ``[(member, score), ...]`` tuples.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            List of member strings, or list of ``(member, score)`` tuples if ``with_scores=True``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return await self.client.zrangebyscore(real_key, min_score, max_score, withscores=with_scores)
+
+    @catch_redis_errors
+    async def remove(self, key: "str | BaseRedisKey", *members: str, **kwargs: Any) -> int:
+        """Remove one or more members from a sorted set (ZREM).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            *members: Member names to remove.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members actually removed.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zrem(real_key, *members))
+
+    @catch_redis_errors
+    async def card(self, key: "str | BaseRedisKey", **kwargs: Any) -> int:
+        """Return the number of members in a sorted set (ZCARD).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members. ``0`` if the key does not exist.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zcard(real_key))
+
+    @catch_redis_errors
+    async def increment(self, key: "str | BaseRedisKey", member: str, amount: float = 1.0, **kwargs: Any) -> float:
+        """Increment the score of a member by the given amount (ZINCRBY).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            member: Member name.
+            amount: Increment value. Defaults to ``1.0``.
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            New score of the member after incrementing.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return float(await self.client.zincrby(real_key, amount, member))
+
+    @catch_redis_errors
+    async def count(self, key: "str | BaseRedisKey", min_score: float, max_score: float, **kwargs: Any) -> int:
+        """Count members within a score range (ZCOUNT).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            min_score: Minimum score (inclusive).
+            max_score: Maximum score (inclusive).
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members with score in ``[min_score, max_score]``.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zcount(real_key, min_score, max_score))
+
+    @catch_redis_errors
+    async def remove_by_rank(self, key: "str | BaseRedisKey", start: int, end: int, **kwargs: Any) -> int:
+        """Remove members by rank range (ZREMRANGEBYRANK).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            start: Start rank (inclusive, 0-based).
+            end: End rank (inclusive).
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members removed.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zremrangebyrank(real_key, start, end))
+
+    @catch_redis_errors
+    async def remove_by_score(
+        self, key: "str | BaseRedisKey", min_score: float, max_score: float, **kwargs: Any
+    ) -> int:
+        """Remove members within a score range (ZREMRANGEBYSCORE).
+
+        Args:
+            key: Redis key or a ``BaseRedisKey`` instance.
+            min_score: Minimum score (inclusive).
+            max_score: Maximum score (inclusive).
+            **kwargs: Extra parameters forwarded to ``resolve_key``.
+
+        Returns:
+            Number of members removed.
+
+        Raises:
+            RedisConnectionError: Redis connection failure.
+            RedisServiceError: Redis operation failure.
+        """
+        real_key = resolve_key(key, **kwargs)
+        return int(await self.client.zremrangebyscore(real_key, min_score, max_score))

codex_platform/redis_service/service.py

@@ -0,0 +1,80 @@
+"""
+codex_platform.redis_service.service
+=====================================
+Full Redis service via composition.
+
+Usage::
+
+    from redis.asyncio import Redis
+    from codex_platform.redis_service import RedisService
+
+    redis_client = Redis(host="localhost", port=6379)
+    service = RedisService(redis_client)
+
+    await service.hash.set_json("u:42", "profile", data)
+    await service.string.set("session:abc", "token", ttl=3600)
+
+    # JSON as plain string (no server modules required):
+    await service.json.set("user:42", {"name": "Alice"}, ttl=3600)
+    user = await service.json.get("user:42")
+
+    # JSON via RedisJSON module (requires server module):
+    await service.json_module.set("user:42", "$", {"name": "Alice"})
+    name = await service.json_module.get("user:42", "$.name")
+
+For selective composition use operations directly::
+
+    from codex_platform.redis_service.operations import HashOperations, StringOperations
+
+    class MyService:
+        def __init__(self, client: Redis):
+            self.hash = HashOperations(client)
+            self.string = StringOperations(client)
+"""
+
+from redis.asyncio import Redis
+
+from .operations import (
+    HashOperations,
+    JsonModuleOperations,
+    JsonStringOperations,
+    ListOperations,
+    PipelineOperations,
+    SetOperations,
+    StringOperations,
+    ZSetOperations,
+)
+
+
+class RedisService:
+    """Unified Redis service — all data-type operations in one place.
+
+    Suitable for projects that need access to multiple Redis data types through
+    a single entry point.  For selective composition, instantiate individual
+    ``Operations`` classes directly.
+
+    Attributes:
+        hash: Hash operations (HSET / HGET / HGETALL …).
+        string: String and key-level operations (SET / GET / EXPIRE …).
+        list: List operations (RPUSH / LPOP / LRANGE …).
+        set: Set operations (SADD / SREM / SMEMBERS …).
+        zset: Sorted-set operations (ZADD / ZRANGE / ZRANK …).
+        json: JSON stored as Redis strings — works with any Redis instance.
+        json_module: JSON via the server-side RedisJSON module (requires RedisJSON).
+        pipeline: Pipeline / transaction helpers.
+    """
+
+    def __init__(self, client: Redis) -> None:
+        """Initialize the service with an existing async Redis client.
+
+        Args:
+            client: An already-constructed ``redis.asyncio.Redis`` instance.
+        """
+        self.hash = HashOperations(client)
+        self.string = StringOperations(client)
+        self.list = ListOperations(client)
+        self.set = SetOperations(client)
+        self.zset = ZSetOperations(client)
+        self.json = JsonStringOperations(client)
+        self.json_module = JsonModuleOperations(client)
+        self.pipeline = PipelineOperations(client)