| Name | upstash-redis-a JSON |
| Version |
0.1.14
JSON |
| download |
| home_page | |
| Summary | |
| upload_time | 2023-06-19 02:20:53 |
| maintainer | |
| docs_url | None |
| author | Zgîmbău Tudor |
| requires_python | >=3.8,<4.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Upstash Redis - python edition
upstash-redis is a connectionless, HTTP-based Redis client for python, designed to be used in serverless and serverful environments such as:
- AWS Lambda
- Google Cloud Functions
- and other environments where HTTP is preferred over TCP.
Inspired by other Redis clients like [@upstash/redis](https://github.com/upstash/upstash-redis) and [redis-py](https://github.com/redis/redis-py),
the goal of this SDK is to provide a simple, dx-enchanted way to use Redis in HTTP-based environments and not only.
It is `async-based` and supports `typing` features.
The SDK is currently compatible with python 3.10 and above.
<!-- toc -->
- [Quick Start](#quick-start)
- [Install](#install)
- [PyPi](#PyPi)
- [Usage](#usage)
- [Command groups](#command-groups)
- [BITFIELD and BITFIELD_RO](#bitfield-and-bitfieldro)
- [Custom commands](#custom-commands)
- [Telemetry](#telemetry)
- [Encoding](#encoding)
- [Retry mechanism](#retry-mechanism)
- [Formatting returns](#formatting-returns)
- [Contributing](#contributing)
- [Preparing the environment](#preparing-the-environment)
- [Config](#config)
- [Adding new commands](#adding-new-commands)
- [Testing](#testing)
- [Releasing](#releasing)
- [Important](#important)
<!-- tocstop -->
# Quick Start
## Install
### PyPi
```bash
pip install upstash-redis
```
If you are using a packaging and dependency management tool like [Poetry](https://python-poetry.org), you might want to check
the respective docs in regard to adding a dependency. For example, in a Poetry-managed virtual environment, you can use
```bash
poetry add upstash-redis
```
## Usage
To be able to use upstash-redis, you need to create a database on [Upstash](https://console.upstash.com/)
and grab `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` from the console.
```python
from upstash_redis.client import Redis
redis = Redis(url="UPSTASH_REDIS_REST_URL", token="UPSTASH_REDIS_REST_TOKEN")
```
Or, if you want to automatically load the credentials from the environment:
```python
from upstash_redis.client import Redis
redis = Redis.from_env()
```
upstash-redis uses [aiohttp](https://docs.aiohttp.org/en/stable/) for handling the HTTP calls.
If you are interested in the low-level aspects of how requests are performed, check the [aiohttp docs](https://docs.aiohttp.org/en/stable/http_request_lifecycle.html).
If not, all you need to know is that the `Redis` class acts both as a command grouper and as an [async context manager](https://superfastpython.com/asynchronous-context-manager/).
If you are in a serverless environment that allows it, it's also recommended to initialise the client outside the request handler
to be reused while your function is still hot.
Running commands might look like this:
```python
from upstash_redis.client import Redis
from asyncio import run
redis = Redis.from_env()
async def main():
async with redis:
await redis.set("a", "b")
print(await redis.get("a"))
run(main())
```
### Command groups
Most of the command groups, such as `PUBSUB` and `SCRIPT`, are available as an instance attribute of the `Redis` class.
```python
await redis.pubsub.channels()
await redis.script.flush(mode="ASYNC")
```
### BITFIELD and BITFIELD_RO
One particular case is represented by these two chained commands, which are available as functions that return an instance of
the `BITFIELD` and, respectively, `BITFIELD_RO` classes. Use the `execute` function to run the commands.
```python
await (
redis.bitfield("test_key")
.incrby(encoding="i8", offset=100, increment=100)
.overflow("SAT")
.incrby(encoding="i8", offset=100, increment=100)
.execute()
)
await (
redis.bitfield_ro("test_key_2")
.get(encoding="u8", offset=0)
.get(encoding="u8", offset="#1")
.execute()
)
```
### Custom commands
If you want to run a command that hasn't been implemented, you can use the `run` function of your client instance
and pass the command as `list`
```python
await redis.run(command=["XLEN", "test_stream"])
```
If you want to have more control over your session management or need to use multiple custom values, use
the [execute](./upstash_redis/http/execute.py) function directly.
# Telemetry
The SDK can collect the following anonymous telemetry:
- the runtime (ex: `python@v.3.10.0`)
- the SDK or SDKs you're using (ex: `upstash-redisy@development, upstash-ratelimit@v.0.1.0`)
- the platform you're running on (ex: `AWS-lambda`)
If you want to opt out, simply set `allow_telemetry` to `False` in the `Redis` constructor or the `from_env` class method.
# Encoding
Although Redis can store invalid JSON data, there might be problems with the deserialization.
To avoid this, the Upstash REST proxy is capable of encoding the data as base64 on the server and then sending it to the client to be
decoded.
For very large data, this can add a few milliseconds in latency. So, if you're sure that your data is valid JSON, you can set
`rest_encoding` to `False`.
# Retry mechanism
upstash-redis has a fallback mechanism in case of network or API issues. By default, if a request fails it'll retry once, 3 seconds
after the error. If you want to customize that, set `rest_retries` and `rest_retry_interval` (in seconds).
# Formatting returns
The SDK relies on the Upstash REST proxy, which returns the `RESP2` responses of the given commands.
By default, we apply formatting to some of them to provide a better developer experience.
If you want the commands to output the raw return, set `format_return` to `False`.
You can also opt out of individual commands:
```python
redis.format_return = False
print(await redis.copy(source="source_string", destination="destination_string"))
redis.format_return = True
```
One particular formatting feature is the `return_cursor` of the `SCAN`-related commands.
If it is `False`, only the list of results will be returned.
# Contributing
## Preparing the environment
This project uses [Poetry](https://python-poetry.org) for packaging and dependency management.
See [this](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) for a detailed explanation on how
to work with the virtual environment.
You will also need a database on [Upstash](https://console.upstash.com/).
## Config
Most of the config variables and defaults are stored in [config.py](./upstash_redis/config.py).
The defaults for telemetry are set directly in the [execute](./upstash_redis/http/execute.py) function.
# Adding new commands
Commands should try to have a developer-friendly signature and each deviation from the Redis API must be documented with
docstrings.
To increase the DX even more, the commands should try to raise exceptions whenever parameters logics is misunderstood
and can't be deducted simply from the types. Example: `bitcount` in [client.py](./upstash_redis/client.py)
The goal is to also isolate the complex formatting functions from the commands themselves.
For chained (ex: [BITFIELD](https://redis.io/commands/bitfield/)) or semantically-grouped (ex: `SCRIPT {command}`) commands, a
separate class should be created.
# Testing
upstash-redis aims to have a simple and reliable testing strategy, defining cases based on both the signature of the commands
and their desired behaviour. Why is this important? Because testing almost any possible command form when the parameters logic
doesn't change is more like testing the REST API, not only the client.
Tests should use named parameters wherever it may improve readability and should use the [execute_on_http](./tests/execute_on_http.py)
function directly instead of the SDK itself whenever an extra command is needed to ensure atomicity.
There is also the [prepare_database](./tests/prepare_database.py) script whose goal is to flush and then seed the selected testing
database with the required keys. In this way, no random values have to be used.
To run all the tests, make sure you are in the tests folder and have the poetry virtual environment activated with all the necessary
dependencies and set the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` environment variables.
Prepare the database (running this will empty your destination database):
```bash
poetry run python prepare_database.py
```
Run the tests:
```bash
poetry run pytest
```
# Releasing
To create a new release, first use Poetry's [version](https://python-poetry.org/docs/cli/#version) command.
You will then need to connect your PyPi API token to Poetry.
A simple tutorial showcasing how to do it was posted by Tony Tran
[on DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-publish-python-packages-to-pypi-using-poetry-on-ubuntu-22-04)
From there, use `poetry publish --build`.
# Important!
This branch's role is to provide a python 3.10-compatible version to allow the use
in platforms such as AWS Lambda.
For that to be possible, some typing features like the "Self" type and the Generic
TypedDict were removed.
Currently, this is the only branch from which the SDK is released, and it holds the
version used by the rate-limit SDK too.
Raw data
{
"_id": null,
"home_page": "",
"name": "upstash-redis-a",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Zg\u00eemb\u0103u Tudor",
"author_email": "tudor.zgimbau@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e2/67/159548a8d293adcffe4c83f3e6782f585c473364de76238dd050e9703cfa/upstash_redis_a-0.1.14.tar.gz",
"platform": null,
"description": "# Upstash Redis - python edition\n\nupstash-redis is a connectionless, HTTP-based Redis client for python, designed to be used in serverless and serverful environments such as:\n- AWS Lambda\n- Google Cloud Functions\n- and other environments where HTTP is preferred over TCP.\n\nInspired by other Redis clients like [@upstash/redis](https://github.com/upstash/upstash-redis) and [redis-py](https://github.com/redis/redis-py),\nthe goal of this SDK is to provide a simple, dx-enchanted way to use Redis in HTTP-based environments and not only.\n\nIt is `async-based` and supports `typing` features.\n\nThe SDK is currently compatible with python 3.10 and above.\n\n<!-- toc -->\n\n- [Quick Start](#quick-start)\n - [Install](#install)\n - [PyPi](#PyPi)\n - [Usage](#usage)\n - [Command groups](#command-groups)\n - [BITFIELD and BITFIELD_RO](#bitfield-and-bitfieldro)\n - [Custom commands](#custom-commands)\n - [Telemetry](#telemetry)\n- [Encoding](#encoding)\n- [Retry mechanism](#retry-mechanism)\n- [Formatting returns](#formatting-returns)\n- [Contributing](#contributing)\n - [Preparing the environment](#preparing-the-environment)\n - [Config](#config)\n - [Adding new commands](#adding-new-commands)\n - [Testing](#testing)\n - [Releasing](#releasing)\n- [Important](#important)\n\n<!-- tocstop -->\n\n# Quick Start\n\n## Install\n\n### PyPi\n```bash\npip install upstash-redis\n```\n\nIf you are using a packaging and dependency management tool like [Poetry](https://python-poetry.org), you might want to check\nthe respective docs in regard to adding a dependency. For example, in a Poetry-managed virtual environment, you can use\n```bash\npoetry add upstash-redis\n```\n\n\n## Usage\nTo be able to use upstash-redis, you need to create a database on [Upstash](https://console.upstash.com/)\nand grab `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` from the console.\n\n```python\nfrom upstash_redis.client import Redis\n\nredis = Redis(url=\"UPSTASH_REDIS_REST_URL\", token=\"UPSTASH_REDIS_REST_TOKEN\")\n```\n\nOr, if you want to automatically load the credentials from the environment:\n\n```python\nfrom upstash_redis.client import Redis\n\nredis = Redis.from_env()\n```\n\nupstash-redis uses [aiohttp](https://docs.aiohttp.org/en/stable/) for handling the HTTP calls.\nIf you are interested in the low-level aspects of how requests are performed, check the [aiohttp docs](https://docs.aiohttp.org/en/stable/http_request_lifecycle.html).\nIf not, all you need to know is that the `Redis` class acts both as a command grouper and as an [async context manager](https://superfastpython.com/asynchronous-context-manager/).\n\nIf you are in a serverless environment that allows it, it's also recommended to initialise the client outside the request handler\nto be reused while your function is still hot.\n\nRunning commands might look like this:\n\n```python\nfrom upstash_redis.client import Redis\nfrom asyncio import run\n\nredis = Redis.from_env()\n\n\nasync def main():\n async with redis:\n await redis.set(\"a\", \"b\")\n print(await redis.get(\"a\"))\n\nrun(main())\n\n```\n\n### Command groups\nMost of the command groups, such as `PUBSUB` and `SCRIPT`, are available as an instance attribute of the `Redis` class.\n\n```python\nawait redis.pubsub.channels()\n\nawait redis.script.flush(mode=\"ASYNC\")\n```\n\n\n### BITFIELD and BITFIELD_RO\nOne particular case is represented by these two chained commands, which are available as functions that return an instance of \nthe `BITFIELD` and, respectively, `BITFIELD_RO` classes. Use the `execute` function to run the commands.\n\n```python\nawait (\n redis.bitfield(\"test_key\")\n .incrby(encoding=\"i8\", offset=100, increment=100)\n .overflow(\"SAT\")\n .incrby(encoding=\"i8\", offset=100, increment=100)\n .execute()\n)\n\nawait (\n redis.bitfield_ro(\"test_key_2\")\n .get(encoding=\"u8\", offset=0)\n .get(encoding=\"u8\", offset=\"#1\")\n .execute()\n)\n```\n\n\n### Custom commands\nIf you want to run a command that hasn't been implemented, you can use the `run` function of your client instance\nand pass the command as `list`\n\n```python\nawait redis.run(command=[\"XLEN\", \"test_stream\"])\n```\n\nIf you want to have more control over your session management or need to use multiple custom values, use\nthe [execute](./upstash_redis/http/execute.py) function directly.\n\n\n# Telemetry\nThe SDK can collect the following anonymous telemetry:\n - the runtime (ex: `python@v.3.10.0`)\n - the SDK or SDKs you're using (ex: `upstash-redisy@development, upstash-ratelimit@v.0.1.0`)\n - the platform you're running on (ex: `AWS-lambda`)\n\nIf you want to opt out, simply set `allow_telemetry` to `False` in the `Redis` constructor or the `from_env` class method.\n\n\n# Encoding\nAlthough Redis can store invalid JSON data, there might be problems with the deserialization.\nTo avoid this, the Upstash REST proxy is capable of encoding the data as base64 on the server and then sending it to the client to be\ndecoded. \n\nFor very large data, this can add a few milliseconds in latency. So, if you're sure that your data is valid JSON, you can set\n`rest_encoding` to `False`.\n\n\n# Retry mechanism\nupstash-redis has a fallback mechanism in case of network or API issues. By default, if a request fails it'll retry once, 3 seconds \nafter the error. If you want to customize that, set `rest_retries` and `rest_retry_interval` (in seconds).\n\n\n# Formatting returns\nThe SDK relies on the Upstash REST proxy, which returns the `RESP2` responses of the given commands.\nBy default, we apply formatting to some of them to provide a better developer experience.\nIf you want the commands to output the raw return, set `format_return` to `False`.\n\nYou can also opt out of individual commands:\n\n```python\nredis.format_return = False\n\nprint(await redis.copy(source=\"source_string\", destination=\"destination_string\"))\n\nredis.format_return = True\n```\n\nOne particular formatting feature is the `return_cursor` of the `SCAN`-related commands.\nIf it is `False`, only the list of results will be returned.\n\n\n# Contributing\n\n## Preparing the environment\nThis project uses [Poetry](https://python-poetry.org) for packaging and dependency management. \n\nSee [this](https://python-poetry.org/docs/basic-usage/#using-your-virtual-environment) for a detailed explanation on how\nto work with the virtual environment.\n\nYou will also need a database on [Upstash](https://console.upstash.com/).\n\n\n## Config\nMost of the config variables and defaults are stored in [config.py](./upstash_redis/config.py).\n\nThe defaults for telemetry are set directly in the [execute](./upstash_redis/http/execute.py) function.\n\n\n# Adding new commands\nCommands should try to have a developer-friendly signature and each deviation from the Redis API must be documented with\ndocstrings.\n\nTo increase the DX even more, the commands should try to raise exceptions whenever parameters logics is misunderstood\nand can't be deducted simply from the types. Example: `bitcount` in [client.py](./upstash_redis/client.py)\n\nThe goal is to also isolate the complex formatting functions from the commands themselves.\n\nFor chained (ex: [BITFIELD](https://redis.io/commands/bitfield/)) or semantically-grouped (ex: `SCRIPT {command}`) commands, a\nseparate class should be created.\n\n\n# Testing\nupstash-redis aims to have a simple and reliable testing strategy, defining cases based on both the signature of the commands\nand their desired behaviour. Why is this important? Because testing almost any possible command form when the parameters logic \ndoesn't change is more like testing the REST API, not only the client.\n\nTests should use named parameters wherever it may improve readability and should use the [execute_on_http](./tests/execute_on_http.py)\nfunction directly instead of the SDK itself whenever an extra command is needed to ensure atomicity.\n\nThere is also the [prepare_database](./tests/prepare_database.py) script whose goal is to flush and then seed the selected testing\ndatabase with the required keys. In this way, no random values have to be used.\n\nTo run all the tests, make sure you are in the tests folder and have the poetry virtual environment activated with all the necessary \ndependencies and set the `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` environment variables.\n\nPrepare the database (running this will empty your destination database):\n\n```bash\npoetry run python prepare_database.py\n```\n\nRun the tests:\n\n```bash\npoetry run pytest\n```\n\n\n# Releasing\nTo create a new release, first use Poetry's [version](https://python-poetry.org/docs/cli/#version) command.\n\nYou will then need to connect your PyPi API token to Poetry. \nA simple tutorial showcasing how to do it was posted by Tony Tran\n[on DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-publish-python-packages-to-pypi-using-poetry-on-ubuntu-22-04)\n\nFrom there, use `poetry publish --build`.\n\n\n# Important!\nThis branch's role is to provide a python 3.10-compatible version to allow the use\nin platforms such as AWS Lambda.\n\nFor that to be possible, some typing features like the \"Self\" type and the Generic \nTypedDict were removed.\n\nCurrently, this is the only branch from which the SDK is released, and it holds the\nversion used by the rate-limit SDK too.",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "0.1.14",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c5cdc0bf1030f66f8743b89ecbf8b75cf74dabb217c31d250f275add045853c",
"md5": "9509d58cf8e531f20a7aeca7ccbc052d",
"sha256": "010b1f8afb6e20c08d3558682fce2ce5d66c94a45715a0b3026a1d3342d77e9e"
},
"downloads": -1,
"filename": "upstash_redis_a-0.1.14-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9509d58cf8e531f20a7aeca7ccbc052d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 23809,
"upload_time": "2023-06-19T02:20:48",
"upload_time_iso_8601": "2023-06-19T02:20:48.347598Z",
"url": "https://files.pythonhosted.org/packages/8c/5c/dc0bf1030f66f8743b89ecbf8b75cf74dabb217c31d250f275add045853c/upstash_redis_a-0.1.14-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e267159548a8d293adcffe4c83f3e6782f585c473364de76238dd050e9703cfa",
"md5": "648955ea42145d4c1b49aba99707e9fe",
"sha256": "14b5e1ae7fc3f6d1deaeee9948e89751b423776d43f1b8531bbf633e1c612bbb"
},
"downloads": -1,
"filename": "upstash_redis_a-0.1.14.tar.gz",
"has_sig": false,
"md5_digest": "648955ea42145d4c1b49aba99707e9fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 23473,
"upload_time": "2023-06-19T02:20:53",
"upload_time_iso_8601": "2023-06-19T02:20:53.238286Z",
"url": "https://files.pythonhosted.org/packages/e2/67/159548a8d293adcffe4c83f3e6782f585c473364de76238dd050e9703cfa/upstash_redis_a-0.1.14.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-19 02:20:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "upstash-redis-a"
}
