# valkey-py
The Python interface to the Valkey key-value store.
[](https://github.com/valkey-io/valkey-py/actions?query=workflow%3ACI+branch%3Amain)
[](https://valkey-py.readthedocs.io/en/latest/)
[](./LICENSE)
[](https://pypi.org/project/valkey/)
[](https://github.com/valkey-io/valkey-py/releases)
[](https://codecov.io/gh/valkey-io/valkey-py)
[Installation](#installation) | [Usage](#usage) | [Advanced Topics](#advanced-topics) | [Contributing](https://github.com/valkey-io/valkey-py/blob/main/CONTRIBUTING.md)
---------------------------------------------
## Installation
Start a valkey via docker:
``` bash
docker run -p 6379:6379 -it valkey/valkey:latest
```
To install valkey-py, simply:
``` bash
$ pip install valkey
```
For faster performance, install valkey with libvalkey support, this provides a compiled response parser, and *for most cases* requires zero code changes.
By default, if libvalkey >= 2.3.2 is available, valkey-py will attempt to use it for response parsing.
``` bash
$ pip install "valkey[libvalkey]"
```
## Usage
### Basic Example
``` python
>>> import valkey
>>> r = valkey.Valkey(host='localhost', port=6379, db=0)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
b'bar'
```
The above code connects to localhost on port 6379, sets a value in Redis, and retrieves it. All responses are returned as bytes in Python, to receive decoded strings, set *decode_responses=True*. For this, and more connection options, see [these examples](https://valkey-py.readthedocs.io/en/latest/examples.html).
### Migration from redis-py
You are encouraged to use the new class names, but to allow for a smooth transition alias are available:
``` python
>>> import valkey as redis
>>> r = redis.Redis(host='localhost', port=6379, db=0)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
b'bar'
```
#### RESP3 Support
To enable support for RESP3 change your connection object to include *protocol=3*
``` python
>>> import valkey
>>> r = valkey.Valkey(host='localhost', port=6379, db=0, protocol=3)
```
### Connection Pools
By default, valkey-py uses a connection pool to manage connections. Each instance of a Valkey class receives its own connection pool. You can however define your own [valkey.ConnectionPool](https://valkey-py.readthedocs.io/en/latest/connections.html#connection-pools).
``` python
>>> pool = valkey.ConnectionPool(host='localhost', port=6379, db=0)
>>> r = valkey.Valkey(connection_pool=pool)
```
Alternatively, you might want to look at [Async connections](https://valkey-py.readthedocs.io/en/latest/examples/asyncio_examples.html), or [Cluster connections](https://valkey-py.readthedocs.io/en/latest/connections.html#cluster-client), or even [Async Cluster connections](https://valkey-py.readthedocs.io/en/latest/connections.html#async-cluster-client).
### Valkey Commands
There is built-in support for all of the [out-of-the-box Valkey commands](https://valkey.io/commands). They are exposed using the raw Redis command names (`HSET`, `HGETALL`, etc.) except where a word (i.e. del) is reserved by the language. The complete set of commands can be found [here](https://github.com/valkey-io/valkey-py/tree/main/valkey/commands), or [the documentation](https://valkey-py.readthedocs.io/en/latest/commands.html).
## Advanced Topics
The [official Valkey command documentation](https://valkey.io/commands)
does a great job of explaining each command in detail. valkey-py attempts
to adhere to the official command syntax. There are a few exceptions:
- **MULTI/EXEC**: These are implemented as part of the Pipeline class.
The pipeline is wrapped with the MULTI and EXEC statements by
default when it is executed, which can be disabled by specifying
transaction=False. See more about Pipelines below.
- **SUBSCRIBE/LISTEN**: Similar to pipelines, PubSub is implemented as
a separate class as it places the underlying connection in a state
where it can\'t execute non-pubsub commands. Calling the pubsub
method from the Valkey client will return a PubSub instance where you
can subscribe to channels and listen for messages. You can only call
PUBLISH from the Valkey client (see [this comment on issue
#151](https://github.com/redis/redis-py/issues/151#issuecomment-1545015)
for details).
For more details, please see the documentation on [advanced topics page](https://valkey-py.readthedocs.io/en/latest/advanced_features.html).
### Pipelines
The following is a basic example of a [Valkey pipeline](https://redis.io/docs/manual/pipelining/), a method to optimize round-trip calls, by batching Valkey commands, and receiving their results as a list.
``` python
>>> pipe = r.pipeline()
>>> pipe.set('foo', 5)
>>> pipe.set('bar', 18.5)
>>> pipe.set('blee', "hello world!")
>>> pipe.execute()
[True, True, True]
```
### PubSub
The following example shows how to utilize [Valkey Pub/Sub](https://redis.io/docs/manual/pubsub/) to subscribe to specific channels.
``` 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}
```
--------------------------
### Author
valkey-py can be found [here](
https://github.com/valkey-io/valkey-py), or downloaded from [pypi](https://pypi.org/project/valkey/).
It was created as a fork of [redis-py](https://github.com/redis/redis-py)
Special thanks to:
- Andy McCurdy (<sedrik@gmail.com>) the original author of redis-py.
- Ludovico Magnocavallo, author of the original Python Redis client,
from which some of the socket code is still used.
- Alexander Solovyov for ideas on the generic response callback
system.
- Paul Hubbard for initial packaging support in redis-py.
[](https://valkey.io/)
Raw data
{
"_id": null,
"home_page": "https://github.com/valkey-io/valkey-py",
"name": "valkey",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Valkey, key-value store, database",
"author": "valkey-py authors",
"author_email": "valkey-py@lists.valkey.io",
"download_url": "https://files.pythonhosted.org/packages/45/f7/b552b7a67017e6233cd8a3b783ce8c4b548e29df98daedd7fb4c4c2cc8f8/valkey-6.0.2.tar.gz",
"platform": null,
"description": "# valkey-py\n\nThe Python interface to the Valkey key-value store.\n\n[](https://github.com/valkey-io/valkey-py/actions?query=workflow%3ACI+branch%3Amain)\n[](https://valkey-py.readthedocs.io/en/latest/)\n[](./LICENSE)\n[](https://pypi.org/project/valkey/)\n[](https://github.com/valkey-io/valkey-py/releases)\n[](https://codecov.io/gh/valkey-io/valkey-py)\n\n[Installation](#installation) | [Usage](#usage) | [Advanced Topics](#advanced-topics) | [Contributing](https://github.com/valkey-io/valkey-py/blob/main/CONTRIBUTING.md)\n\n---------------------------------------------\n\n## Installation\n\nStart a valkey via docker:\n\n``` bash\ndocker run -p 6379:6379 -it valkey/valkey:latest\n```\n\nTo install valkey-py, simply:\n\n``` bash\n$ pip install valkey\n```\n\nFor faster performance, install valkey with libvalkey support, this provides a compiled response parser, and *for most cases* requires zero code changes.\nBy default, if libvalkey >= 2.3.2 is available, valkey-py will attempt to use it for response parsing.\n\n``` bash\n$ pip install \"valkey[libvalkey]\"\n```\n\n## Usage\n\n### Basic Example\n\n``` python\n>>> import valkey\n>>> r = valkey.Valkey(host='localhost', port=6379, db=0)\n>>> r.set('foo', 'bar')\nTrue\n>>> r.get('foo')\nb'bar'\n```\n\nThe above code connects to localhost on port 6379, sets a value in Redis, and retrieves it. All responses are returned as bytes in Python, to receive decoded strings, set *decode_responses=True*. For this, and more connection options, see [these examples](https://valkey-py.readthedocs.io/en/latest/examples.html).\n\n### Migration from redis-py\n\nYou are encouraged to use the new class names, but to allow for a smooth transition alias are available:\n\n``` python\n>>> import valkey as redis\n>>> r = redis.Redis(host='localhost', port=6379, db=0)\n>>> r.set('foo', 'bar')\nTrue\n>>> r.get('foo')\nb'bar'\n```\n\n#### RESP3 Support\nTo enable support for RESP3 change your connection object to include *protocol=3*\n\n``` python\n>>> import valkey\n>>> r = valkey.Valkey(host='localhost', port=6379, db=0, protocol=3)\n```\n\n### Connection Pools\n\nBy default, valkey-py uses a connection pool to manage connections. Each instance of a Valkey class receives its own connection pool. You can however define your own [valkey.ConnectionPool](https://valkey-py.readthedocs.io/en/latest/connections.html#connection-pools).\n\n``` python\n>>> pool = valkey.ConnectionPool(host='localhost', port=6379, db=0)\n>>> r = valkey.Valkey(connection_pool=pool)\n```\n\nAlternatively, you might want to look at [Async connections](https://valkey-py.readthedocs.io/en/latest/examples/asyncio_examples.html), or [Cluster connections](https://valkey-py.readthedocs.io/en/latest/connections.html#cluster-client), or even [Async Cluster connections](https://valkey-py.readthedocs.io/en/latest/connections.html#async-cluster-client).\n\n### Valkey Commands\n\nThere is built-in support for all of the [out-of-the-box Valkey commands](https://valkey.io/commands). They are exposed using the raw Redis command names (`HSET`, `HGETALL`, etc.) except where a word (i.e. del) is reserved by the language. The complete set of commands can be found [here](https://github.com/valkey-io/valkey-py/tree/main/valkey/commands), or [the documentation](https://valkey-py.readthedocs.io/en/latest/commands.html).\n\n## Advanced Topics\n\nThe [official Valkey command documentation](https://valkey.io/commands)\ndoes a great job of explaining each command in detail. valkey-py attempts\nto adhere to the official command syntax. There are a few exceptions:\n\n- **MULTI/EXEC**: These are implemented as part of the Pipeline class.\n The pipeline is wrapped with the MULTI and EXEC statements by\n default when it is executed, which can be disabled by specifying\n transaction=False. See more about Pipelines below.\n\n- **SUBSCRIBE/LISTEN**: Similar to pipelines, PubSub is implemented as\n a separate class as it places the underlying connection in a state\n where it can\\'t execute non-pubsub commands. Calling the pubsub\n method from the Valkey client will return a PubSub instance where you\n can subscribe to channels and listen for messages. You can only call\n PUBLISH from the Valkey client (see [this comment on issue\n #151](https://github.com/redis/redis-py/issues/151#issuecomment-1545015)\n for details).\n\nFor more details, please see the documentation on [advanced topics page](https://valkey-py.readthedocs.io/en/latest/advanced_features.html).\n\n### Pipelines\n\nThe following is a basic example of a [Valkey pipeline](https://redis.io/docs/manual/pipelining/), a method to optimize round-trip calls, by batching Valkey commands, and receiving their results as a list.\n\n\n``` python\n>>> pipe = r.pipeline()\n>>> pipe.set('foo', 5)\n>>> pipe.set('bar', 18.5)\n>>> pipe.set('blee', \"hello world!\")\n>>> pipe.execute()\n[True, True, True]\n```\n\n### PubSub\n\nThe following example shows how to utilize [Valkey Pub/Sub](https://redis.io/docs/manual/pubsub/) to subscribe to specific channels.\n\n``` python\n>>> r = valkey.Valkey(...)\n>>> p = r.pubsub()\n>>> p.subscribe('my-first-channel', 'my-second-channel', ...)\n>>> p.get_message()\n{'pattern': None, 'type': 'subscribe', 'channel': b'my-second-channel', 'data': 1}\n```\n\n\n--------------------------\n\n### Author\n\nvalkey-py can be found [here](\nhttps://github.com/valkey-io/valkey-py), or downloaded from [pypi](https://pypi.org/project/valkey/).\nIt was created as a fork of [redis-py](https://github.com/redis/redis-py)\n\nSpecial thanks to:\n\n- Andy McCurdy (<sedrik@gmail.com>) the original author of redis-py.\n- Ludovico Magnocavallo, author of the original Python Redis client,\n from which some of the socket code is still used.\n- Alexander Solovyov for ideas on the generic response callback\n system.\n- Paul Hubbard for initial packaging support in redis-py.\n\n[](https://valkey.io/)\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for Valkey forked from redis-py",
"version": "6.0.2",
"project_urls": {
"Changes": "https://github.com/valkey-io/valkey-py/releases",
"Code": "https://github.com/valkey-io/valkey-py",
"Documentation": "https://valkey-py.readthedocs.io/en/latest/",
"Homepage": "https://github.com/valkey-io/valkey-py",
"Issue tracker": "https://github.com/valkey-io/valkey-py/issues"
},
"split_keywords": [
"valkey",
" key-value store",
" database"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d7cbb1eac0fe9cbdbba0a5cf189f5778fe54ba7d7c9f26c2f62ca8d759b38f52",
"md5": "ec38497b50d1c36e95cddb1fb3f53a31",
"sha256": "dbbdd65439ee0dc5689502c54f1899504cc7268e85cb7fe8935f062178ff5805"
},
"downloads": -1,
"filename": "valkey-6.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ec38497b50d1c36e95cddb1fb3f53a31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 260101,
"upload_time": "2024-09-11T11:54:02",
"upload_time_iso_8601": "2024-09-11T11:54:02.963475Z",
"url": "https://files.pythonhosted.org/packages/d7/cb/b1eac0fe9cbdbba0a5cf189f5778fe54ba7d7c9f26c2f62ca8d759b38f52/valkey-6.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "45f7b552b7a67017e6233cd8a3b783ce8c4b548e29df98daedd7fb4c4c2cc8f8",
"md5": "284fa719744eff425bcff5bffec082a2",
"sha256": "dc2e91512b82d1da0b91ab0cdbd8c97c0c0250281728cb32f9398760df9caeae"
},
"downloads": -1,
"filename": "valkey-6.0.2.tar.gz",
"has_sig": false,
"md5_digest": "284fa719744eff425bcff5bffec082a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 4602149,
"upload_time": "2024-09-11T11:54:05",
"upload_time_iso_8601": "2024-09-11T11:54:05.014693Z",
"url": "https://files.pythonhosted.org/packages/45/f7/b552b7a67017e6233cd8a3b783ce8c4b548e29df98daedd7fb4c4c2cc8f8/valkey-6.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-11 11:54:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "valkey-io",
"github_project": "valkey-py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "async-timeout",
"specs": [
[
">=",
"4.0.3"
]
]
}
],
"lcname": "valkey"
}
JSON
