encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/bitmap.py

@@ -0,0 +1,142 @@
+"""Redis commands for bits stored in binary strings.
+
+Keys are strings without Encore prefixes. Bit offsets are zero-based. Range
+commands describe whether their offsets address bytes or individual bits; these
+commands do not decode stored values.
+"""
+
+from __future__ import annotations
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def bitcount(
+        self,
+        key: str,
+        *,
+        start: int | None = None,
+        end: int | None = None,
+        unit: str | None = None,
+    ) -> int:
+        """Count set bits in a string or an inclusive range.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            start: The inclusive start in the selected unit; negative offsets
+                count from the end.
+            end: The inclusive end in the selected unit; negative offsets count
+                from the end. Supply start and end together.
+            unit: BYTE (default) or BIT, case-insensitively. Requires start and
+                end.
+
+        Returns:
+            The number of bits equal to one; zero for a missing key.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().bitmap_bitcount(
+            key, start=start, end=end, unit=unit, source=active_ctx_bytes()
+        )
+
+    async def bitpos(
+        self,
+        key: str,
+        bit: bool,
+        *,
+        start: int | None = None,
+        end: int | None = None,
+        unit: str | None = None,
+    ) -> int:
+        """Find the first occurrence of a bit in a string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            bit: The bit to find: False for zero or True for one.
+            start: The inclusive start in the selected unit; negative offsets
+                count from the end.
+            end: The inclusive end in the selected unit; negative offsets count
+                from the end. Requires start.
+            unit: BYTE (default) or BIT, case-insensitively. Requires start and
+                end.
+
+        Returns:
+            The absolute bit offset, or -1 if no matching bit is found. When
+            searching for zero without an explicit end, Redis treats the string
+            as padded with zero bits.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().bitmap_bitpos(
+            key, bit, start=start, end=end, unit=unit, source=active_ctx_bytes()
+        )
+
+    async def getbit(self, key: str, offset: int) -> int:
+        """Read a bit at an offset in a string.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            offset: The nonnegative bit offset, with zero denoting the most
+                significant bit of the first byte.
+
+        Returns:
+            Zero or one; missing keys and offsets beyond the string read as
+            zero.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().bitmap_getbit(
+            key, offset, source=active_ctx_bytes()
+        )
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def bitop(
+        self, operation: str, destination: str, key: str, *keys: str
+    ) -> int:
+        """Store the result of a bitwise operation on source strings.
+
+        Args:
+            operation: The case-insensitive operation: AND, OR, XOR, or NOT. NOT
+                requires exactly one source key.
+            destination: The destination key, without an Encore key prefix.
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The byte length of the stored result.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().bitmap_bitop(
+            operation, destination, keys, source=active_ctx_bytes()
+        )
+
+    async def setbit(self, key: str, offset: int, value: bool) -> int:
+        """Set a bit, extending the string with zero bytes if needed.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            offset: The nonnegative bit offset, with zero denoting the most
+                significant bit of the first byte.
+            value: The new bit: False for zero or True for one.
+
+        Returns:
+            The previous bit value, either zero or one.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().bitmap_setbit(
+            key, offset, value, source=active_ctx_bytes()
+        )

encore/storage/redis/generic.py

@@ -0,0 +1,367 @@
+"""Redis commands for keys, expiration, and database scans.
+
+Key arguments are strings without Encore prefixes. SCAN returns unprefixed key
+names as bytes. These commands do not decode stored values.
+"""
+
+from __future__ import annotations
+
+from ...tracing._context import active_ctx_bytes
+from ._base import CommandInterface
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def exists(self, key: str, *keys: str) -> int:
+        """Count the supplied keys that exist.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The number of existing keys, counting repeated keys separately.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().generic_exists(keys, source=active_ctx_bytes())
+
+    async def expiretime(self, key: str) -> int:
+        """Return a key's expiration time in Unix seconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The timestamp, -1 if the key has no expiry, or -2 if it is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_expiretime(
+            key, source=active_ctx_bytes()
+        )
+
+    async def pexpiretime(self, key: str) -> int:
+        """Return a key's expiration time in Unix milliseconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The timestamp, -1 if the key has no expiry, or -2 if it is missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_pexpiretime(
+            key, source=active_ctx_bytes()
+        )
+
+    async def pttl(self, key: str) -> int:
+        """Return the remaining lifetime of a key in milliseconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The remaining milliseconds, -1 for no expiry, or -2 for a missing
+            key.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_pttl(key, source=active_ctx_bytes())
+
+    async def scan(
+        self,
+        cursor: int,
+        *,
+        pattern: str | None = None,
+        count: int | None = None,
+        key_type: str | None = None,
+    ) -> tuple[int, list[bytes]]:
+        """Read a batch of keys using a scan cursor.
+
+        Continue with the returned cursor until it is zero. Scans may return
+        duplicates and do not provide a snapshot while data changes.
+
+        Args:
+            cursor: Zero to start an iteration, or the cursor from the previous
+                call.
+            pattern: A Redis glob pattern to filter results, or None for no
+                filter.
+            count: A hint for work per call, not a result limit; None uses the
+                server default.
+            key_type: An optional Redis type name, such as "string" or "hash".
+
+        Returns:
+            A tuple (cursor, keys), where cursor is the next scan cursor and
+            keys is a list of unprefixed byte key names. A zero cursor ends the
+            iteration; an empty batch does not.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_scan(
+            cursor,
+            pattern=pattern,
+            count=count,
+            key_type=key_type,
+            source=active_ctx_bytes(),
+        )
+
+    async def touch(self, key: str, *keys: str) -> int:
+        """Update the last-access time of existing keys.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The number of existing keys that were touched.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().generic_touch(keys, source=active_ctx_bytes())
+
+    async def ttl(self, key: str) -> int:
+        """Return the remaining lifetime of a key in seconds.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The remaining seconds, -1 for no expiry, or -2 for a missing key.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_ttl(key, source=active_ctx_bytes())
+
+    async def type(self, key: str) -> str:
+        """Return the Redis data type stored at a key.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            The type name, such as "string" or "hash", or "none" for a missing
+            key.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_type(key, source=active_ctx_bytes())
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def copy(self, key: str, destination: str, *, replace: bool = False) -> bool:
+        """Copy a value to another key in the same database.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            destination: The destination key, without an Encore key prefix.
+            replace: Whether to overwrite an existing destination.
+
+        Returns:
+            True if the value was copied; False if the source is missing or an
+            existing destination was not replaced.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_copy(
+            key, destination, replace=replace, source=active_ctx_bytes()
+        )
+
+    async def delete(self, key: str, *keys: str) -> int:
+        """Delete keys and free their values synchronously.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The number of keys removed; missing keys are ignored.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().generic_delete(keys, source=active_ctx_bytes())
+
+    async def expire(
+        self, key: str, seconds: int, *, condition: str | None = None
+    ) -> bool:
+        """Set a key's remaining lifetime in seconds.
+
+        A nonpositive lifetime or expiration time in the past deletes the key
+        when the condition permits the operation.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            seconds: The lifetime in seconds.
+            condition: An optional case-insensitive condition: NX for no current
+                expiry, XX for an existing expiry, GT for a later expiry, or LT
+                for an earlier expiry.
+
+        Returns:
+            True if the timeout was applied; False if the key is missing or the
+            condition failed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_expire(
+            key, seconds, condition=condition, source=active_ctx_bytes()
+        )
+
+    async def expireat(
+        self, key: str, timestamp: int, *, condition: str | None = None
+    ) -> bool:
+        """Set a key's expiration time using Unix seconds.
+
+        A nonpositive lifetime or expiration time in the past deletes the key
+        when the condition permits the operation.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            timestamp: The expiration time in seconds since the Unix epoch.
+            condition: An optional case-insensitive condition: NX for no current
+                expiry, XX for an existing expiry, GT for a later expiry, or LT
+                for an earlier expiry.
+
+        Returns:
+            True if the timeout was applied; False if the key is missing or the
+            condition failed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_expireat(
+            key, timestamp, condition=condition, source=active_ctx_bytes()
+        )
+
+    async def persist(self, key: str) -> bool:
+        """Remove a key's expiration time.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+
+        Returns:
+            True if an expiry was removed; False if the key is missing or has no
+            expiry.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_persist(key, source=active_ctx_bytes())
+
+    async def pexpire(
+        self, key: str, milliseconds: int, *, condition: str | None = None
+    ) -> bool:
+        """Set a key's remaining lifetime in milliseconds.
+
+        A nonpositive lifetime or expiration time in the past deletes the key
+        when the condition permits the operation.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            milliseconds: The lifetime in milliseconds.
+            condition: An optional case-insensitive condition: NX for no current
+                expiry, XX for an existing expiry, GT for a later expiry, or LT
+                for an earlier expiry.
+
+        Returns:
+            True if the timeout was applied; False if the key is missing or the
+            condition failed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_pexpire(
+            key, milliseconds, condition=condition, source=active_ctx_bytes()
+        )
+
+    async def pexpireat(
+        self, key: str, timestamp: int, *, condition: str | None = None
+    ) -> bool:
+        """Set a key's expiration time using Unix milliseconds.
+
+        A nonpositive lifetime or expiration time in the past deletes the key
+        when the condition permits the operation.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            timestamp: The expiration time in milliseconds since the Unix epoch.
+            condition: An optional case-insensitive condition: NX for no current
+                expiry, XX for an existing expiry, GT for a later expiry, or LT
+                for an earlier expiry.
+
+        Returns:
+            True if the timeout was applied; False if the key is missing or the
+            condition failed.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().generic_pexpireat(
+            key, timestamp, condition=condition, source=active_ctx_bytes()
+        )
+
+    async def rename(self, key: str, destination: str) -> None:
+        """Rename a key, replacing any existing destination.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            destination: The destination key, without an Encore key prefix.
+
+        Raises:
+            EncoreError: The source key does not exist, or Redis rejects the
+                command or the request fails.
+        """
+        return await self._get_handle().generic_rename(
+            key, destination, source=active_ctx_bytes()
+        )
+
+    async def renamenx(self, key: str, destination: str) -> bool:
+        """Rename a key only if the destination does not exist.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            destination: The destination key, without an Encore key prefix.
+
+        Returns:
+            True if renamed; False if the destination already exists.
+
+        Raises:
+            EncoreError: The source key does not exist, or Redis rejects the
+                command or the request fails.
+        """
+        return await self._get_handle().generic_renamenx(
+            key, destination, source=active_ctx_bytes()
+        )
+
+    async def unlink(self, key: str, *keys: str) -> int:
+        """Remove keys and reclaim their memory asynchronously.
+
+        Args:
+            key: The first database key, without an Encore prefix.
+            *keys: Additional database keys, without Encore prefixes.
+
+        Returns:
+            The number of keys removed; missing keys are ignored.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        keys = (key, *keys)
+        return await self._get_handle().generic_unlink(keys, source=active_ctx_bytes())