Debian Codegraph @

PKG-INFO

raw
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