| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: aiocache |
| 3 |
Version: 0.12.3 |
| 4 |
Summary: multi backend asyncio cache |
| 5 |
Home-page: https://github.com/aio-libs/aiocache |
| 6 |
Author: Manuel Miranda |
| 7 |
Author-email: [email protected] |
| 8 |
Classifier: Programming Language :: Python |
| 9 |
Classifier: Programming Language :: Python :: 3.7 |
| 10 |
Classifier: Programming Language :: Python :: 3.8 |
| 11 |
Classifier: Programming Language :: Python :: 3.9 |
| 12 |
Classifier: Programming Language :: Python :: 3.10 |
| 13 |
Classifier: Programming Language :: Python :: 3.11 |
| 14 |
Classifier: Framework :: AsyncIO |
| 15 |
License-File: LICENSE |
| 16 |
Provides-Extra: redis |
| 17 |
Requires-Dist: redis>=4.2.0; extra == "redis" |
| 18 |
Provides-Extra: memcached |
| 19 |
Requires-Dist: aiomcache>=0.5.2; extra == "memcached" |
| 20 |
Provides-Extra: msgpack |
| 21 |
Requires-Dist: msgpack>=0.5.5; extra == "msgpack" |
| 22 |
|
| 23 |
aiocache |
| 24 |
######## |
| 25 |
|
| 26 |
Asyncio cache supporting multiple backends (memory, redis and memcached). |
| 27 |
|
| 28 |
.. image:: https://travis-ci.org/argaen/aiocache.svg?branch=master |
| 29 |
:target: https://travis-ci.org/argaen/aiocache |
| 30 |
|
| 31 |
.. image:: https://codecov.io/gh/argaen/aiocache/branch/master/graph/badge.svg |
| 32 |
:target: https://codecov.io/gh/argaen/aiocache |
| 33 |
|
| 34 |
.. image:: https://badge.fury.io/py/aiocache.svg |
| 35 |
:target: https://pypi.python.org/pypi/aiocache |
| 36 |
|
| 37 |
.. image:: https://img.shields.io/pypi/pyversions/aiocache.svg |
| 38 |
:target: https://pypi.python.org/pypi/aiocache |
| 39 |
|
| 40 |
.. image:: https://api.codacy.com/project/badge/Grade/96f772e38e63489ca884dbaf6e9fb7fd |
| 41 |
:target: https://www.codacy.com/app/argaen/aiocache |
| 42 |
|
| 43 |
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg |
| 44 |
:target: https://github.com/ambv/black |
| 45 |
|
| 46 |
This library aims for simplicity over specialization. All caches contain the same minimum interface which consists on the following functions: |
| 47 |
|
| 48 |
- ``add``: Only adds key/value if key does not exist. |
| 49 |
- ``get``: Retrieve value identified by key. |
| 50 |
- ``set``: Sets key/value. |
| 51 |
- ``multi_get``: Retrieves multiple key/values. |
| 52 |
- ``multi_set``: Sets multiple key/values. |
| 53 |
- ``exists``: Returns True if key exists False otherwise. |
| 54 |
- ``increment``: Increment the value stored in the given key. |
| 55 |
- ``delete``: Deletes key and returns number of deleted items. |
| 56 |
- ``clear``: Clears the items stored. |
| 57 |
- ``raw``: Executes the specified command using the underlying client. |
| 58 |
|
| 59 |
|
| 60 |
.. role:: python(code) |
| 61 |
:language: python |
| 62 |
|
| 63 |
.. contents:: |
| 64 |
|
| 65 |
.. section-numbering: |
| 66 |
|
| 67 |
|
| 68 |
Installing |
| 69 |
========== |
| 70 |
|
| 71 |
- ``pip install aiocache`` |
| 72 |
- ``pip install aiocache[redis]`` |
| 73 |
- ``pip install aiocache[memcached]`` |
| 74 |
- ``pip install aiocache[redis,memcached]`` |
| 75 |
- ``pip install aiocache[msgpack]`` |
| 76 |
|
| 77 |
|
| 78 |
Usage |
| 79 |
===== |
| 80 |
|
| 81 |
Using a cache is as simple as |
| 82 |
|
| 83 |
.. code-block:: python |
| 84 |
|
| 85 |
>>> import asyncio |
| 86 |
>>> from aiocache import Cache |
| 87 |
>>> cache = Cache(Cache.MEMORY) # Here you can also use Cache.REDIS and Cache.MEMCACHED, default is Cache.MEMORY |
| 88 |
>>> with asyncio.Runner() as runner: |
| 89 |
>>> runner.run(cache.set('key', 'value')) |
| 90 |
True |
| 91 |
>>> runner.run(cache.get('key')) |
| 92 |
'value' |
| 93 |
|
| 94 |
Or as a decorator |
| 95 |
|
| 96 |
.. code-block:: python |
| 97 |
|
| 98 |
import asyncio |
| 99 |
|
| 100 |
from collections import namedtuple |
| 101 |
|
| 102 |
from aiocache import cached, Cache |
| 103 |
from aiocache.serializers import PickleSerializer |
| 104 |
# With this we can store python objects in backends like Redis! |
| 105 |
|
| 106 |
Result = namedtuple('Result', "content, status") |
| 107 |
|
| 108 |
|
| 109 |
@cached( |
| 110 |
ttl=10, cache=Cache.REDIS, key="key", serializer=PickleSerializer(), port=6379, namespace="main") |
| 111 |
async def cached_call(): |
| 112 |
print("Sleeping for three seconds zzzz.....") |
| 113 |
await asyncio.sleep(3) |
| 114 |
return Result("content", 200) |
| 115 |
|
| 116 |
|
| 117 |
async def run(): |
| 118 |
await cached_call() |
| 119 |
await cached_call() |
| 120 |
await cached_call() |
| 121 |
cache = Cache(Cache.REDIS, endpoint="127.0.0.1", port=6379, namespace="main") |
| 122 |
await cache.delete("key") |
| 123 |
|
| 124 |
if __name__ == "__main__": |
| 125 |
asyncio.run(run()) |
| 126 |
|
| 127 |
The recommended approach to instantiate a new cache is using the `Cache` constructor. However you can also instantiate directly using `aiocache.RedisCache`, `aiocache.SimpleMemoryCache` or `aiocache.MemcachedCache`. |
| 128 |
|
| 129 |
|
| 130 |
You can also setup cache aliases so its easy to reuse configurations |
| 131 |
|
| 132 |
.. code-block:: python |
| 133 |
|
| 134 |
import asyncio |
| 135 |
|
| 136 |
from aiocache import caches |
| 137 |
|
| 138 |
# You can use either classes or strings for referencing classes |
| 139 |
caches.set_config({ |
| 140 |
'default': { |
| 141 |
'cache': "aiocache.SimpleMemoryCache", |
| 142 |
'serializer': { |
| 143 |
'class': "aiocache.serializers.StringSerializer" |
| 144 |
} |
| 145 |
}, |
| 146 |
'redis_alt': { |
| 147 |
'cache': "aiocache.RedisCache", |
| 148 |
'endpoint': "127.0.0.1", |
| 149 |
'port': 6379, |
| 150 |
'timeout': 1, |
| 151 |
'serializer': { |
| 152 |
'class': "aiocache.serializers.PickleSerializer" |
| 153 |
}, |
| 154 |
'plugins': [ |
| 155 |
{'class': "aiocache.plugins.HitMissRatioPlugin"}, |
| 156 |
{'class': "aiocache.plugins.TimingPlugin"} |
| 157 |
] |
| 158 |
} |
| 159 |
}) |
| 160 |
|
| 161 |
|
| 162 |
async def default_cache(): |
| 163 |
cache = caches.get('default') # This always returns the SAME instance |
| 164 |
await cache.set("key", "value") |
| 165 |
assert await cache.get("key") == "value" |
| 166 |
|
| 167 |
|
| 168 |
async def alt_cache(): |
| 169 |
cache = caches.create('redis_alt') # This creates a NEW instance on every call |
| 170 |
await cache.set("key", "value") |
| 171 |
assert await cache.get("key") == "value" |
| 172 |
|
| 173 |
|
| 174 |
async def test_alias(): |
| 175 |
await default_cache() |
| 176 |
await alt_cache() |
| 177 |
|
| 178 |
await caches.get("redis_alt").delete("key") |
| 179 |
|
| 180 |
|
| 181 |
if __name__ == "__main__": |
| 182 |
asyncio.run(test_alias()) |
| 183 |
|
| 184 |
|
| 185 |
How does it work |
| 186 |
================ |
| 187 |
|
| 188 |
Aiocache provides 3 main entities: |
| 189 |
|
| 190 |
- **backends**: Allow you specify which backend you want to use for your cache. Currently supporting: SimpleMemoryCache, RedisCache using redis_ and MemCache using aiomcache_. |
| 191 |
- **serializers**: Serialize and deserialize the data between your code and the backends. This allows you to save any Python object into your cache. Currently supporting: StringSerializer, PickleSerializer, JsonSerializer, and MsgPackSerializer. But you can also build custom ones. |
| 192 |
- **plugins**: Implement a hooks system that allows to execute extra behavior before and after of each command. |
| 193 |
|
| 194 |
If you are missing an implementation of backend, serializer or plugin you think it could be interesting for the package, do not hesitate to open a new issue. |
| 195 |
|
| 196 |
.. image:: docs/images/architecture.png |
| 197 |
:align: center |
| 198 |
|
| 199 |
Those 3 entities combine during some of the cache operations to apply the desired command (backend), data transformation (serializer) and pre/post hooks (plugins). To have a better vision of what happens, here you can check how ``set`` function works in ``aiocache``: |
| 200 |
|
| 201 |
.. image:: docs/images/set_operation_flow.png |
| 202 |
:align: center |
| 203 |
|
| 204 |
|
| 205 |
Amazing examples |
| 206 |
================ |
| 207 |
|
| 208 |
In `examples folder <https://github.com/argaen/aiocache/tree/master/examples>`_ you can check different use cases: |
| 209 |
|
| 210 |
- `Sanic, Aiohttp and Tornado <https://github.com/argaen/aiocache/tree/master/examples/frameworks>`_ |
| 211 |
- `Python object in Redis <https://github.com/argaen/aiocache/blob/master/examples/python_object.py>`_ |
| 212 |
- `Custom serializer for compressing data <https://github.com/argaen/aiocache/blob/master/examples/serializer_class.py>`_ |
| 213 |
- `TimingPlugin and HitMissRatioPlugin demos <https://github.com/argaen/aiocache/blob/master/examples/plugins.py>`_ |
| 214 |
- `Using marshmallow as a serializer <https://github.com/argaen/aiocache/blob/master/examples/marshmallow_serializer_class.py>`_ |
| 215 |
- `Using cached decorator <https://github.com/argaen/aiocache/blob/master/examples/cached_decorator.py>`_. |
| 216 |
- `Using multi_cached decorator <https://github.com/argaen/aiocache/blob/master/examples/multicached_decorator.py>`_. |
| 217 |
|
| 218 |
|
| 219 |
|
| 220 |
Documentation |
| 221 |
============= |
| 222 |
|
| 223 |
- `Usage <http://aiocache.readthedocs.io/en/latest>`_ |
| 224 |
- `Caches <http://aiocache.readthedocs.io/en/latest/caches.html>`_ |
| 225 |
- `Serializers <http://aiocache.readthedocs.io/en/latest/serializers.html>`_ |
| 226 |
- `Plugins <http://aiocache.readthedocs.io/en/latest/plugins.html>`_ |
| 227 |
- `Configuration <http://aiocache.readthedocs.io/en/latest/configuration.html>`_ |
| 228 |
- `Decorators <http://aiocache.readthedocs.io/en/latest/decorators.html>`_ |
| 229 |
- `Testing <http://aiocache.readthedocs.io/en/latest/testing.html>`_ |
| 230 |
- `Examples <https://github.com/argaen/aiocache/tree/master/examples>`_ |
| 231 |
|
| 232 |
|
| 233 |
.. _redis: https://github.com/redis/redis-py |
| 234 |
.. _aiomcache: https://github.com/aio-libs/aiomcache |