encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/string.py

@@ -0,0 +1,654 @@
+"""Redis string commands.
+
+Keys are strings without Encore prefixes. Values accept bytes, str, int, float,
+or
+RedisValue implementations; value reads default to bytes. Use command[T](...) to
+decode values as T. Custom encoding and decoding errors propagate to the caller.
+Repeated arguments are variadic. Individual commands document their reply
+shapes and any option-dependent behavior.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import U, T, Value, encode, decode, decode_optional
+from typing import overload, Literal
+
+
+class _GetCommand(TypedCommand[T]):
+    """A callable GET command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GetCommand[U]:
+        """Select the value type for this command.
+
+        Use get[T](...) to decode stored values as T. Selecting a type does not
+        open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _GetCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str) -> Optional[T]:
+        """Return the string value stored at a key.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The decoded value, or None if the key does not exist.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().string_get(key, source=active_ctx_bytes())
+        return decode_optional(result, self._value_type)
+
+
+class _GetrangeCommand(TypedCommand[T]):
+    """A callable GETRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GetrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use getrange[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _GetrangeCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, start: int, end: int) -> T:
+        """Return a range of bytes from a string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            start: The inclusive starting index; negative values count from the
+                end.
+            end: The inclusive ending index; negative values count from the end.
+
+        Returns:
+            The selected bytes decoded using the command's type argument.
+            Missing keys yield an empty byte range before decoding. Indices
+            always refer to bytes.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().string_getrange(
+            key, start, end, source=active_ctx_bytes()
+        )
+        return decode(result, self._value_type)
+
+
+class _MgetCommand(TypedCommand[T]):
+    """A callable MGET command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _MgetCommand[U]:
+        """Select the value type for this command.
+
+        Use mget[T](...) to decode stored values as T. Selecting a type does not
+        open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _MgetCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str, *keys: str) -> list[Optional[T]]:
+        """Return string values in the requested key order.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            One value per key, with None for missing keys or non-string values.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        result = await self._get_handle().string_mget(keys, source=active_ctx_bytes())
+        return [decode_optional(value, self._value_type) for value in result]
+
+
+class _GetdelCommand(TypedCommand[T]):
+    """A callable GETDEL command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GetdelCommand[U]:
+        """Select the value type for this command.
+
+        Use getdel[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _GetdelCommand(self._get_handle, value_type)
+
+    async def __call__(self, key: str) -> Optional[T]:
+        """Return a string value and delete its key atomically.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The decoded previous value, or None if the key does not exist.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().string_getdel(key, source=active_ctx_bytes())
+        return decode_optional(result, self._value_type)
+
+
+class _GetexCommand(TypedCommand[T]):
+    """A callable GETEX command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GetexCommand[U]:
+        """Select the value type for this command.
+
+        Use getex[T](...) to decode stored values as T. Selecting a type does
+        not open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _GetexCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        *,
+        ex: int | None = None,
+        px: int | None = None,
+        exat: int | None = None,
+        pxat: int | None = None,
+        persist: bool = False,
+    ) -> Optional[T]:
+        """Return a string value and optionally change its expiry.
+
+        With no expiry option, the current expiration is unchanged.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            ex: The lifetime in seconds; mutually exclusive with other expiry
+                options.
+            px: The lifetime in milliseconds; mutually exclusive with other
+                expiry options.
+            exat: The expiration time in Unix seconds; mutually exclusive with
+                other expiry options.
+            pxat: The expiration time in Unix milliseconds; mutually exclusive
+                with other expiry options.
+            persist: Whether to remove the expiry; mutually exclusive with
+                expiry options.
+
+        Returns:
+            The decoded value, or None if the key does not exist.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        result = await self._get_handle().string_getex(
+            key,
+            ex=ex,
+            px=px,
+            exat=exat,
+            pxat=pxat,
+            persist=persist,
+            source=active_ctx_bytes(),
+        )
+        return decode_optional(result, self._value_type)
+
+
+class _SetCommand(TypedCommand[T]):
+    """A callable SET command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _SetCommand[U]:
+        """Select the value type for this command.
+
+        Use set[T](...) to decode stored values as T. Selecting a type does not
+        open a connection or change the decoder of an existing command.
+
+        Args:
+            value_type: bytes, str, int, float, or a class implementing
+                RedisValue.
+
+        Returns:
+            An independent command with the same arguments and the selected
+            decoder. Keys and other command metadata retain their existing
+            types.
+        """
+        return _SetCommand(self._get_handle, value_type)
+
+    @overload
+    async def __call__(
+        self,
+        key: str,
+        value: Value,
+        *,
+        ex: int | None = None,
+        px: int | None = None,
+        exat: int | None = None,
+        pxat: int | None = None,
+        keepttl: bool = False,
+        nx: bool = False,
+        xx: bool = False,
+        get: Literal[True],
+    ) -> Optional[T]: ...
+
+    @overload
+    async def __call__(
+        self,
+        key: str,
+        value: Value,
+        *,
+        ex: int | None = None,
+        px: int | None = None,
+        exat: int | None = None,
+        pxat: int | None = None,
+        keepttl: bool = False,
+        nx: bool = False,
+        xx: bool = False,
+        get: bool = False,
+    ) -> T | bytes | None: ...
+
+    async def __call__(
+        self,
+        key: str,
+        value: Value,
+        *,
+        ex: int | None = None,
+        px: int | None = None,
+        exat: int | None = None,
+        pxat: int | None = None,
+        keepttl: bool = False,
+        nx: bool = False,
+        xx: bool = False,
+        get: bool = False,
+    ) -> T | bytes | None:
+        """Set a string value, optionally checking existence or setting expiry.
+
+        Without an expiry option or keepttl=True, a successful write removes any
+        existing expiry. A non-bytes type argument requires get=True;
+        conditional-write status replies remain bytes.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The value to encode and store.
+            ex: The lifetime in seconds; mutually exclusive with other expiry
+                options.
+            px: The lifetime in milliseconds; mutually exclusive with other
+                expiry options.
+            exat: The expiration time in Unix seconds; mutually exclusive with
+                other expiry options.
+            pxat: The expiration time in Unix milliseconds; mutually exclusive
+                with other expiry options.
+            keepttl: Whether to retain the existing expiry; mutually exclusive
+                with explicit expiry options.
+            nx: Only set the value if the key is missing; incompatible with xx.
+            xx: Only set the value if the key exists; incompatible with nx.
+            get: Whether to return the previous string value.
+
+        Returns:
+            With get=True, the previous string value or None if missing, even
+            when an existence condition prevents the write. Otherwise, b"OK" for
+            a successful conditional write, None for a failed condition, and
+            None for an unconditional write.
+
+        Raises:
+            UnicodeDecodeError: A value is not valid UTF-8 when the type
+                argument is str.
+            ValueError: A stored value cannot be parsed as int or float.
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        if self._value_type is not bytes and not get:
+            raise ValueError("A non-bytes type argument requires get=True for SET")
+        result = await self._get_handle().string_set(
+            key,
+            encode(value),
+            ex=ex,
+            px=px,
+            exat=exat,
+            pxat=pxat,
+            keepttl=keepttl,
+            nx=nx,
+            xx=xx,
+            get=get,
+            source=active_ctx_bytes(),
+        )
+        return decode_optional(result, self._value_type) if get else result
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    @property
+    def get(self) -> _GetCommand[bytes]:
+        """The callable GET command.
+
+        Use get[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GetCommand(self._get_handle, bytes)
+
+    @property
+    def getrange(self) -> _GetrangeCommand[bytes]:
+        """The callable GETRANGE command.
+
+        Use getrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GetrangeCommand(self._get_handle, bytes)
+
+    @property
+    def mget(self) -> _MgetCommand[bytes]:
+        """The callable MGET command.
+
+        Use mget[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _MgetCommand(self._get_handle, bytes)
+
+    async def strlen(self, key: str) -> int:
+        """Return the length of a stored string in bytes.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The byte length, or zero if the key does not exist.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_strlen(key, source=active_ctx_bytes())
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def append(self, key: str, value: Value) -> int:
+        """Append bytes to a string, creating it if needed.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The value to encode and store.
+
+        Returns:
+            The resulting string length in bytes.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_append(
+            key, encode(value), source=active_ctx_bytes()
+        )
+
+    async def decr(self, key: str) -> int:
+        """Subtract one from an integer string, starting from zero if missing.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The integer value after the decrement.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_decr(key, source=active_ctx_bytes())
+
+    async def decrby(self, key: str, amount: int) -> int:
+        """Subtract an amount from an integer string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            amount: The amount to subtract; negative values add.
+
+        Returns:
+            The integer value after the decrement; a missing key starts at zero.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_decrby(
+            key, amount, source=active_ctx_bytes()
+        )
+
+    @property
+    def getdel(self) -> _GetdelCommand[bytes]:
+        """The callable GETDEL command.
+
+        Use getdel[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GetdelCommand(self._get_handle, bytes)
+
+    @property
+    def getex(self) -> _GetexCommand[bytes]:
+        """The callable GETEX command.
+
+        Use getex[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GetexCommand(self._get_handle, bytes)
+
+    async def incr(self, key: str) -> int:
+        """Add one to an integer string, starting from zero if missing.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The integer value after the increment.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_incr(key, source=active_ctx_bytes())
+
+    async def incrby(self, key: str, amount: int) -> int:
+        """Add an amount to an integer string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            amount: The amount to add; negative values subtract.
+
+        Returns:
+            The integer value after the increment; a missing key starts at zero.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_incrby(
+            key, amount, source=active_ctx_bytes()
+        )
+
+    async def incrbyfloat(self, key: str, amount: float) -> float:
+        """Add an amount to a numeric string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            amount: The amount to add; negative values subtract.
+
+        Returns:
+            The numeric value after the increment; a missing key starts at zero.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_incrbyfloat(
+            key, amount, source=active_ctx_bytes()
+        )
+
+    async def mset(self, item: tuple[str, Value], *items: tuple[str, Value]) -> None:
+        """Set multiple string values atomically, replacing existing values.
+
+        Args:
+            item: The first (key, value) pair.
+            *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().string_mset(
+            [(field, encode(value)) for field, value in items],
+            source=active_ctx_bytes(),
+        )
+
+    async def msetnx(self, item: tuple[str, Value], *items: tuple[str, Value]) -> bool:
+        """Set multiple string values only if none of the keys exist.
+
+        Args:
+            item: The first (key, value) pair.
+            *items: Additional tuples of the same shape, in order.
+
+        Returns:
+            True if all values were set; False if any key exists and nothing
+            changed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().string_msetnx(
+            [(field, encode(value)) for field, value in items],
+            source=active_ctx_bytes(),
+        )
+
+    async def psetex(self, key: str, milliseconds: int, value: Value) -> None:
+        """Set a string value with a lifetime in milliseconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            milliseconds: The positive lifetime in milliseconds.
+            value: The value to encode and store.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_psetex(
+            key, milliseconds, encode(value), source=active_ctx_bytes()
+        )
+
+    @property
+    def set(self) -> _SetCommand[bytes]:
+        """The callable SET command.
+
+        Use set[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        Selecting a non-bytes type requires get=True and decodes the previous
+        value.
+        """
+        return _SetCommand(self._get_handle, bytes)
+
+    async def setex(self, key: str, seconds: int, value: Value) -> None:
+        """Set a string value with a lifetime in seconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            seconds: The positive lifetime in seconds.
+            value: The value to encode and store.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_setex(
+            key, seconds, encode(value), source=active_ctx_bytes()
+        )
+
+    async def setnx(self, key: str, value: Value) -> bool:
+        """Set a string value only if the key does not exist.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            value: The value to encode and store.
+
+        Returns:
+            True if the value was set; False if the key already exists.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_setnx(
+            key, encode(value), source=active_ctx_bytes()
+        )
+
+    async def setrange(self, key: str, offset: int, value: Value) -> int:
+        """Overwrite bytes starting at an offset, padding gaps with zero bytes.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            offset: The nonnegative byte offset at which to begin writing.
+            value: The value to encode and store.
+
+        Returns:
+            The resulting string length in bytes.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().string_setrange(
+            key, offset, encode(value), source=active_ctx_bytes()
+        )

encore/tracing/__init__.py

@@ -0,0 +1,19 @@
+"""OpenTelemetry tracing recorded by the Encore runtime.
+
+Importing encore installs the tracer provider and W3C propagator as the
+OpenTelemetry globals.
+
+Typical usage example:
+
+    from opentelemetry import trace
+
+    tracer = trace.get_tracer(__name__)
+
+    async def get_user(user_id: int):
+        with tracer.start_as_current_span("load user"):
+            return await db.query("SELECT * FROM users WHERE id = $1", user_id).one()
+
+HTTP and framework tracing comes from the standard
+``opentelemetry-instrumentation-*`` packages, e.g.
+``FastAPIInstrumentor().instrument_app(app)``.
+"""

encore/tracing/_context.py

@@ -0,0 +1,27 @@
+"""Span contexts as the runtime's 25-byte buffers."""
+
+from __future__ import annotations
+
+from opentelemetry import context as context_api
+from opentelemetry import trace
+
+from ._encode import ctx_bytes
+from ._span import Span
+
+
+def span_ctx_bytes(span: trace.Span) -> bytes | None:
+    """The 25-byte context of ``span``; ``None`` when invalid."""
+    if isinstance(span, Span):
+        return span.ctx_bytes
+    sc = span.get_span_context()
+    return ctx_bytes(sc) if sc.is_valid else None
+
+
+def active_ctx_bytes(context: context_api.Context | None = None) -> bytes | None:
+    """Return the active span context as 25 bytes, or None if invalid.
+
+    Args:
+        context: The OpenTelemetry context to inspect, or None to use the
+            current context.
+    """
+    return span_ctx_bytes(trace.get_current_span(context))