# Purse
High-Level Async-IO Python interface for Redis >6.0.x that provides useful Pythonic abstractions to simplify
the usage of Redis as a non-blocking Caching layer, or even as a first-class non-blocking datastore.
Influenced and Inspired by the great library [pottery](https://github.com/brainix/pottery), with
a few differences in objectives and implementation detail.
* ``purse`` is strictly an Async-IO library that utilizes the redis library.
* ``purse`` tries to adhere as much as possible to familiar APIs and idioms used with familiar python structures
(``dict``, ``set``, ``list`` among others), but deviates from those conventions in many instances:
* Due to the ``async/await`` nature of the API, it is difficult and sometimes impossible to use python language constructs such as ``myhash["key"] = "value"`` -
as of Python 3.10, the language simply doesn't provide async-io methods for those operations and idioms
* ``purse`` tries to expose, as much as possible, Redis rich features such as key TTL and pattern matching, among others
Optionally, collections in this library use [pydantic](https://github.com/samuelcolvin/pydantic)
to serialize, validate, and deserialize Python Models part of all data storage and retrieval operations
# installation
with pip
```bash
pip install redis-purse
```
# Basic Usage
## RedisList
RedisList provides an API that provides most methods and features of the python ``list`` and ``deque``
```python
import asyncio
from purse.collections import RedisList
from redis.asyncio import Redis
async def main():
local_list = ['a', 'b', 'c', 'd', 'e', 'f']
# local Redis >= 6.0.x plain connection with default params
red_con = Redis()
redis_key = 'redis_list'
# The value_type defines the class to serialize to and from
redis_list = RedisList(redis=red_con, rkey=redis_key, value_type=str)
# Clear the list, in case it was previously populated
await redis_list.clear()
# extend a Redis list with a Python list
await redis_list.extend(local_list)
# async list comprehension
print([x async for x in redis_list])
# contains
print(await redis_list.contains('f')) # True
print(await redis_list.contains('g')) # False
# getting the index of a value
print(await redis_list.index('c')) # 2
print(await redis_list.index('g')) # None, unlike a Python list that raises a ValueError
# slicing
print(await redis_list.slice(2, 5)) # ['c', 'd', 'e']
# inserting values
await redis_list.insert(2, 'x')
await redis_list.insert(-2, 'y')
# getitem
assert await redis_list.getitem(2) == 'x'
assert await redis_list.getitem(-3) == 'y'
# some deque methods
await redis_list.appendleft('z')
await redis_list.pop()
await redis_list.popleft()
asyncio.run(main())
```
## RedisHash
Provides most of the functionality of the Python ``dict``.
```python
import asyncio
from purse.collections import RedisHash
from redis.asyncio import Redis
from pydantic import BaseModel
async def main():
# Pydantic Model
class Plant(BaseModel):
name: str
healthiness: float
tasty: bool
red_con = Redis()
redis_key = 'redis_hash'
# This class serializes and deserializes Plant Model objects when storing and retrieving data
redis_hash = RedisHash(red_con, redis_key, Plant)
await redis_hash.clear()
plants = [
Plant(name="spinach", healthiness=9.8, tasty=False),
Plant(name="broccoli", healthiness=12.2, tasty=True),
Plant(name="lettuce", healthiness=3, tasty=False),
Plant(name="avocado", healthiness=8, tasty=True),
]
# update redis hash with a python dict
await redis_hash.update({p.name: p for p in plants})
await redis_hash.set("carrot", Plant(name="carrot", healthiness=5, tasty=False))
print(await redis_hash.len()) # currently 5 mappings in total
# RedisHash is a generic type with supports IDE intellisense and type hints
p: Plant = await redis_hash.get('spinach')
print(p.tasty) # False
# async for syntax
async for name, plant in redis_hash.items():
print(name, plant)
asyncio.run(main())
```
## Redlock
Distributed, None-blocking Lock implementation according to the algorithm and logic described here
https://redis.io/topics/distlock, and closely resembling the python implementation here
https://github.com/brainix/pottery/blob/master/pottery/redlock.py.
This none-blocking implementation is particularly efficient and attractive when a real world
distributed application is using many distributed locks over many Redis Masters,
to synchronize on many Network Resources simultaneously, due to the very small overhead associated with
asyncio tasks, and any "waiting" that may need to happen to acquire locks, since all of the above
is happening efficiently on an event-queue.
This example uses 5 Redis databases on the localhost as the Redlock Masters, to synchronize on
the access of a RedisList, where multiple tasks are concurrently synchronizing getting, incrementing and appending
to the last numerical item of that Redis List, with some asyncio delay to simulate real world
latencies and data processing times.
```python
import asyncio
from purse.redlock import Redlock
from purse.collections import RedisList
from redis.asyncio import Redis
from random import random
# The main Redis Store that contains the data that need synchronization
redis_store = Redis(db=0)
# The Redis Masters for the async Redlock
# Highly Recommended to be an odd number of masters: typically 1, 3 or 5 masters
redlock_masters = [Redis(db=x) for x in range(5)]
async def do_job(n):
rlock = Redlock("redlock:list_lock", redlock_masters)
rlist = RedisList(redis_store, "redis_list", str)
for x in range(n):
async with rlock:
cl = await rlist.len()
if cl == 0:
await rlist.append("0")
current_num = 0
else:
current_num = int(await rlist.getitem(-1))
# This sleep simulates the processing time of the job - up to 100ms here
await asyncio.sleep(0.1 * random())
# Get the job done, which is add 1 to the last number
current_num += 1
print(f"the task {asyncio.current_task().get_name()} working on item #: {current_num}")
await rlist.append(str(current_num))
async def main():
rlist = RedisList(redis_store, "redis_list", str)
await rlist.clear()
# run 10 async threads (or tasks) in parallel, each one to perform 10 increments
await asyncio.gather(
*[asyncio.create_task(do_job(10)) for _ in range(10)]
)
# should print 0 to 100 in order, which means synchronization has happened
async for item in rlist:
print(item)
return "success"
asyncio.run(main())
```
Raw data
{
"_id": null,
"home_page": "https://plataux.com",
"name": "redis-purse",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4",
"maintainer_email": "",
"keywords": "key-value,caching,messaging",
"author": "mk",
"author_email": "mk@plataux.com",
"download_url": "https://files.pythonhosted.org/packages/59/58/a37bbb8447b0bfe3ead4b6675172459800aa0b2d4adf21ea119f68f2e3b9/redis_purse-2.0.0.tar.gz",
"platform": null,
"description": "\n# Purse\n\nHigh-Level Async-IO Python interface for Redis >6.0.x that provides useful Pythonic abstractions to simplify \nthe usage of Redis as a non-blocking Caching layer, or even as a first-class non-blocking datastore.\n\nInfluenced and Inspired by the great library [pottery](https://github.com/brainix/pottery), with\na few differences in objectives and implementation detail.\n\n* ``purse`` is strictly an Async-IO library that utilizes the redis library.\n* ``purse`` tries to adhere as much as possible to familiar APIs and idioms used with familiar python structures\n (``dict``, ``set``, ``list`` among others), but deviates from those conventions in many instances:\n * Due to the ``async/await`` nature of the API, it is difficult and sometimes impossible to use python language constructs such as ``myhash[\"key\"] = \"value\"`` - \n as of Python 3.10, the language simply doesn't provide async-io methods for those operations and idioms \n * ``purse`` tries to expose, as much as possible, Redis rich features such as key TTL and pattern matching, among others\n\nOptionally, collections in this library use [pydantic](https://github.com/samuelcolvin/pydantic) \nto serialize, validate, and deserialize Python Models part of all data storage and retrieval operations\n\n# installation\n\nwith pip\n\n```bash\npip install redis-purse\n```\n\n# Basic Usage\n\n## RedisList\n\nRedisList provides an API that provides most methods and features of the python ``list`` and ``deque``\n\n```python\nimport asyncio\nfrom purse.collections import RedisList\nfrom redis.asyncio import Redis\n\n\nasync def main():\n local_list = ['a', 'b', 'c', 'd', 'e', 'f']\n\n # local Redis >= 6.0.x plain connection with default params\n red_con = Redis()\n redis_key = 'redis_list'\n\n # The value_type defines the class to serialize to and from\n redis_list = RedisList(redis=red_con, rkey=redis_key, value_type=str)\n\n # Clear the list, in case it was previously populated\n await redis_list.clear()\n\n # extend a Redis list with a Python list\n await redis_list.extend(local_list)\n\n # async list comprehension\n print([x async for x in redis_list])\n\n # contains\n print(await redis_list.contains('f')) # True\n print(await redis_list.contains('g')) # False\n\n # getting the index of a value\n print(await redis_list.index('c')) # 2\n print(await redis_list.index('g')) # None, unlike a Python list that raises a ValueError\n\n # slicing\n print(await redis_list.slice(2, 5)) # ['c', 'd', 'e']\n\n # inserting values\n await redis_list.insert(2, 'x')\n await redis_list.insert(-2, 'y')\n\n # getitem\n assert await redis_list.getitem(2) == 'x'\n assert await redis_list.getitem(-3) == 'y'\n\n # some deque methods\n await redis_list.appendleft('z')\n await redis_list.pop()\n await redis_list.popleft()\n\nasyncio.run(main())\n```\n\n## RedisHash\n\nProvides most of the functionality of the Python ``dict``. \n\n```python\nimport asyncio\nfrom purse.collections import RedisHash\nfrom redis.asyncio import Redis\nfrom pydantic import BaseModel\n\n\nasync def main():\n # Pydantic Model\n class Plant(BaseModel):\n name: str\n healthiness: float\n tasty: bool\n\n red_con = Redis()\n redis_key = 'redis_hash'\n\n # This class serializes and deserializes Plant Model objects when storing and retrieving data\n redis_hash = RedisHash(red_con, redis_key, Plant)\n await redis_hash.clear()\n\n plants = [\n Plant(name=\"spinach\", healthiness=9.8, tasty=False),\n Plant(name=\"broccoli\", healthiness=12.2, tasty=True),\n Plant(name=\"lettuce\", healthiness=3, tasty=False),\n Plant(name=\"avocado\", healthiness=8, tasty=True),\n ]\n\n # update redis hash with a python dict\n await redis_hash.update({p.name: p for p in plants})\n\n await redis_hash.set(\"carrot\", Plant(name=\"carrot\", healthiness=5, tasty=False))\n\n print(await redis_hash.len()) # currently 5 mappings in total\n \n # RedisHash is a generic type with supports IDE intellisense and type hints\n p: Plant = await redis_hash.get('spinach')\n \n print(p.tasty) # False\n \n # async for syntax\n async for name, plant in redis_hash.items():\n print(name, plant)\n\nasyncio.run(main())\n```\n\n## Redlock\n\nDistributed, None-blocking Lock implementation according to the algorithm and logic described here\nhttps://redis.io/topics/distlock, and closely resembling the python implementation here\nhttps://github.com/brainix/pottery/blob/master/pottery/redlock.py.\n\nThis none-blocking implementation is particularly efficient and attractive when a real world\ndistributed application is using many distributed locks over many Redis Masters,\nto synchronize on many Network Resources simultaneously, due to the very small overhead associated with\nasyncio tasks, and any \"waiting\" that may need to happen to acquire locks, since all of the above\nis happening efficiently on an event-queue.\n\nThis example uses 5 Redis databases on the localhost as the Redlock Masters, to synchronize on\nthe access of a RedisList, where multiple tasks are concurrently synchronizing getting, incrementing and appending\nto the last numerical item of that Redis List, with some asyncio delay to simulate real world\nlatencies and data processing times.\n\n```python\nimport asyncio\nfrom purse.redlock import Redlock\nfrom purse.collections import RedisList\nfrom redis.asyncio import Redis\nfrom random import random\n\n# The main Redis Store that contains the data that need synchronization\nredis_store = Redis(db=0)\n\n# The Redis Masters for the async Redlock\n# Highly Recommended to be an odd number of masters: typically 1, 3 or 5 masters\nredlock_masters = [Redis(db=x) for x in range(5)]\n\n\nasync def do_job(n):\n\n rlock = Redlock(\"redlock:list_lock\", redlock_masters)\n rlist = RedisList(redis_store, \"redis_list\", str)\n\n for x in range(n):\n async with rlock:\n cl = await rlist.len()\n\n if cl == 0:\n await rlist.append(\"0\")\n current_num = 0\n else:\n current_num = int(await rlist.getitem(-1))\n\n # This sleep simulates the processing time of the job - up to 100ms here\n await asyncio.sleep(0.1 * random())\n\n # Get the job done, which is add 1 to the last number\n current_num += 1\n\n print(f\"the task {asyncio.current_task().get_name()} working on item #: {current_num}\")\n\n await rlist.append(str(current_num))\n\n\nasync def main():\n rlist = RedisList(redis_store, \"redis_list\", str)\n await rlist.clear()\n\n # run 10 async threads (or tasks) in parallel, each one to perform 10 increments\n await asyncio.gather(\n *[asyncio.create_task(do_job(10)) for _ in range(10)]\n )\n\n # should print 0 to 100 in order, which means synchronization has happened\n async for item in rlist:\n print(item)\n\n return \"success\"\n\nasyncio.run(main())\n```\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "High Level Asyncio interface to redis",
"version": "2.0.0",
"project_urls": {
"Homepage": "https://plataux.com",
"Repository": "https://github.com/plataux/purse"
},
"split_keywords": [
"key-value",
"caching",
"messaging"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "edcf7865d6ee5361224dc8d74086c5fd5ad40e5020e6f38c04b1cb49f7420e38",
"md5": "f6f528ae6796b0000f3a8d0594db3757",
"sha256": "57d771a83bb4b6b3b638136ff02368313716f315acc79e3e1a8b6062bfd64406"
},
"downloads": -1,
"filename": "redis_purse-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f6f528ae6796b0000f3a8d0594db3757",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4",
"size": 19621,
"upload_time": "2023-08-24T10:36:54",
"upload_time_iso_8601": "2023-08-24T10:36:54.926857Z",
"url": "https://files.pythonhosted.org/packages/ed/cf/7865d6ee5361224dc8d74086c5fd5ad40e5020e6f38c04b1cb49f7420e38/redis_purse-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5958a37bbb8447b0bfe3ead4b6675172459800aa0b2d4adf21ea119f68f2e3b9",
"md5": "802b8bdc0cd56f5c1c504863549644b8",
"sha256": "46a6f1582deb23f902639657f04c45980e22a1283237f8bbca86313a31c08027"
},
"downloads": -1,
"filename": "redis_purse-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "802b8bdc0cd56f5c1c504863549644b8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4",
"size": 21043,
"upload_time": "2023-08-24T10:36:56",
"upload_time_iso_8601": "2023-08-24T10:36:56.105457Z",
"url": "https://files.pythonhosted.org/packages/59/58/a37bbb8447b0bfe3ead4b6675172459800aa0b2d4adf21ea119f68f2e3b9/redis_purse-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-24 10:36:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plataux",
"github_project": "purse",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "redis-purse"
}
JSON
