encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/stream.py

@@ -0,0 +1,773 @@
+"""Redis stream 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 Any, Optional
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface, TypedCommand
+from ._values import Value, encode, T, U
+from . import _responses
+
+
+class _XinfoStreamCommand(TypedCommand[T]):
+    """A callable XINFO_STREAM command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XinfoStreamCommand[U]:
+        """Select the value type for this command.
+
+        Use xinfo_stream[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 _XinfoStreamCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, *, full: bool = False, count: int | None = None
+    ) -> Any:
+        """Return stream metadata, optionally including entries and groups.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            full: Whether to include full entry, group, and consumer metadata.
+            count: The maximum entries returned with full=True; zero requests
+                all. Requires full=True.
+
+        Returns:
+            Alternating metadata names and values in RESP2, or a dictionary in
+            RESP3. Stored values in first-entry, last-entry, and entries are
+            decoded using T. Stream IDs, field names, counts, and group metadata
+            retain their existing types and structure.
+
+        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().stream_xinfo_stream(
+            key, full=full, count=count, source=active_ctx_bytes()
+        )
+        return _responses.stream_info(result, self._value_type)
+
+
+class _XrangeCommand(TypedCommand[T]):
+    """A callable XRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use xrange[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 _XrangeCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, start: str, end: str, *, count: int | None = None
+    ) -> Any:
+        """Return stream entries in ascending ID order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            start: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            end: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            count: The maximum number of results, or None for the server
+                default.
+
+        Returns:
+            Rows of [ID bytes, alternating field names and decoded values], or
+            an empty list when the range contains no entries.
+
+        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().stream_xrange(
+            key, start, end, count=count, source=active_ctx_bytes()
+        )
+        return _responses.entries(result, self._value_type)
+
+
+class _XreadCommand(TypedCommand[T]):
+    """A callable XREAD command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XreadCommand[U]:
+        """Select the value type for this command.
+
+        Use xread[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 _XreadCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        stream: tuple[str, str],
+        *streams: tuple[str, str],
+        count: int | None = None,
+        block_ms: int | None = None,
+    ) -> Any:
+        """Read stream entries with IDs greater than the supplied IDs.
+
+        Args:
+            stream: The first (stream key, last-seen ID) pair. Use "0-0" to
+                read from the beginning or "$" to wait for new entries. For
+                subsequent calls, use the last returned IDs.
+            *streams: Additional (stream key, last-seen ID) pairs, in order.
+            count: The maximum number of entries per stream; None uses server
+                behavior.
+            block_ms: The time to wait for entries in milliseconds; zero waits
+                indefinitely and None does not block.
+
+        Returns:
+            In RESP2, rows of [stream key bytes, entries], with each entry
+            represented as [ID bytes, alternating field names and decoded
+            values]. RESP3 uses a dictionary from stream keys to entries. Stream
+            keys exclude Encore prefixes. Returns None if no entries are
+            available or the blocking timeout expires.
+
+        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.
+        """
+        streams = (stream, *streams)
+        result = await self._get_handle().stream_xread(
+            streams, count=count, block_ms=block_ms, source=active_ctx_bytes()
+        )
+        return _responses.streams(result, self._value_type)
+
+
+class _XrevrangeCommand(TypedCommand[T]):
+    """A callable XREVRANGE command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XrevrangeCommand[U]:
+        """Select the value type for this command.
+
+        Use xrevrange[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 _XrevrangeCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self, key: str, end: str, start: str, *, count: int | None = None
+    ) -> Any:
+        """Return stream entries in descending ID order.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            end: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            start: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            count: The maximum number of results, or None for the server
+                default.
+
+        Returns:
+            Rows of [ID bytes, alternating field names and decoded values], or
+            an empty list when the range contains no entries.
+
+        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().stream_xrevrange(
+            key, end, start, count=count, source=active_ctx_bytes()
+        )
+        return _responses.entries(result, self._value_type)
+
+
+class _XautoclaimCommand(TypedCommand[T]):
+    """A callable XAUTOCLAIM command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XautoclaimCommand[U]:
+        """Select the value type for this command.
+
+        Use xautoclaim[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 _XautoclaimCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        group: str,
+        consumer: str,
+        min_idle_ms: int,
+        start: str,
+        *,
+        count: int | None = None,
+        justid: bool = False,
+    ) -> Any:
+        """Claim idle pending entries by scanning from a stream ID.
+
+        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.
+            group: The consumer-group name.
+            consumer: The consumer name within the group.
+            min_idle_ms: The minimum idle time in milliseconds before an entry
+                can be claimed.
+            start: The scan start ID; use "0-0" initially, then the next ID from
+                the previous result.
+            count: The maximum number of results, or None for the server
+                default.
+            justid: Whether to return only entry IDs and avoid incrementing
+                delivery counts.
+
+        Returns:
+            A list containing the next scan ID and claimed entries, plus deleted
+            pending IDs on Redis 7 and later. Entries are [ID bytes, alternating
+            field names and decoded values], or just ID bytes with justid=True.
+            A next ID of b"0-0" ends the scan.
+
+        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().stream_xautoclaim(
+            key,
+            group,
+            consumer,
+            min_idle_ms,
+            start,
+            count=count,
+            justid=justid,
+            source=active_ctx_bytes(),
+        )
+        return _responses.autoclaim(result, self._value_type, justid)
+
+
+class _XclaimCommand(TypedCommand[T]):
+    """A callable XCLAIM command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XclaimCommand[U]:
+        """Select the value type for this command.
+
+        Use xclaim[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 _XclaimCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        group: str,
+        consumer: str,
+        min_idle_ms: int,
+        id: str,
+        *ids: str,
+        idle_ms: int | None = None,
+        time_ms: int | None = None,
+        retrycount: int | None = None,
+        force: bool = False,
+        justid: bool = False,
+    ) -> Any:
+        """Transfer ownership of pending entries to a consumer.
+
+        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.
+            group: The consumer-group name.
+            consumer: The consumer name within the group.
+            min_idle_ms: The minimum idle time in milliseconds before an entry
+                can be claimed.
+            id: The first stream entry ID.
+            *ids: Additional stream entry IDs, in order.
+            idle_ms: The idle time to assign in milliseconds; incompatible with
+                time_ms.
+            time_ms: The last-delivery Unix timestamp in milliseconds;
+                incompatible with idle_ms.
+            retrycount: The delivery count to assign, or None to use Redis
+                behavior.
+            force: Whether to create pending records for existing stream entries
+                that are not already pending.
+            justid: Whether to return only entry IDs and avoid incrementing
+                delivery counts.
+
+        Returns:
+            Claimed [ID bytes, alternating field names and decoded values]
+            entries, or ID bytes with justid=True. Entries that cannot be
+            claimed are omitted.
+
+        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.
+        """
+        ids = (id, *ids)
+        result = await self._get_handle().stream_xclaim(
+            key,
+            group,
+            consumer,
+            min_idle_ms,
+            ids,
+            idle_ms=idle_ms,
+            time_ms=time_ms,
+            retrycount=retrycount,
+            force=force,
+            justid=justid,
+            source=active_ctx_bytes(),
+        )
+        return result if justid else _responses.entries(result, self._value_type)
+
+
+class _XreadgroupCommand(TypedCommand[T]):
+    """A callable XREADGROUP command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _XreadgroupCommand[U]:
+        """Select the value type for this command.
+
+        Use xreadgroup[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 _XreadgroupCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        group: str,
+        consumer: str,
+        stream: tuple[str, str],
+        *streams: tuple[str, str],
+        count: int | None = None,
+        block_ms: int | None = None,
+        noack: bool = False,
+    ) -> Any:
+        """Read stream entries as a consumer-group member.
+
+        Reading new entries advances the group and normally records pending
+        entries. Acknowledge processed entries with xack unless noack=True. When
+        reading pending entries, Redis ignores block_ms and noack.
+
+        Redis executes the command before its result is decoded. A decoding
+        error does not undo the command's effects.
+
+        Args:
+            group: The consumer-group name.
+            consumer: The consumer name within the group.
+            stream: The first (stream key, ID) pair. Use ">" for never-delivered
+                entries, or an ID such as "0-0" to read this consumer's pending
+                entries after that ID.
+            *streams: Additional (stream key, ID) pairs, in order.
+            count: The maximum number of entries per stream; None uses server
+                behavior.
+            block_ms: The time to wait for entries in milliseconds; zero waits
+                indefinitely and None does not block.
+            noack: Whether to skip pending-entry tracking for new messages; they
+                will not require xack.
+
+        Returns:
+            In RESP2, rows of [stream key bytes, entries], with entries
+            represented as [ID bytes, alternating field names and decoded
+            values]. RESP3 uses a dictionary from stream keys to entries.
+            Deleted pending entries can have None in place of their fields.
+            Stream keys exclude Encore prefixes. Returns None if no entries are
+            available or the blocking timeout expires.
+
+        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.
+        """
+        streams = (stream, *streams)
+        result = await self._get_handle().stream_xreadgroup(
+            group,
+            consumer,
+            streams,
+            count=count,
+            block_ms=block_ms,
+            noack=noack,
+            source=active_ctx_bytes(),
+        )
+        return _responses.streams(result, self._value_type)
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    @property
+    def xinfo_stream(self) -> _XinfoStreamCommand[bytes]:
+        """The callable XINFO_STREAM command.
+
+        Use xinfo_stream[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XinfoStreamCommand(self._get_handle, bytes)
+
+    async def xlen(self, key: str) -> int:
+        """Return the number of entries in a stream.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The entry count, or zero if the key is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().stream_xlen(key, source=active_ctx_bytes())
+
+    async def xpending(
+        self,
+        key: str,
+        group: str,
+        *,
+        start: str | None = None,
+        end: str | None = None,
+        count: int | None = None,
+        consumer: str | None = None,
+        idle_ms: int | None = None,
+    ) -> Any:
+        """Inspect entries delivered to a group but not yet acknowledged.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            group: The consumer-group name.
+            start: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            end: An inclusive stream ID bound; use "-" or "+" for an unbounded
+                end, or prefix an ID with "(" for an exclusive bound.
+            count: The maximum entries to return; supply together with start and
+                end.
+            consumer: Only include pending entries owned by this consumer;
+                requires start, end, and count.
+            idle_ms: Only include entries idle for at least this many
+                milliseconds; requires start, end, and count.
+
+        Returns:
+            Without a range, [total, smallest ID, largest ID, consumer counts].
+            With a range, rows of [ID, consumer, idle milliseconds, delivery
+            count]. IDs and consumer names are bytes; empty-summary ID fields
+            are None.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().stream_xpending(
+            key,
+            group,
+            start=start,
+            end=end,
+            count=count,
+            consumer=consumer,
+            idle_ms=idle_ms,
+            source=active_ctx_bytes(),
+        )
+
+    @property
+    def xrange(self) -> _XrangeCommand[bytes]:
+        """The callable XRANGE command.
+
+        Use xrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XrangeCommand(self._get_handle, bytes)
+
+    @property
+    def xread(self) -> _XreadCommand[bytes]:
+        """The callable XREAD command.
+
+        Use xread[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XreadCommand(self._get_handle, bytes)
+
+    @property
+    def xrevrange(self) -> _XrevrangeCommand[bytes]:
+        """The callable XREVRANGE command.
+
+        Use xrevrange[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XrevrangeCommand(self._get_handle, bytes)
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def xack(self, key: str, group: str, id: str, *ids: str) -> int:
+        """Acknowledge pending stream entries for a consumer group.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            group: The consumer-group name.
+            id: The first stream entry ID.
+            *ids: Additional stream entry IDs, in order.
+
+        Returns:
+            The number of entries removed from the group's pending list. Entries
+            remain in the stream.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        ids = (id, *ids)
+        return await self._get_handle().stream_xack(
+            key, group, ids, source=active_ctx_bytes()
+        )
+
+    async def xadd(
+        self,
+        key: str,
+        item: tuple[str, Value],
+        *items: tuple[str, Value],
+        id: str = "*",
+        nomkstream: bool = False,
+        maxlen: int | None = None,
+        minid: str | None = None,
+        approximate: bool = False,
+        limit: int | None = None,
+    ) -> Optional[bytes]:
+        """Append an entry to a stream and optionally trim older entries.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            item: The first (field name, value) pair.
+            *items: Additional tuples of the same shape, in order.
+            id: The new entry ID; "*" lets Redis generate one.
+            nomkstream: Whether to skip insertion when the stream does not
+                exist.
+            maxlen: The target maximum stream length; incompatible with minid.
+            minid: Trim entries with IDs below this threshold; incompatible with
+                maxlen.
+            approximate: Whether to trim in efficient chunks, potentially
+                retaining extra entries. Requires maxlen or minid.
+            limit: The maximum entries to examine while trimming; zero means
+                unlimited. Requires approximate=True and a trimming threshold.
+
+        Returns:
+            The new entry ID as bytes, or None if nomkstream=True and the stream
+            does not exist.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().stream_xadd(
+            key,
+            [(field, encode(value)) for field, value in items],
+            id=id,
+            nomkstream=nomkstream,
+            maxlen=maxlen,
+            minid=minid,
+            approximate=approximate,
+            limit=limit,
+            source=active_ctx_bytes(),
+        )
+
+    @property
+    def xautoclaim(self) -> _XautoclaimCommand[bytes]:
+        """The callable XAUTOCLAIM command.
+
+        Use xautoclaim[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XautoclaimCommand(self._get_handle, bytes)
+
+    @property
+    def xclaim(self) -> _XclaimCommand[bytes]:
+        """The callable XCLAIM command.
+
+        Use xclaim[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XclaimCommand(self._get_handle, bytes)
+
+    async def xdel(self, key: str, id: str, *ids: str) -> int:
+        """Delete entries from a stream by ID.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            id: The first stream entry ID.
+            *ids: Additional stream entry IDs, in order.
+
+        Returns:
+            The number of entries deleted; missing IDs are ignored.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        ids = (id, *ids)
+        return await self._get_handle().stream_xdel(key, ids, source=active_ctx_bytes())
+
+    async def xgroup_create(
+        self,
+        key: str,
+        group: str,
+        *,
+        id: str = "$",
+        mkstream: bool = False,
+        entries_read: int | None = None,
+    ) -> None:
+        """Create a consumer group on a stream.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            group: The consumer-group name.
+            id: The last-delivered ID for the group. "$" starts after existing
+                entries; "0-0" includes existing entries.
+            mkstream: Whether to create an empty stream if it does not exist.
+            entries_read: The group's logical read counter for lag tracking, or
+                None to let Redis choose it.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().stream_xgroup_create(
+            key,
+            group,
+            id=id,
+            mkstream=mkstream,
+            entries_read=entries_read,
+            source=active_ctx_bytes(),
+        )
+
+    async def xgroup_destroy(self, key: str, group: str) -> bool:
+        """Delete a consumer group and its pending-entry tracking.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            group: The consumer-group name.
+
+        Returns:
+            True if the group existed and was removed, otherwise False. The
+            stream's entries are retained.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().stream_xgroup_destroy(
+            key, group, source=active_ctx_bytes()
+        )
+
+    @property
+    def xreadgroup(self) -> _XreadgroupCommand[bytes]:
+        """The callable XREADGROUP command.
+
+        Use xreadgroup[T](...) to select the decoded value type. Plain calls
+        keep stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _XreadgroupCommand(self._get_handle, bytes)
+
+    async def xtrim(
+        self,
+        key: str,
+        *,
+        maxlen: int | None = None,
+        minid: str | None = None,
+        approximate: bool = False,
+        limit: int | None = None,
+    ) -> int:
+        """Remove stream entries older than a trimming threshold.
+
+        Supply exactly one of maxlen and minid.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            maxlen: The target maximum stream length; incompatible with minid.
+            minid: Trim entries with IDs below this threshold; incompatible with
+                maxlen.
+            approximate: Whether to trim in efficient chunks, potentially
+                retaining extra entries. Requires maxlen or minid.
+            limit: The maximum entries to examine while trimming; zero means
+                unlimited. Requires approximate=True and a trimming threshold.
+
+        Returns:
+            The number of entries removed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().stream_xtrim(
+            key,
+            maxlen=maxlen,
+            minid=minid,
+            approximate=approximate,
+            limit=limit,
+            source=active_ctx_bytes(),
+        )