encore-dev 2.0.0a7__py3-none-any.whl

encore/storage/redis/geo.py

@@ -0,0 +1,508 @@
+"""Redis geo 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 _GeosearchCommand(TypedCommand[T]):
+    """A callable GEOSEARCH command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GeosearchCommand[U]:
+        """Select the value type for this command.
+
+        Use geosearch[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 _GeosearchCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        *,
+        member: Value | None = None,
+        longitude: float | None = None,
+        latitude: float | None = None,
+        radius: float | None = None,
+        width: float | None = None,
+        height: float | None = None,
+        unit: str = "m",
+        count: int | None = None,
+        any: bool = False,
+        order: str | None = None,
+        withcoord: bool = False,
+        withdist: bool = False,
+        withhash: bool = False,
+    ) -> Any:
+        """Find geospatial members inside a circle or rectangle.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to use as the center, instead of longitude and
+                latitude.
+            longitude: The center longitude in degrees; supply together with
+                latitude instead of member.
+            latitude: The center latitude in degrees; supply together with
+                longitude instead of member.
+            radius: The circle radius in the selected unit, instead of width and
+                height.
+            width: The box width in the selected unit; supply with height
+                instead of radius.
+            height: The box height in the selected unit; supply with width
+                instead of radius.
+            unit: The case-insensitive distance unit: m, km, mi, or ft.
+            count: The maximum number of results, or None for the server
+                default.
+            any: Whether to stop after finding count matches, without
+                guaranteeing the nearest matches. Requires count.
+            order: ASC for nearest first or DESC for farthest first,
+                case-insensitively; None leaves results unordered.
+            withcoord: Whether to include [longitude, latitude] coordinates in
+                each row.
+            withdist: Whether to include distance from the search center in each
+                row.
+            withhash: Whether to include the integer geospatial hash in each
+                row.
+
+        Returns:
+            A list of decoded members, or rows containing a member followed by
+            requested distance, hash, and coordinates in that order. Distances
+            and coordinates are bytes in RESP2 or floats in RESP3; hashes are
+            integers.
+
+        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().geo_geosearch(
+            key,
+            member=None if member is None else encode(member),
+            longitude=longitude,
+            latitude=latitude,
+            radius=radius,
+            width=width,
+            height=height,
+            unit=unit,
+            count=count,
+            any=any,
+            order=order,
+            withcoord=withcoord,
+            withdist=withdist,
+            withhash=withhash,
+            source=active_ctx_bytes(),
+        )
+        return _responses.geo_members(result, self._value_type)
+
+
+class _GeoradiusCommand(TypedCommand[T]):
+    """A callable GEORADIUS command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GeoradiusCommand[U]:
+        """Select the value type for this command.
+
+        Use georadius[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 _GeoradiusCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        longitude: float,
+        latitude: float,
+        radius: float,
+        *,
+        unit: str = "m",
+        count: int | None = None,
+        any: bool = False,
+        order: str | None = None,
+        withcoord: bool = False,
+        withdist: bool = False,
+        withhash: bool = False,
+        store: str | None = None,
+        storedist: str | None = None,
+    ) -> Any:
+        """Find geospatial members within a radius of coordinates.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            longitude: The longitude in degrees, between -180 and 180.
+            latitude: The latitude in degrees, between approximately
+                -85.05112878 and 85.05112878.
+            radius: The search radius in the selected unit.
+            unit: The case-insensitive distance unit: m, km, mi, or ft.
+            count: The maximum number of results, or None for the server
+                default.
+            any: Whether to stop after finding count matches, without
+                guaranteeing the nearest matches. Requires count.
+            order: ASC for nearest first or DESC for farthest first,
+                case-insensitively; None leaves results unordered.
+            withcoord: Whether to include [longitude, latitude] coordinates in
+                each row.
+            withdist: Whether to include distance from the search center in each
+                row.
+            withhash: Whether to include the integer geospatial hash in each
+                row.
+            store: A destination key for results with geospatial scores.
+                Incompatible with storedist and reply options.
+            storedist: A destination key for results scored by distance in the
+                selected unit. Incompatible with store and reply options.
+
+        Returns:
+            A list of decoded members, or rows containing a member followed by
+            requested distance, hash, and coordinates in that order. Distances
+            and coordinates are bytes in RESP2 or floats in RESP3; hashes are
+            integers. With store or storedist, the number of members stored.
+
+        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().geo_georadius(
+            key,
+            longitude,
+            latitude,
+            radius,
+            unit=unit,
+            count=count,
+            any=any,
+            order=order,
+            withcoord=withcoord,
+            withdist=withdist,
+            withhash=withhash,
+            store=store,
+            storedist=storedist,
+            source=active_ctx_bytes(),
+        )
+        return _responses.geo_members(result, self._value_type)
+
+
+class _GeoradiusbymemberCommand(TypedCommand[T]):
+    """A callable GEORADIUSBYMEMBER command with selectable value decoding."""
+
+    def __getitem__(self, value_type: type[U]) -> _GeoradiusbymemberCommand[U]:
+        """Select the value type for this command.
+
+        Use georadiusbymember[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 _GeoradiusbymemberCommand(self._get_handle, value_type)
+
+    async def __call__(
+        self,
+        key: str,
+        member: Value,
+        radius: float,
+        *,
+        unit: str = "m",
+        count: int | None = None,
+        any: bool = False,
+        order: str | None = None,
+        withcoord: bool = False,
+        withdist: bool = False,
+        withhash: bool = False,
+        store: str | None = None,
+        storedist: str | None = None,
+    ) -> Any:
+        """Find geospatial members within a radius of another member.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member: The member to encode.
+            radius: The search radius in the selected unit.
+            unit: The case-insensitive distance unit: m, km, mi, or ft.
+            count: The maximum number of results, or None for the server
+                default.
+            any: Whether to stop after finding count matches, without
+                guaranteeing the nearest matches. Requires count.
+            order: ASC for nearest first or DESC for farthest first,
+                case-insensitively; None leaves results unordered.
+            withcoord: Whether to include [longitude, latitude] coordinates in
+                each row.
+            withdist: Whether to include distance from the search center in each
+                row.
+            withhash: Whether to include the integer geospatial hash in each
+                row.
+            store: A destination key for results with geospatial scores.
+                Incompatible with storedist and reply options.
+            storedist: A destination key for results scored by distance in the
+                selected unit. Incompatible with store and reply options.
+
+        Returns:
+            A list of decoded members, or rows containing a member followed by
+            requested distance, hash, and coordinates in that order. Distances
+            and coordinates are bytes in RESP2 or floats in RESP3; hashes are
+            integers. With store or storedist, the number of members stored.
+
+        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().geo_georadiusbymember(
+            key,
+            encode(member),
+            radius,
+            unit=unit,
+            count=count,
+            any=any,
+            order=order,
+            withcoord=withcoord,
+            withdist=withdist,
+            withhash=withhash,
+            store=store,
+            storedist=storedist,
+            source=active_ctx_bytes(),
+        )
+        return _responses.geo_members(result, self._value_type)
+
+
+class ReadOnlyInterface(CommandInterface):
+    """Commands available through a read-only database handle."""
+
+    async def geodist(
+        self, key: str, member1: Value, member2: Value, *, unit: str = "m"
+    ) -> Optional[float]:
+        """Return the distance between two geospatial members.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            member1: The first member to encode.
+            member2: The second member to encode.
+            unit: The case-insensitive distance unit: m, km, mi, or ft.
+
+        Returns:
+            The distance in the requested unit, or None if either member is
+            missing.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().geo_geodist(
+            key, encode(member1), encode(member2), unit=unit, source=active_ctx_bytes()
+        )
+
+    async def geohash(self, key: str, *members: Value) -> list[Optional[bytes]]:
+        """Return geohash strings for geospatial members.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            *members: Members to encode; may be empty.
+
+        Returns:
+            One geohash as bytes per member, with None for missing members.
+            Returns an empty list if no members are supplied.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().geo_geohash(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    async def geopos(self, key: str, *members: Value) -> Any:
+        """Return coordinates for geospatial members.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            *members: Members to encode; may be empty.
+
+        Returns:
+            One [longitude, latitude] pair per member, or None for missing
+            members. Coordinates retain their raw reply type: bytes in RESP2 or
+            floats in RESP3. Returns an empty list if no members are supplied.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().geo_geopos(
+            key, [encode(value) for value in members], source=active_ctx_bytes()
+        )
+
+    @property
+    def geosearch(self) -> _GeosearchCommand[bytes]:
+        """The callable GEOSEARCH command.
+
+        Use geosearch[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GeosearchCommand(self._get_handle, bytes)
+
+
+class Interface(ReadOnlyInterface):
+    """Read and write commands."""
+
+    async def geoadd(
+        self,
+        key: str,
+        item: tuple[float, float, Value],
+        *items: tuple[float, float, Value],
+        nx: bool = False,
+        xx: bool = False,
+        ch: bool = False,
+    ) -> int:
+        """Add geospatial members or update their coordinates.
+
+        Args:
+            key: The database key, without an Encore key prefix.
+            item: The first (longitude, latitude, member) tuple. Coordinates
+                are in degrees; longitude must be within [-180, 180] and
+                latitude within approximately [-85.05112878, 85.05112878].
+            *items: Additional tuples of the same shape, in order.
+            nx: Only add new entries; mutually exclusive with xx.
+            xx: Only update existing entries; mutually exclusive with nx.
+            ch: Whether to count changed existing members as well as new
+                members.
+
+        Returns:
+            The number of new members, or added and changed members when
+            ch=True.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        items = (item, *items)
+        return await self._get_handle().geo_geoadd(
+            key,
+            [
+                (longitude, latitude, encode(member))
+                for longitude, latitude, member in items
+            ],
+            nx=nx,
+            xx=xx,
+            ch=ch,
+            source=active_ctx_bytes(),
+        )
+
+    @property
+    def georadius(self) -> _GeoradiusCommand[bytes]:
+        """The callable GEORADIUS command.
+
+        Use georadius[T](...) to select the decoded value type. Plain calls keep
+        stored values as bytes; keys and command metadata are unchanged.
+        """
+        return _GeoradiusCommand(self._get_handle, bytes)
+
+    @property
+    def georadiusbymember(self) -> _GeoradiusbymemberCommand[bytes]:
+        """The callable GEORADIUSBYMEMBER command.
+
+        Use georadiusbymember[T](...) to select the decoded value type. Plain
+        calls keep stored values as bytes; keys and command metadata are
+        unchanged.
+        """
+        return _GeoradiusbymemberCommand(self._get_handle, bytes)
+
+    async def geosearchstore(
+        self,
+        destination: str,
+        key: str,
+        *,
+        member: Value | None = None,
+        longitude: float | None = None,
+        latitude: float | None = None,
+        radius: float | None = None,
+        width: float | None = None,
+        height: float | None = None,
+        unit: str = "m",
+        count: int | None = None,
+        any: bool = False,
+        order: str | None = None,
+        storedist: bool = False,
+    ) -> int:
+        """Store geospatial search results in a destination sorted set.
+
+        Args:
+            destination: The destination key, without an Encore key prefix.
+            key: The database key, without an Encore key prefix.
+            member: The member to use as the center, instead of longitude and
+                latitude.
+            longitude: The center longitude in degrees; supply together with
+                latitude instead of member.
+            latitude: The center latitude in degrees; supply together with
+                longitude instead of member.
+            radius: The circle radius in the selected unit, instead of width and
+                height.
+            width: The box width in the selected unit; supply with height
+                instead of radius.
+            height: The box height in the selected unit; supply with width
+                instead of radius.
+            unit: The case-insensitive distance unit: m, km, mi, or ft.
+            count: The maximum number of results, or None for the server
+                default.
+            any: Whether to stop after finding count matches, without
+                guaranteeing the nearest matches. Requires count.
+            order: ASC for nearest first or DESC for farthest first,
+                case-insensitively; None leaves results unordered.
+            storedist: Whether to store distances as scores instead of
+                geospatial hashes.
+
+        Returns:
+            The number of members stored, replacing the destination's previous
+            value.
+
+        Raises:
+            EncoreError: Redis rejects the command or the request fails.
+        """
+        return await self._get_handle().geo_geosearchstore(
+            destination,
+            key,
+            member=None if member is None else encode(member),
+            longitude=longitude,
+            latitude=latitude,
+            radius=radius,
+            width=width,
+            height=height,
+            unit=unit,
+            count=count,
+            any=any,
+            order=order,
+            storedist=storedist,
+            source=active_ctx_bytes(),
+        )