GitHub

API reference for redis.

A Redis client as a service (Effect's effect/persistence/Redis)::

redis = yield from Redis()
yield from redis.send("SET", "greeting", "hello")
greeting = yield from redis.send("GET", "greeting")       # "hello"

incr = script(lambda key, by: [key, by], lua="return redis.call('INCRBY', KEYS[1], ARGV[1])",
              number_of_keys=1, decode=int)
total = yield from redis.eval(incr)("counter", 5)

Redis sends commands on shared connections, runs script\ s with EVALSHA (loading each once), delivers a channel's messages through subscribe and lends a connection of its own for blocking commands with reserve. make builds the service over any client; pyfect.persistence.redis_py (the pyfect-dev[redis] extra) provides it on redis-py.

Values

AttributeTypeDescription
DEFAULT_SUBSCRIBE_CAPACITYLiteral[1024]

How many messages a subscribe dequeue holds untaken by default.

Types

TypeDefinitionDescription
RedisReplytype RedisReply = str | int | list[RedisReply] | None

What a command answers, as the client decodes it: a bulk or status reply is a str, an integer an int, nil None, an array a list.

Subscribetype Subscribe = Callable[[str, Callable[[RedisMessage], bool]], Effect[Effect[None, RedisError], RedisError, Scope]]

subscribe(channel, on_message): subscribes until the scope closes and gives the effect that delivers its messages to on_message (on the fiber running it) until the subscription fails, or until on_message gives False (the subscriber fell behind): then it stops reading, and the effect ends.

Classes

Functions

make

make(*, send, subscribe, connect, pool=None) -> Effect[RedisService, Never, Scope]

The Redis service over a client: send runs commands on its shared connections, connect opens a connection for reserve (pooled by pool), and subscribe subscribes to a channel. Scripts are loaded with SCRIPT LOAD through send once each; the connections still open are closed with the scope.

ParameterTypeDescription
sendSend
subscribeSubscribe
connectEffect[OpenConnection, RedisError]
poolPoolOptions | None = None

Returns Effect[RedisService, Never, Scope]

def make(
    *,
    send: Send,
    subscribe: Subscribe,
    connect: Effect[OpenConnection, RedisError],
    pool: PoolOptions | None = None,
) -> Effect[RedisService, Never, Scope]:
    """The ``Redis`` service over a client: ``send`` runs commands on its
    shared connections, ``connect`` opens a connection for ``reserve``
    (pooled by ``pool``), and ``subscribe`` subscribes to a channel.
    Scripts are loaded with ``SCRIPT LOAD`` through ``send`` once each;
    the connections still open are closed with the scope."""
    require_effect(connect, "connect")
    options = pool or PoolOptions()

    def build() -> Generator[Effect[Any, Any, Any], Any, RedisService]:
        def load(script: Script[..., Any]) -> Effect[str, RedisError]:
            return send("SCRIPT", "LOAD", script.lua).map(str)

        scripts: Cache[Script[..., Any], str, RedisError] = yield from Cache.make(
            load, capacity=None, time_to_live=_kept_while_loaded
        )

        # Closing a connection fails its command still running, which ends
        # its reservation; the pool waits for reservations when it shuts
        # down, so connections are closed before it does.
        connections: set[_Pooled] = set()

        def opened(connection: OpenConnection) -> _Pooled:
            return _Pooled(connection, connections)

        connection_pool: Pool[_Pooled, RedisError] = yield from Pool.make_with_ttl(
            acquire_release(connect.map(opened), lambda pooled, _exit: pooled.close),
            min=options.min_connections,
            max=options.max_connections,
            concurrency=1,
            time_to_live=options.idle_timeout,
        )
        yield from add_finalizer(
            lambda _: for_each(list(connections), lambda pooled: pooled.close).as_void()
        )

        get = connection_pool.get()
        if options.acquire_timeout is not None:
            get = get.timeout_or_else(
                from_input_unsafe(options.acquire_timeout),
                lambda: fail(
                    RedisError(
                        cause=TimeoutError("Timed out waiting for a reserved Redis connection")
                    )
                ),
            )
        reserved_get = get

        def reserve() -> Generator[Effect[Any, Any, Any], Any, RedisConnection]:
            pooled = yield from reserved_get
            yield from add_finalizer(
                lambda _: (
                    void
                    if pooled.healthy and pooled.active == 0
                    else connection_pool.invalidate(pooled)
                )
            )

            def send_reserved(command: str, *args: str) -> Effect[RedisReply, RedisError]:
                def run() -> Effect[RedisReply, RedisError]:
                    pooled.active += 1

                    def settle(ex: Exit[RedisReply, RedisError]) -> Effect[None]:
                        pooled.active -= 1
                        if isinstance(ex, Failure):
                            pooled.healthy = False
                        return void

                    return pooled.send(command, *args).on_exit(settle)

                return suspend(run)

            return _Connection(send_reserved, scripts)

        return _Redis(send, scripts, subscribe, gen(reserve))

    return gen(build)

script

script[**P](params: Callable[P, Sequence[str | float]], *, lua: str, number_of_keys: int | Callable[P, int]) -> Script[P, RedisReply]
script[**P, A](params: Callable[P, Sequence[str | float]], *, lua: str, number_of_keys: int | Callable[P, int], decode: Callable[[RedisReply], A]) -> Script[P, A]

A script whose keys and arguments params gives from its call's arguments; the first number_of_keys of them (a count, or a function of the arguments) are keys. decode reads the reply into the script's result (Effect's withReturnType); a raise there is a defect.

ParameterTypeDescription
params
lua
number_of_keys
decode= _raw
@overload
def script[**P](
    params: Callable[P, Sequence[str | float]],
    *,
    lua: str,
    number_of_keys: int | Callable[P, int],
) -> Script[P, RedisReply]: ...
@overload
def script[**P, A](
    params: Callable[P, Sequence[str | float]],
    *,
    lua: str,
    number_of_keys: int | Callable[P, int],
    decode: Callable[[RedisReply], A],
) -> Script[P, A]: ...
def script[**P](
    params: Callable[P, Sequence[str | float]],
    *,
    lua: str,
    number_of_keys: int | Callable[P, int],
    decode: Callable[[RedisReply], Any] = _raw,
) -> Script[P, Any]:
    """A script whose keys and arguments ``params`` gives from its call's
    arguments; the first ``number_of_keys`` of them (a count, or a function
    of the arguments) are keys. ``decode`` reads the reply into the
    script's result (Effect's ``withReturnType``); a raise there is a
    defect."""
    if isinstance(number_of_keys, int):
        count = number_of_keys

        def keys(*_args: P.args, **_kwargs: P.kwargs) -> int:
            return count

        return Script(lua, params, keys, decode)
    return Script(lua, params, number_of_keys, decode)