encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/json.py

@@ -0,0 +1,614 @@
+"""RedisJSON commands using Python JSON values.
+
+Values are serialized as JSON, including strings. Document replies are decoded
+into Python values; JSONPath queries preserve the server's arrays of matches.
+Requires a server with RedisJSON support.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from typing import Any
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface
+
+
+def _encode(value: Any) -> str:
+    """Serialize a Python value as compact JSON text.
+
+    Args:
+        value: A JSON-serializable value with finite numbers and no circular
+            references.
+
+    Returns:
+        JSON text with non-ASCII characters preserved.
+    """
+    return _json.dumps(
+        value, ensure_ascii=False, allow_nan=False, separators=(",", ":")
+    )
+
+
+def _decode(value: Any) -> Any:
+    """Decode JSON byte strings within a RedisJSON reply.
+
+    Args:
+        value: A byte string, a list of replies, or a scalar to preserve.
+
+    Returns:
+        Decoded Python JSON values. Lists are traversed recursively; other
+        values are unchanged.
+
+    Raises:
+        UnicodeDecodeError: JSON bytes use an invalid text encoding.
+        ValueError: A byte string is not valid JSON.
+    """
+    if isinstance(value, bytes):
+        return _json.loads(value)
+    if isinstance(value, list):
+        return [_decode(item) for item in value]
+    return value
+
+
+def _text(value: Any) -> Any:
+    """Decode text byte strings within a RedisJSON metadata reply.
+
+    Args:
+        value: A byte string, a list of replies, or a scalar to preserve.
+
+    Returns:
+        UTF-8-decoded strings. Lists are traversed recursively; other values are
+        unchanged.
+
+    Raises:
+        UnicodeDecodeError: A byte string is not valid UTF-8.
+    """
+    if isinstance(value, bytes):
+        return value.decode("utf-8")
+    if isinstance(value, list):
+        return [_text(item) for item in value]
+    return value
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def arrindex(
+        self,
+        key: str,
+        path: str,
+        value: Any,
+        *,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> Any:
+        """Find a JSON value within arrays selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            value: A Python JSON-serializable value; strings are encoded as JSON
+                strings, not treated as pre-encoded JSON. Numbers must be
+                finite, and values must not contain circular references.
+            start: The inclusive start index; negative indices count from the
+                end. Defaults to zero.
+            stop: The exclusive stop index; zero means through the end. Negative
+                indices count from the end. Requires start.
+
+        Returns:
+            For JSONPath, one index per match, -1 if not found, or None for a
+            non-array match. Legacy paths return a scalar index.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_arrindex(
+            key, path, _encode(value), start=start, stop=stop, source=active_ctx_bytes()
+        )
+
+    async def arrlen(self, key: str, *, path: str = "$") -> Any:
+        """Return the lengths of arrays selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, one length per match or None for a non-array match.
+            Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_arrlen(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def get(
+        self,
+        key: str,
+        *paths: str,
+        indent: str | None = None,
+        newline: str | None = None,
+        space: str | None = None,
+    ) -> Any:
+        """Return decoded JSON values selected by one or more paths.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            *paths: Paths to retrieve; omit for the root document.
+            indent: The indentation in the server's JSON text; formatting is
+                discarded when decoded into Python values.
+            newline: The newline text in the server response; formatting is
+                discarded when decoded into Python values.
+            space: The spacing in the server response; formatting is discarded
+                when decoded into Python values.
+
+        Returns:
+            Python JSON values, or None if the key is missing. A single JSONPath
+            returns a list of matches; multiple paths return a dictionary keyed
+            by path. With no paths, returns the root document.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            ValueError: The server response is not valid JSON.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _decode(
+            await self._get_handle().json_get(
+                key,
+                paths=paths or None,
+                indent=indent,
+                newline=newline,
+                space=space,
+                source=active_ctx_bytes(),
+            )
+        )
+
+    async def mget(self, key: str, *keys: str, path: str) -> Any:
+        """Return decoded JSON values from several keys in input order.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            One result per key, with None for missing keys or paths. JSONPath
+            results retain their lists of matches.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            ValueError: The server response is not valid JSON.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return _decode(
+            await self._get_handle().json_mget(keys, path, source=active_ctx_bytes())
+        )
+
+    async def objkeys(self, key: str, *, path: str = "$") -> Any:
+        """Return field names of JSON objects selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, one list of Python string field names per match or
+            None for a non-object match. Legacy paths return a single list of
+            names.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _text(
+            await self._get_handle().json_objkeys(
+                key, path=path, source=active_ctx_bytes()
+            )
+        )
+
+    async def objlen(self, key: str, *, path: str = "$") -> Any:
+        """Return the sizes of JSON objects selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, one field count per match or None for a non-object
+            match. Legacy paths return a scalar count.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_objlen(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def strlen(self, key: str, *, path: str = "$") -> Any:
+        """Return the lengths of JSON strings selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, one length per match or None for a non-string match.
+            Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_strlen(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def type(self, key: str, *, path: str = "$") -> Any:
+        """Return the JSON types of values selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, a list of Python string type names. Legacy paths
+            return a single type name, or None if the path is missing.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _text(
+            await self._get_handle().json_type(
+                key, path=path, source=active_ctx_bytes()
+            )
+        )
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def arrappend(self, key: str, path: str, value: Any, *values: Any) -> Any:
+        """Append Python JSON values to arrays selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            value: The first JSON value to append.
+                Numbers must be finite, and values must not contain circular
+                references.
+            *values: Additional JSON values with the same restrictions,
+                in order.
+
+        Returns:
+            For JSONPath, one resulting length per match or None for a non-array
+            match. Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        values = (value, *values)
+        return await self._get_handle().json_arrappend(
+            key, path, [_encode(value) for value in values], source=active_ctx_bytes()
+        )
+
+    async def arrinsert(
+        self, key: str, path: str, index: int, value: Any, *values: Any
+    ) -> Any:
+        """Insert Python JSON values into arrays selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            index: The zero-based index; negative values count from the end.
+            value: The first JSON value to insert.
+                Numbers must be finite, and values must not contain circular
+                references.
+            *values: Additional JSON values with the same restrictions,
+                in order.
+
+        Returns:
+            For JSONPath, one resulting length per match or None for a non-array
+            match. Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        values = (value, *values)
+        return await self._get_handle().json_arrinsert(
+            key,
+            path,
+            index,
+            [_encode(value) for value in values],
+            source=active_ctx_bytes(),
+        )
+
+    async def arrpop(self, key: str, *, path: str = "$", index: int = -1) -> Any:
+        """Remove and return elements from arrays selected by a path.
+
+        The command executes before the reply is decoded. A decoding error does
+        not undo changes to the stored document.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            index: The index to remove; -1 selects the last element.
+                Out-of-range indices are clamped to the nearest end.
+
+        Returns:
+            For JSONPath, one decoded Python value per match, or None for an
+            empty array or non-array match. Legacy paths return a single decoded
+            value.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            ValueError: The server response is not valid JSON.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _decode(
+            await self._get_handle().json_arrpop(
+                key, path=path, index=index, source=active_ctx_bytes()
+            )
+        )
+
+    async def arrtrim(self, key: str, path: str, start: int, stop: int) -> Any:
+        """Keep an inclusive range of elements in selected JSON arrays.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            start: The inclusive starting index; negative values count from the
+                end.
+            stop: The inclusive ending index; negative values count from the
+                end.
+
+        Returns:
+            For JSONPath, one resulting length per match or None for a non-array
+            match. Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_arrtrim(
+            key, path, start, stop, source=active_ctx_bytes()
+        )
+
+    async def clear(self, key: str, *, path: str = "$") -> Any:
+        """Empty selected containers and reset selected numbers to zero.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            The number of values changed; values already empty or zero are not
+            counted.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_clear(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def delete(self, key: str, *, path: str = "$") -> Any:
+        """Delete the JSON values selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            The number of values deleted, or zero if nothing matches.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_delete(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def forget(self, key: str, *, path: str = "$") -> Any:
+        """Delete selected JSON values, as an alias for delete.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            The number of values deleted, or zero if nothing matches.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_forget(
+            key, path=path, source=active_ctx_bytes()
+        )
+
+    async def merge(self, key: str, path: str, value: Any) -> Any:
+        """Apply a JSON Merge Patch to the values selected by a path.
+
+        Uses JSON Merge Patch semantics: object fields are merged, null fields
+        remove existing fields, and arrays or scalars replace the target value.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            value: A Python JSON-serializable value; strings are encoded as JSON
+                strings, not treated as pre-encoded JSON. Numbers must be
+                finite, and values must not contain circular references.
+
+        Returns:
+            b"OK" when the merge succeeds.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_merge(
+            key, path, _encode(value), source=active_ctx_bytes()
+        )
+
+    async def mset(
+        self, item: tuple[str, str, Any], *items: tuple[str, str, Any]
+    ) -> Any:
+        """Set multiple JSON values atomically.
+
+        Args:
+            item: The first (key, path, Python JSON value) tuple. Numbers must
+                be finite, and values must not contain circular references.
+            *items: Additional tuples of the same shape, in order.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().json_mset(
+            [(key, path, _encode(value)) for key, path, value in items],
+            source=active_ctx_bytes(),
+        )
+
+    async def numincrby(self, key: str, path: str, number: float) -> Any:
+        """Add a number to JSON numeric values selected by a path.
+
+        The command executes before the reply is decoded. A decoding error does
+        not undo changes to the stored document.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            number: The number used in the arithmetic operation.
+
+        Returns:
+            For JSONPath, a list of resulting numbers or None for non-numeric
+            matches. Legacy paths return a scalar number.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            ValueError: The server response is not valid JSON.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _decode(
+            await self._get_handle().json_numincrby(
+                key, path, number, source=active_ctx_bytes()
+            )
+        )
+
+    async def nummultby(self, key: str, path: str, number: float) -> Any:
+        """Multiply JSON numeric values selected by a path.
+
+        The command executes before the reply is decoded. A decoding error does
+        not undo changes to the stored document.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            number: The number used in the arithmetic operation.
+
+        Returns:
+            For JSONPath, a list of resulting numbers or None for non-numeric
+            matches. Legacy paths return a scalar number.
+
+        Raises:
+            UnicodeDecodeError: The server response uses an invalid text
+                encoding.
+            ValueError: The server response is not valid JSON.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return _decode(
+            await self._get_handle().json_nummultby(
+                key, path, number, source=active_ctx_bytes()
+            )
+        )
+
+    async def set(
+        self, key: str, path: str, value: Any, *, condition: str | None = None
+    ) -> Any:
+        """Set a JSON value, optionally requiring an existing or new path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            value: A Python JSON-serializable value; strings are encoded as JSON
+                strings, not treated as pre-encoded JSON. Numbers must be
+                finite, and values must not contain circular references.
+            condition: NX to set only a new path, XX to set only an existing
+                path, or None for no condition. Case-insensitive.
+
+        Returns:
+            b"OK" if the value was set, or None if the condition failed or the
+            server could not create the path.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_set(
+            key, path, _encode(value), condition=condition, source=active_ctx_bytes()
+        )
+
+    async def strappend(self, key: str, path: str, value: Any) -> Any:
+        """Append a Python string to JSON strings selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+            value: The Python string to append; it is JSON-encoded
+                automatically. Numbers must be finite, and values must not
+                contain circular references.
+
+        Returns:
+            For JSONPath, one resulting length per match or None for a
+            non-string match. Legacy paths return a scalar length.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_strappend(
+            key, path, _encode(value), source=active_ctx_bytes()
+        )
+
+    async def toggle(self, key: str, *, path: str = "$") -> Any:
+        """Invert JSON boolean values selected by a path.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            path: The JSONPath expression, or a legacy RedisJSON path. JSONPath
+                expressions start with "$" and can select multiple values.
+
+        Returns:
+            For JSONPath, a list of 0/1 results or None for non-boolean matches.
+            Legacy paths return a scalar 0 or 1, or None for a non-boolean
+            match.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().json_toggle(
+            key, path=path, source=active_ctx_bytes()
+        )