Valkey Py

https://github.com/valkey-io/valkey-py
Admin
Python client library for Valkey, a high-performance key-value store forked from Redis.
Tokens:425,374
Snippets:2,888
Trust Score:9.3
License:MIT
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Install the package

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry/README.md

Installs the package from the current directory, which includes the example dependencies.

```shell
pip install .
```

--------------------------------

### Set up virtual environment and install dev dependencies

Source: https://github.com/valkey-io/valkey-py/blob/main/CONTRIBUTING.md

These commands create a virtual environment, activate it, and install the development dependencies from the dev group. They are part of the setup steps for contributing to valkey-py.

```bash
python -m venv .venv
```

```bash
source .venv/bin/activate
```

```bash
pip install --group dev
```

--------------------------------

### Basic Valkey connection and set/get example

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Connects to localhost on port 6379, sets a value, and retrieves it. Responses are returned as bytes; set decode_responses=True to get strings.

```python
import valkey
r = valkey.Valkey(host='localhost', port=6379, db=0)
r.set('foo', 'bar')
# True
r.get('foo')
# b'bar'
```

--------------------------------

### Connect to Sentinel and use master_for

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/asyncio_examples.ipynb

Creates a Sentinel client with a list of Sentinel addresses and obtains a client for the 'mymaster' service. The client automatically detects failover and reconnects. The example sets and gets a key asynchronously.

```python
import asyncio

from valkey.asyncio.sentinel import Sentinel

sentinel = Sentinel([("localhost", 26379), ("sentinel2", 26379)])
r = sentinel.master_for("mymaster")

ok = await r.set("key", "value")
assert ok
val = await r.get("key")
assert val == b"value"
```

--------------------------------

### Install valkey-py with pip

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Installs the valkey-py package from PyPI.

```bash
$ pip install valkey
```

--------------------------------

### Run the Valkey client example

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry/README.md

Runs the Valkey client example. The CLI prints a trace URL that you can follow to view the trace in Uptrace.

```shell
python3 main.py
trace: http://localhost:14318/traces/ee029d8782242c8ed38b16d961093b35
```

--------------------------------

### Install OpenTelemetry Redis instrumentation for valkey-py

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/opentelemetry.rst

Install the OpenTelemetry Redis instrumentation plugin for valkey-py.

```shell
pip install opentelemetry-instrumentation-redis
```

--------------------------------

### Start Valkey via Docker

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Starts a Valkey server in a Docker container, mapping port 6379 and running interactively.

```bash
docker run -p 6379:6379 -it valkey/valkey:latest
```

--------------------------------

### Enable client_capa_redirect and handle RedirectError

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/advanced_features.rst

Shows how to create a Valkey client with client_capa_redirect=True to receive redirect responses from a replica. When a command like get is sent to the replica, it raises RedirectError with host, port, and node_addr attributes. The example demonstrates catching the exception and printing the redirect target.

```python
>>> import valkey
>>> primary = valkey.Valkey(host='localhost', port=6379, decode_responses=True)
>>> replica = valkey.Valkey(
...     host='localhost',
...     port=6380,
...     decode_responses=True,
...     client_capa_redirect=True,
... )
>>> primary.set('example:key', 'value')
True
>>> try:
...     replica.get('example:key')
... except valkey.RedirectError as exc:
...     print(exc.host, exc.port)
...     print(exc.node_addr)
127.0.0.1 6379
('127.0.0.1', 6379)
```

--------------------------------

### Valkey pipeline example

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Basic Valkey pipeline example that batches multiple set commands and executes them in one round-trip. The execute() call returns a list of results, shown as [True, True, True].

```python
pipe = r.pipeline()
pipe.set('foo', 5)
pipe.set('bar', 18.5)
pipe.set('blee', "hello world!")
pipe.execute()
# [True, True, True]
```

--------------------------------

### Use Sentinel to get master and slave clients

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Creates a Sentinel client, then uses master_for and slave_for to get clients for the master and slave. Demonstrates setting a key on the master and getting it from the slave.

```pycon
>>> from valkey.sentinel import Sentinel
>>> sentinel = Sentinel([('localhost', 26379)], socket_timeout=0.1)
>>> master = sentinel.master_for('mymaster', socket_timeout=0.1)
>>> master.set('foo', 'bar')
>>> slave = sentinel.slave_for('mymaster', socket_timeout=0.1)
>>> slave.get('foo')
b'bar'
```

--------------------------------

### Install valkey-py with libvalkey support

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Installs valkey-py with libvalkey support for a compiled response parser. Requires libvalkey >= 2.3.2; if available, it is used by default for response parsing.

```bash
$ pip install "valkey[libvalkey]"
```

--------------------------------

### Install OpenTelemetry API and SDK with pip

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry_api_examples.ipynb

Install the opentelemetry-api and opentelemetry-sdk packages using pip. The output shows the packages are already installed in the user's environment.

```bash
pip install opentelemetry-api opentelemetry-sdk
```

```text
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: opentelemetry-api in /home/vmihailenco/.local/lib/python3.10/site-packages (1.14.0)
Requirement already satisfied: opentelemetry-sdk in /home/vmihailenco/.local/lib/python3.10/site-packages (1.14.0)
Requirement already satisfied: setuptools>=16.0 in /usr/lib/python3/dist-packages (from opentelemetry-api) (59.6.0)
Requirement already satisfied: deprecated>=1.2.6 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-api) (1.2.13)
Requirement already satisfied: opentelemetry-semantic-conventions==0.35b0 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-sdk) (0.35b0)
Requirement already satisfied: typing-extensions>=3.7.4 in /home/vmihailenco/.local/lib/python3.10/site-packages (from opentelemetry-sdk) (4.4.0)
Requirement already satisfied: wrapt<2,>=1.10 in /home/vmihailenco/.local/lib/python3.10/site-packages (from deprecated>=1.2.6->opentelemetry-api) (1.14.1)
Note: you may need to restart the kernel to use updated packages.
```

--------------------------------

### Connect with custom CredentialProvider and ACL setup

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/connection_examples.ipynb

Defines a custom CredentialProvider that maps usernames to passwords, sets up an ACL user, and connects using the provider. The example creates a default connection to configure the ACL user, then uses the custom provider to connect and ping.

```python
from typing import Tuple
import valkey

creds_map = {"user_1": "pass_1", "user_2": "pass_2"}


class UserMapCredentialProvider(valkey.CredentialProvider):
    def __init__(self, username: str):
        self.username = username

    def get_credentials(self) -> Tuple[str, str]:
        return self.username, creds_map.get(self.username)


# Create a default connection to set the ACL user
default_connection = valkey.Valkey(host="localhost", port=6379)
default_connection.acl_setuser(
    "user_1",
    enabled=True,
    passwords=["+" + "pass_1"],
    keys="~*",
    commands=["+ping", "+command", "+info", "+select", "+flushdb"],
)

# Create a UserMapCredentialProvider instance for user_1
creds_provider = UserMapCredentialProvider("user_1")
# Initiate user connection with the credential provider
user_connection = valkey.Valkey(
    host="localhost", port=6379, credential_provider=creds_provider
)
user_connection.ping()
```

--------------------------------

### Migration from redis-py using alias

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Shows how to use valkey-py with the redis-py class names via the alias import. The example performs the same set/get operations as the basic example.

```python
import valkey as redis
r = redis.Redis(host='localhost', port=6379, db=0)
r.set('foo', 'bar')
# True
r.get('foo')
# b'bar'
```

--------------------------------

### Output of xack example

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/valkey-stream-example.ipynb

Output from the xack example showing two acknowledged messages from the stream 'skey'.

```text
Output:
got element b'1710790167983-1'from stream b'skey'
got element b'1710790167983-2'from stream b'skey'
```

--------------------------------

### Valkey PubSub subscribe example

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

Example of using Valkey PubSub to subscribe to channels and retrieve messages. The get_message() call returns a dictionary with subscription confirmation details.

```python
r = valkey.Valkey(...)
p = r.pubsub()
p.subscribe('my-first-channel', 'my-second-channel', ...)
p.get_message()
# {'pattern': None, 'type': 'subscribe', 'channel': b'my-second-channel', 'data': 1}
```

--------------------------------

### Setup for performance comparison

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/pipeline_examples.ipynb

Sets up the performance comparison by importing datetime and defining the number of increments (100000).

```python
from datetime import datetime

incr_value = 100000

```

--------------------------------

### Start services with Docker Compose

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry/README.md

Starts the services defined in the docker-compose file in detached mode and then shows the logs for the uptrace service to confirm it is running.

```shell
docker compose up -d
docker compose logs uptrace
```

--------------------------------

### Define custom connection pool

Source: https://github.com/valkey-io/valkey-py/blob/main/README.md

By default, each Valkey instance gets its own connection pool. This example shows how to define your own valkey.ConnectionPool and pass it to the Valkey constructor.

```python
pool = valkey.ConnectionPool(host='localhost', port=6379, db=0)
r = valkey.Valkey(connection_pool=pool)
```

--------------------------------

### get

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Documentation for the get method, which retrieves the value of a key.

```APIDOC
## get(name)

### Description
Return the value at key `name`, or None if the key doesn't exist.

### Method
GET

### Parameters
- **name** (bytes | str | memoryview) - Required - The key name.

### Return Type
str | bytes | None | Awaitable[str | bytes | None]

### More Information
See [https://valkey.io/commands/get](https://valkey.io/commands/get)
```

--------------------------------

### Install OpenAI package

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/search_vector_similarity_examples.ipynb

Installs the OpenAI Python package using pip.

```python
%pip install openai
```

--------------------------------

### Install Cohere package

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/search_vector_similarity_examples.ipynb

Installs the Cohere Python package using pip.

```python
%pip install cohere
```

--------------------------------

### Define host and stream keys

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/valkey-stream-example.ipynb

Defines the host and stream/group names used throughout the example. Set these before running the other snippets.

```python
valkey_host = "valkey"
stream_key = "skey"
stream2_key = "s2key"
group1 = "grp1"
group2 = "grp2"
```

--------------------------------

### Clone the valkey-py repository

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry/README.md

Clones the valkey-py repository and changes into the example/opentelemetry directory, which contains the example files.

```shell
git clone https://github.com/valkey-io/valkey-py.git
cd example/opentelemetry
```

--------------------------------

### Install numpy and add vectors to Valkey with hset

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/search_vector_similarity_examples.ipynb

Install numpy, import it, and use a Valkey pipeline to write HASH objects with random vectors via HSET. The search index listens to keyspace notifications and includes HASH objects prefixed by DOC_PREFIX.

```python
%pip install numpy
```

```python
import numpy as np
```

```python
# instantiate a valkey pipeline
pipe = r.pipeline()

# define some dummy data
objects = [
    {"name": "a", "tag": "foo"},
    {"name": "b", "tag": "foo"},
    {"name": "c", "tag": "bar"},
]

# write data
for obj in objects:
    # define key
    key = f"doc:{obj['name']}"
    # create a random "dummy" vector
    obj["vector"] = np.random.rand(VECTOR_DIMENSIONS).astype(np.float32).tobytes()
    # HSET
    pipe.hset(key, mapping=obj)

res = pipe.execute()
```

--------------------------------

### DCO Signed-off-by line example

Source: https://github.com/valkey-io/valkey-py/blob/main/CONTRIBUTING.md

Example of a DCO-signed commit line that must appear in every contribution to Valkey. Use your real or preferred name; anonymous or pseudonymous contributions are not accepted. You can add this line manually or use git commit -s or --signoff.

```text
Signed-off-by: Jane Smith <jane.smith@email.com>
```

--------------------------------

### Use READONLY to restore read commands on replica

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/advanced_features.rst

After enabling client_capa_redirect, calling READONLY on the same connection restores the ability to run read commands against the replica. The example shows that after readonly() returns True, get('example:key') returns the value instead of raising RedirectError. Write commands still redirect after READONLY.

```python
>>> replica.readonly()
True
>>> replica.get('example:key')
'value'
```

--------------------------------

### Basic pipeline usage with r.pipeline() and execute()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/advanced_features.rst

Creates a pipeline with r.pipeline(), buffers SET and GET commands, then sends them with execute(). The output shows the list of responses: [True, b'baz'].

```python
>>> r = valkey.Valkey(...)
>>> r.set('bing', 'baz')
>>> # Use the pipeline() method to create a pipeline instance
>>> pipe = r.pipeline()
>>> # The following SET commands are buffered
>>> pipe.set('foo', 'bar')
>>> pipe.get('bing')
>>> # the EXECUTE call sends all buffered commands to the server, returning
>>> # a list of responses, one for each command.
>>> pipe.execute()
[True, b'baz']
```

--------------------------------

### Create a span with OpenTelemetry API

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/opentelemetry.rst

Create a tracer and start a span named 'operation-name' with kind CLIENT to measure operations.

```python
from opentelemetry import trace

tracer = trace.get_tracer("app_or_package_name", "1.0.0")

# Create a span with name "operation-name" and kind="server".
with tracer.start_as_current_span("operation-name", kind=trace.SpanKind.CLIENT) as span:
    do_some_work()
```

--------------------------------

### Connect to Valkey and ping

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/valkey-stream-example.ipynb

Imports the valkey client and required exceptions, then creates a Valkey client and pings the server. The ping returns True when the connection is successful.

```python
import valkey
from time import time
from valkey.exceptions import (
    ConnectionError,
    DataError,
    NoScriptError,
    ValkeyError,
    ResponseError,
)

r = valkey.Valkey(valkey_host)
r.ping()
```

--------------------------------

### initialize()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Async method to initialize the cluster client.

```APIDOC
## initialize()

### Description
Async method to get all nodes from startup nodes and create connections if not initialized.

### Method
async

### Return Type
ValkeyCluster
```

--------------------------------

### on_connect(connection)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Initializes the connection, authenticates, selects a database, and sends READONLY if set during object initialization.

```APIDOC
## on_connect(connection)

### Description
Initializes the connection, authenticates and selects a database, and sends READONLY if it is set during object initialization.

### Parameters
- **connection** (Connection) - Required - The connection to initialize.
```

--------------------------------

### Create JSON index and add documents

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/search_json_examples.ipynb

Sets up a Valkey connection, stores four JSON documents under keys with the 'user:' prefix, and creates a JSON index with text, tag, and numeric fields extracted from JSON paths.

```python
import valkey
from valkey.commands.json.path import Path
import valkey.commands.search.aggregation as aggregations
import valkey.commands.search.reducers as reducers
from valkey.commands.search.field import TextField, NumericField, TagField
from valkey.commands.search.indexDefinition import IndexDefinition, IndexType
from valkey.commands.search.query import NumericFilter, Query

r = valkey.Valkey(host="localhost", port=6379)
user1 = {
    "user": {
        "name": "Paul John",
        "email": "paul.john@example.com",
        "age": 42,
        "city": "London",
    }
}
user2 = {
    "user": {
        "name": "Eden Zamir",
        "email": "eden.zamir@example.com",
        "age": 29,
        "city": "Tel Aviv",
    }
}
user3 = {
    "user": {
        "name": "Paul Zamir",
        "email": "paul.zamir@example.com",
        "age": 35,
        "city": "Tel Aviv",
    }
}

user4 = {
    "user": {
        "name": "Sarah Zamir",
        "email": "sarah.zamir@example.com",
        "age": 30,
        "city": "Paris",
    }
}
r.json().set("user:1", Path.root_path(), user1)
r.json().set("user:2", Path.root_path(), user2)
r.json().set("user:3", Path.root_path(), user3)
r.json().set("user:4", Path.root_path(), user4)

schema = (
    TextField("$.user.name", as_name="name"),
    TagField("$.user.city", as_name="city"),
    NumericField("$.user.age", as_name="age"),
)
r.ft().create_index(
    schema, definition=IndexDefinition(prefix=["user:"], index_type=IndexType.JSON)
)
```

```text
Result:
b'OK'
```

--------------------------------

### lrange(name, start, end)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Returns a slice of a list between start and end positions.

```APIDOC
## lrange(name, start, end)

### Description
Return a slice of the list `name` between position `start` and `end`. Negative indices are supported.

### Method
lrange

### Parameters
- **name** (*bytes* | *str* | *memoryview*) - Required - The name of the list.
- **start** (*int*) - Required - Starting position.
- **end** (*int*) - Required - Ending position.

### Return Type
list[str | bytes] | Awaitable[list[str | bytes]]

### Reference
https://valkey.io/commands/lrange
```

--------------------------------

### lrange(name, start, end)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Returns a slice of a list between start and end indices.

```APIDOC
## lrange(name, start, end)

### Description
Return a slice of the list `name` between position `start` and `end`. Negative indices are supported.

### Method
lrange

### Parameters
- **name** (*bytes* | *str* | *memoryview*) - Required - The name of the list.
- **start** (*int*) - Required - Starting index.
- **end** (*int*) - Required - Ending index.

### Return Type
list[str | bytes] | Awaitable[list[str | bytes]]

### Reference
https://valkey.io/commands/lrange
```

--------------------------------

### Create a PubSub object

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/advanced_features.rst

Creates a Valkey client and a PubSub object for subscribing to channels and listening for messages.

```python
>>> r = valkey.Valkey(...)
>>> p = r.pubsub()
```

--------------------------------

### Connect with RESP3 protocol (protocol=3)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/connection_examples.ipynb

Enables RESP3 protocol by setting protocol=3. Note: the example uses rcon.ping() but the connection variable is r, which may be a typo in the source.

```python
import valkey

r = valkey.Valkey(protocol=3)
rcon.ping()
```

--------------------------------

### function_load(code, replace=False)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Loads a library to Valkey. The code must start with a shebang statement providing metadata about the library. The replace option overwrites an existing library.

```APIDOC
## function_load(code, replace=False)

### Description
Load a library to Valkey. The code must start with a shebang statement that provides metadata about the library. If replace is True, the existing library is overwritten.

### Method
function_load

### Parameters
- **code** (str) - Required - The source code of the library.
- **replace** (bool) - Optional - If True, overwrite the existing library with the new contents.

### Return Type
str | bytes | Awaitable[str | bytes]

### Reference
[https://valkey.io/commands/function-load](https://valkey.io/commands/function-load)
```

--------------------------------

### Create ValkeyCluster with ClusterNode startup nodes

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/clustering.rst

Create a ValkeyCluster client directly using the ClusterNode class to specify startup nodes. The client attempts to connect to one of the provided startup nodes.

```python
>>> from valkey.cluster import ValkeyCluster as Valkey
>>> from valkey.cluster import ClusterNode
>>> nodes = [ClusterNode('localhost', 6379), ClusterNode('localhost', 6378)]
>>> rc = Valkey(startup_nodes=nodes)
```

--------------------------------

### Create a pipeline instance

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/pipeline_examples.ipynb

Creates a pipeline instance from the Valkey client. Commands added to the pipeline are buffered and executed together when execute() is called.

```python
pipe = r.pipeline()

```

--------------------------------

### Get stream length after xack

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/valkey-stream-example.ipynb

Gets the length of the stream after acknowledging all messages. The result is 20, indicating the stream length remains unchanged after xack.

```python
r.xlen(stream_key)
```

--------------------------------

### substr(name, start, end=-1)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Returns a substring of the string at key `name`. `start` and `end` are 0-based integers specifying the portion of the string to return.

```APIDOC
## substr(name, start, end=-1)

### Description
Returns a substring of the string at key `name`. `start` and `end` are 0-based integers specifying the portion of the string to return.

### Parameters
- **name** (bytes | str | memoryview) - Required - The key name.
- **start** (int) - Required - Starting index (0-based).
- **end** (int) - Optional - Ending index (0-based). Default is -1.

### Return Type
str | bytes | Awaitable[str | bytes]
```

--------------------------------

### Loading external Valkey module

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Example of using load_external_module to add a custom module named 'foo' with commands 'foo.do_thing' and 'foo.another_thing'. After loading, the client can call r.foo().do_thing('your', 'arguments').

```python
from valkey import Valkey
from foomodule import F
r = Valkey()
r.load_external_module("foo", F)
r.foo().do_thing('your', 'arguments')
```

--------------------------------

### Enable RESP protocol version 3

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/asyncio_examples.ipynb

Sets the `protocol` parameter to 3 to enable RESP version 3. The example creates a client, closes it, and then pings, but note that the ping is called after closing the client.

```python
import valkey.asyncio as valkey

client = valkey.Valkey(protocol=3)
await client.aclose()
await client.ping()
```

--------------------------------

### Execute pipeline and get responses

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/pipeline_examples.ipynb

Executes all buffered commands in the pipeline. The responses are returned as a list: booleans for the set commands and the value from get("a").

```python
pipe.execute()

```

```text
Result:
[True, True, 'a value']

```

--------------------------------

### hello

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Intentionally unsupported; always raises NotImplementedError.

```APIDOC
## hello()

### Description
This function throws a NotImplementedError since it is intentionally not supported.

### Return Type
NoReturn
```

--------------------------------

### Connect with host, port, username, password, and decode_responses

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/connection_examples.ipynb

Connects to a Valkey instance on localhost:6380 with username and password credentials, and decodes responses. The ping returns True.

```python
import valkey

user_connection = valkey.Valkey(
    host="localhost",
    port=6380,
    username="dvora",
    password="valkey",
    decode_responses=True,
)
user_connection.ping()
```

```text
Result:
True
```

--------------------------------

### Connect with standard Valkey client using protocol=3

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/resp3_features.rst

Creates a standard Valkey client with RESP 3 enabled by setting protocol=3. The ping() call verifies the connection.

```python
>>> import valkey
>>> r = valkey.Valkey(host='localhost', port=6379, protocol=3)
>>> r.ping()
```

--------------------------------

### Set and get a value with valkey.Valkey

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Basic usage of the Valkey client to set and get a string value. The connection is created with decode_responses=True so responses are returned as strings instead of bytes.

```python
import valkey
r = valkey.Valkey(decode_responses=True)
r.set('mykey', 'thevalueofmykey')
r.get('mykey')
```

--------------------------------

### Connect to Sentinel and discover master and slaves

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Creates a Sentinel client and uses discover_master and discover_slaves to find the current master and slave addresses. Assumes Valkey is running on the listed ports.

```pycon
>>> from valkey import Sentinel
>>> sentinel = Sentinel([('localhost', 26379)], socket_timeout=0.1)
>>> sentinel.discover_master('mymaster')
('127.0.0.1', 6379)
>>> sentinel.discover_slaves('mymaster')
[('127.0.0.1', 6380)]
```

--------------------------------

### sentinel_masters()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the state of all masters.

```APIDOC
## sentinel_masters()

### Description
Returns a list of dictionaries containing each master's state.

### Method
SENTINEL MASTERS

### Parameters
None

### Response
Returns a list of dictionaries, each containing a master's state.
```

--------------------------------

### ValkeyCluster.__init__

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Initializes a ValkeyCluster client with connection parameters such as host, port, startup nodes, retry settings, and more.

```APIDOC
## ValkeyCluster.__init__

### Description
Initializes a ValkeyCluster client with the given connection parameters.

### Method
Constructor

### Parameters
- **host** (str | None) - Optional - The hostname of the cluster node.
- **port** (int) - Optional - The port of the cluster node. Defaults to 6379.
- **startup_nodes** (List[ClusterNode] | None) - Optional - A list of startup nodes.
- **cluster_error_retry_attempts** (int) - Optional - Number of retry attempts for cluster errors. Defaults to 3.
- **retry** (Retry | None) - Optional - A Retry object for retry logic.
- **require_full_coverage** (bool) - Optional - Whether full coverage is required. Defaults to False.
- **reinitialize_steps** (int) - Optional - Steps for reinitialization. Defaults to 5.
- **read_from_replicas** (bool) - Optional - Whether to read from replicas. Defaults to False.
- **dynamic_startup_nodes** (bool) - Optional - Whether startup nodes are dynamic. Defaults to True.
- **url** (str | None) - Optional - A URL for the cluster.
- **address_remap** (Callable[[Tuple[str, int]], Tuple[str, int]] | None) - Optional - A callable to remap addresses.

### Response
No return value.
```

--------------------------------

### scard

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the cardinality of a set.

```APIDOC
## scard(name)

### Description
Return the number of elements in the set `name`.

### Method
SCARD

### Parameters
- **name** (bytes | str | memoryview) - Required - The name of the set.

### Return Type
int | Awaitable[int]
```

--------------------------------

### Connect to default Valkey instance and ping

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/connection_examples.ipynb

Connects to a default Valkey instance running locally on localhost:6379 and pings it. The output shows that the ping returns True.

```python
import valkey

connection = valkey.Valkey()
connection.ping()
```

```text
Result:
True
```

--------------------------------

### get_nodes()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get all nodes of the cluster.

```APIDOC
## get_nodes()

### Description
Get all nodes of the cluster.

### Method
sync

### Return Type
List[ClusterNode]
```

--------------------------------

### Create PubSub connections in Valkey Cluster

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/clustering.rst

Shows how to create PubSub connections in a Valkey Cluster. The first connection is automatically routed to the node holding the keyslot for 'foo', while the second explicitly targets a specific node using rc.get_node().

```python
>>> p1 = rc.pubsub()
# p1 connection will be set to the node that holds 'foo' keyslot
>>> p1.subscribe('foo')
# p2 connection will be set to node 'localhost:6379'
>>> p2 = rc.pubsub(rc.get_node('localhost', 6379))
```

--------------------------------

### slowlog_len

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the number of items in the slowlog.

```APIDOC
## slowlog_len(**kwargs)

### Description
Get the number of items in the slowlog.

### Method
slowlog_len

### Parameters
- **kwargs** - Optional - Keyword arguments.

### Return Type
int | Awaitable[int]
```

--------------------------------

### from_url(url, **kwargs)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Classmethod to create a Valkey client from a URL.

```APIDOC
## from_url(url, **kwargs)

### Description
Return a Valkey client object configured from the given URL. Supports three URL schemes: valkey://, valkeys://, and unix://.

### Method
Classmethod

### Parameters
- **url** (str) - Required - The URL to configure the client from.
- **kwargs** - Optional - Additional keyword arguments passed to the ConnectionPool initializer.

### URL Schemes
- `valkey://` - Creates a TCP socket connection.
- `valkeys://` - Creates a SSL wrapped TCP socket connection.
- `unix://` - Creates a Unix Domain Socket connection.

### Database Number Selection
1. A `db` querystring option, e.g. valkey://localhost?db=0
2. If using the valkey:// or valkeys:// schemes, the path argument of the url, e.g. valkey://localhost/0
3. A `db` keyword argument to this function.

If none of these options are specified, the default db=0 is used.

### Notes
- The username, password, hostname, path and all querystring values are passed through urllib.parse.unquote to replace percent-encoded values.
- All querystring options are cast to their appropriate Python types. Boolean arguments can be specified with string values "True"/"False" or "Yes"/"No". Values that cannot be properly cast cause a ValueError to be raised.
- Querystring arguments always win in case of conflicting arguments.

### Return Type
Valkey

```

--------------------------------

### acl_whoami

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the username for the current connection.

```APIDOC
## acl_whoami(**kwargs)

### Description
Get the username for the current connection.

### Method
acl_whoami

### Return Type
str | bytes | Awaitable[str | bytes]
```

--------------------------------

### from_url(url, **kwargs)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Classmethod to create a Valkey client from a URL.

```APIDOC
## from_url(url, **kwargs)

### Description
Classmethod that returns a Valkey client object configured from the given URL. Supports valkey:// and valkeys:// URL schemes.

### Method
classmethod

### Parameters
- **url** (str) - Required - The URL to configure the client.
- **kwargs** (Any) - Optional - Additional keyword arguments passed to the Connection.

### Return Type
ValkeyCluster
```

--------------------------------

### acl_log

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Gets ACL logs as a list.

```APIDOC
## acl_log(count=None, **kwargs)

### Description
Gets ACL logs as a list. If count is provided, returns logs[0:count].

### Parameters
- **count** (int | None) - Optional - Number of logs to return.

### Return Type
list[dict[str, str | float | dict[str, str | int]]] | Awaitable[list[dict[str, str | float | dict[str, str | int]]]]
```

--------------------------------

### get

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Method to retrieve the value of a key.

```APIDOC
## get(name)

### Description
Return the value at key `name`, or None if the key doesn't exist.

### Method
GET

### Parameters
- **name** (bytes | str | memoryview) - Required - The key name.

### Return Type
str | bytes | None | Awaitable[str | bytes | None]
```

--------------------------------

### Connect to Valkey using from_url

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/index.rst

Connects to a Valkey server using a URL string with the valkey:// scheme and verifies the connection with a ping command.

```python
import valkey
r = valkey.from_url('valkey://foo.bar.com:12345')
r.ping()
```

--------------------------------

### get_connection_kwargs()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the kwargs passed to Connection.

```APIDOC
## get_connection_kwargs()

### Description
Get the kwargs passed to Connection.

### Method
sync

### Return Type
Dict[str, Any | None]
```

--------------------------------

### Create ValkeyCluster with host and port

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/clustering.rst

Create a ValkeyCluster client using host and port arguments. The client connects to a single node for cluster discovery and prints the discovered nodes.

```python
>>> from valkey.cluster import ValkeyCluster as Valkey
>>> rc = Valkey(host='localhost', port=6379)
>>> print(rc.get_nodes())
    [[host=127.0.0.1,port=6379,name=127.0.0.1:6379,server_type=primary,valkey_connection=Valkey<ConnectionPool<Connection<host=127.0.0.1,port=6379,db=0>>>], [host=127.0.0.1,port=6378,name=127.0.0.1:6378,server_type=primary,valkey_connection=Valkey<ConnectionPool<Connection<host=127.0.0.1,port=6378,db=0>>>], [host=127.0.0.1,port=6377,name=127.0.0.1:6377,server_type=replica,valkey_connection=Valkey<ConnectionPool<Connection<host=127.0.0.1,port=6377,db=0>>>]]
```

--------------------------------

### get_encoder()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the encoder object of the client.

```APIDOC
## get_encoder()

### Description
Get the encoder object of the client.

### Method
sync

### Return Type
Encoder
```

--------------------------------

### Connect async client with protocol=3

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/resp3_features.rst

Creates an asynchronous Valkey client with RESP 3 enabled by setting protocol=3. The await r.ping() call verifies the connection asynchronously.

```python
>>> import valkey.asyncio as valkey
>>> r = valkey.Valkey(host='localhost', port=6379, protocol=3)
>>> await r.ping()
```

--------------------------------

### get_default_node()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the default node of the client.

```APIDOC
## get_default_node()

### Description
Get the default node of the client.

### Method
sync

### Return Type
ClusterNode
```

--------------------------------

### get_random_node()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get a random node of the cluster.

```APIDOC
## get_random_node()

### Description
Get a random node of the cluster.

### Method
sync

### Return Type
ClusterNode
```

--------------------------------

### Connect async client via URL with protocol=3

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/resp3_features.rst

Connects asynchronously to Valkey using a URL scheme with the protocol=3 query parameter to enable RESP 3. The await r.ping() call verifies the connection.

```python
>>> import valkey.asyncio as Valkey
>>> r = valkey.from_url("valkey://localhost:6379?protocol=3")
>>> await r.ping()
```

--------------------------------

### module_loadex(path, options=None, args=None)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Loads a module from a dynamic library at runtime with configuration directives.

```APIDOC
## module_loadex(path, options=None, args=None)

### Description
Loads a module from a dynamic library at runtime with configuration directives.

### Method
module_loadex

### Parameters
- **path** (str) - Required - The path to the module to load.
- **options** (list[str] | None) - Optional - Configuration options for the module.
- **args** (list[str] | None) - Optional - Arguments to pass to the module.

### Return Type
str | bytes | Awaitable[str | bytes]

### Reference
For more information see [https://valkey.io/commands/module-loadex](https://valkey.io/commands/module-loadex)
```

--------------------------------

### get_replicas()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the replica nodes of the cluster.

```APIDOC
## get_replicas()

### Description
Get the replica nodes of the cluster.

### Method
sync

### Return Type
List[ClusterNode]
```

--------------------------------

### get_primaries()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the primary nodes of the cluster.

```APIDOC
## get_primaries()

### Description
Get the primary nodes of the cluster.

### Method
sync

### Return Type
List[ClusterNode]
```

--------------------------------

### module_loadex(path, options=None, args=None)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Loads a module from a dynamic library at runtime with configuration directives.

```APIDOC
## module_loadex(path, options=None, args=None)

### Description
Loads a module from a dynamic library at runtime with configuration directives.

### Parameters
- **path** (str) - Required
- **options** (list[str] | None) - Optional
- **args** (list[str] | None) - Optional

### Return Type
str | bytes | Awaitable[str | bytes]
```

--------------------------------

### Use valkey-py sync and async clients after instrumentation

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/opentelemetry.rst

After instrumentation, use valkey-py sync and async clients as usual.

```python
# Sync client
client = valkey.Valkey()
client.get("my-key")

# Async client
client = valkey.asyncio.Valkey()
await client.get("my-key")
```

--------------------------------

### expiretime(key)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Gets the expiration timestamp of a key.

```APIDOC
## expiretime(key)

### Description
Returns the absolute Unix timestamp (since January 1, 1970) in seconds at which the given key will expire.

### Method
EXPIRETIME

### Parameters
#### Path Parameters
- **key** (str) - Required - The key to check.

### Return Type
int | Awaitable[int]

### Reference
For more information see [https://valkey.io/commands/expiretime](https://valkey.io/commands/expiretime)
```

--------------------------------

### acl_getuser

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Gets the ACL details for a specified username.

```APIDOC
## acl_getuser(username, **kwargs)

### Description
Gets the ACL details for the specified username. If the username does not exist, returns None.

### Parameters
- **username** (str) - Required - The username to get details for.

### Return Type
dict[str, bool | list[str] | list[list[str]] | list[dict[str, str]]] | None | Awaitable[dict[str, bool | list[str] | list[list[str]] | list[dict[str, str]]] | None]
```

--------------------------------

### Create and activate a virtual environment

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/opentelemetry/README.md

Creates a Python virtual environment named .venv and activates it. This step is optional.

```shell
python3 -m venv .venv
source .venv/bin/active
```

--------------------------------

### sentinel_master(service_name)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the state of a specific master.

```APIDOC
## sentinel_master(service_name)

### Description
Returns a dictionary containing the specified master's state.

### Method
SENTINEL MASTER

### Parameters
- **service_name** (string) - Required - The name of the master service.

### Response
Returns a dictionary containing the master's state.
```

--------------------------------

### acl_whoami(**kwargs)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Get the username for the current connection.

```APIDOC
## acl_whoami(**kwargs)

### Description
Get the username for the current connection.

### Method
acl_whoami

### Parameters
- **kwargs** - Optional - Additional keyword arguments (not documented).

### Return Type
str | bytes | Awaitable[str | bytes]

### More Information
See [https://valkey.io/commands/acl-whoami](https://valkey.io/commands/acl-whoami)
```

--------------------------------

### acl_log(count=None)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Gets ACL logs as a list.

```APIDOC
## acl_log(count=None)

### Description
Get ACL logs as a list. If `count` is supplied, returns logs[0:count].

### Method
Function call on a Valkey client instance.

### Parameters
- **count** (int | None) - Optional - The number of logs to return.

### Return Type
list[dict[str, str | float | dict[str, str | int]]] | Awaitable[list[dict[str, str | float | dict[str, str | int]]]]
```

--------------------------------

### info(section=None, *args, **kwargs)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Returns a dictionary containing information about the Valkey server. The section option can be used to select a specific section of information.

```APIDOC
## info(section=None, *args, **kwargs)

### Description
Returns a dictionary containing information about the Valkey server. The `section` option can be used to select a specific section of information. The section option is not supported by older versions of Valkey Server, and will generate ResponseError.

### Parameters
- **section** (str | None) - Optional - The section of information to retrieve.
- **args** (str) - Optional - Additional arguments.

### Return Type
dict[str, str | int | float | dict[str, str | int]] | Awaitable[dict[str, str | int | float | dict[str, str | int]]]

### Reference
For more information see [https://valkey.io/commands/info](https://valkey.io/commands/info)
```

--------------------------------

### get_encoder()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the connection pool's encoder.

```APIDOC
## get_encoder()

### Description
Get the connection pool's encoder.

### Method
sync

### Parameters
None

### Return Type
Encoder
```

--------------------------------

### get_connection_kwargs()

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Get the connection's key-word arguments.

```APIDOC
## get_connection_kwargs()

### Description
Get the connection's key-word arguments.

### Method
sync

### Parameters
None

### Return Type
Connection keyword arguments
```

--------------------------------

### Connect to Valkey via SSL with ssl_min_version=TLSv1_3

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/ssl_connection_examples.ipynb

Connects via SSL while specifying a minimum TLS version of TLSv1_3. The ping returns True.

```python
import valkey
import ssl

r = valkey.Valkey(
    host="localhost",
    port=6666,
    ssl=True,
    ssl_min_version=ssl.TLSVersion.TLSv1_3,
    ssl_cert_reqs="none",
)
r.ping()
```

```text
Result:
True
```

--------------------------------

### command

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Returns a dictionary reply of details about all Valkey commands.

```APIDOC
## command(**kwargs)

### Description
Returns dict reply of details about all Valkey commands.

### Parameters
- **kwargs** - Additional keyword arguments.

### Return Type
dict[str, dict[str, Any]] | Awaitable[dict[str, dict[str, Any]]]

### Reference
See [https://valkey.io/commands/command](https://valkey.io/commands/command)
```

--------------------------------

### Initialize Valkey client and timeseries API

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/timeseries_examples.ipynb

Initializes a Valkey client with decode_responses=True, obtains the timeseries API via r.ts(), and verifies connectivity with r.ping().

```python
import valkey

r = valkey.Valkey(decode_responses=True)
ts = r.ts()

r.ping()
```

--------------------------------

### acl_getuser(username)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/commands.rst

Gets the ACL details for a specified username.

```APIDOC
## acl_getuser(username)

### Description
Get the ACL details for the specified username. If username does not exist, return None.

### Method
Function call on a Valkey client instance.

### Parameters
- **username** (str) - Required - The username to get details for.

### Return Type
dict[str, bool | list[str] | list[list[str]] | list[dict[str, str]]] | None | Awaitable[dict[str, bool | list[str] | list[list[str]] | list[dict[str, str]]] | None]
```

--------------------------------

### Get last sample

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/timeseries_examples.ipynb

Retrieves the most recent sample from the timeseries.

```python
ts.get("ts_key")
```

--------------------------------

### execute_command(*args, **options)

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/connections.rst

Executes a command and returns a parsed response. This is the core method for sending commands to Valkey.

```APIDOC
## execute_command(*args, **options)

### Description
Execute a command and return a parsed response.

### Method
async

### Parameters
- **args** (Any) - Required - Command arguments.
- **options** (Any) - Optional - Command options.

### Return Type
Parsed response
```

--------------------------------

### Get samples between timestamps

Source: https://github.com/valkey-io/valkey-py/blob/main/docs/examples/timeseries_examples.ipynb

Fetches samples between two specific timestamps (inclusive).

```python
ts.range("ts_key", 1657265437756, 1657265437757)
```
Tokens:
Raw