Metadata-Version: 2.4
Name: ring
Version: 0.10.1
Summary: Function-oriented cache interface with built-in memcache & redis + asyncio support.
Home-page: https://github.com/youknowone/ring
Author: Jeong YunWon
Author-email: ring@youknowone.org
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
License-File: LICENSE
Requires-Dist: six>=1.11.0
Requires-Dist: wirerope>=0.4.7
Requires-Dist: attrs>=19.3.0
Requires-Dist: inspect2>=0.1.0; python_version < "3.0.0"
Requires-Dist: functools32>=3.2.3-2; python_version < "3.0"
Provides-Extra: tests
Requires-Dist: pytest>=3.10.1; extra == "tests"
Requires-Dist: pytest-cov; extra == "tests"
Requires-Dist: pytest-lazy-fixture>=0.6.2; extra == "tests"
Requires-Dist: mock; extra == "tests"
Requires-Dist: patch; extra == "tests"
Requires-Dist: pymemcache; extra == "tests"
Requires-Dist: redis; python_version < "3.0" and extra == "tests"
Requires-Dist: redis>=4.2.0; python_version >= "3.0" and extra == "tests"
Requires-Dist: requests; extra == "tests"
Requires-Dist: diskcache>=4.1.0; extra == "tests"
Requires-Dist: django<4; extra == "tests"
Requires-Dist: numpy; extra == "tests"
Requires-Dist: pylibmc; extra == "tests"
Requires-Dist: pytest-asyncio; extra == "tests"
Requires-Dist: aiomcache; extra == "tests"
Requires-Dist: python3-memcached; extra == "tests"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: django; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest>=3.10.1; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-lazy-fixture>=0.6.2; extra == "dev"
Requires-Dist: mock; extra == "dev"
Requires-Dist: patch; extra == "dev"
Requires-Dist: pymemcache; extra == "dev"
Requires-Dist: redis; python_version < "3.0" and extra == "dev"
Requires-Dist: redis>=4.2.0; python_version >= "3.0" and extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: diskcache>=4.1.0; extra == "dev"
Requires-Dist: django<4; extra == "dev"
Requires-Dist: numpy; extra == "dev"
Requires-Dist: pylibmc; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: aiomcache; extra == "dev"
Requires-Dist: python3-memcached; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: django; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: summary

Ring
====

.. image:: https://badges.gitter.im/ring-cache/community.svg
   :alt: Join the chat at https://gitter.im/ring-cache/community
   :target: https://gitter.im/ring-cache/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

.. image:: https://github.com/youknowone/ring/actions/workflows/python-package.yml/badge.svg
.. image:: https://codecov.io/gh/youknowone/ring/graph/badge.svg
    :target: https://codecov.io/gh/youknowone/ring

Let's concentrate on code, not on storages.

Ring shows a way to control cache in point of view of code - not about storages.
Ring's decorator is convenient but also keeps fluency for general scenarios.

asyncio support for Python3.5+!

Take advantage of perfectly explicit and fully automated cache interface.
Ring decorators convert your functions to cached version of them, with extra
control methods.


Documentation
-------------

Full documentation with examples and references:
`<http://ring-cache.readthedocs.io/>`_

- Function/method support.
- asyncio support.
- Django support.
- Bulk access support.


Function cache
--------------

.. code:: python

    import ring
    import memcache
    import requests

    mc = memcache.Client(['127.0.0.1:11211'])

    # working for mc, expire in 60sec
    @ring.memcache(mc, time=60)
    def get_url(url):
        return requests.get(url).content

    # normal way - it is cached
    data = get_url('http://example.com')

It is a normal smart cache flow.

But ring is different when you want to explicitly control it.


.. code:: python

    # delete the cache
    get_url.delete('http://example.com')
    # get cached data or None
    data_or_none = get_url.get('http://example.com')

    # get internal cache key
    key = get_url.key('http://example.com')
    # and access directly to the backend
    direct_data = mc.get(key)


Method cache
------------

.. code:: python

    import ring
    import redis

    rc = redis.StrictRedis()

    class User(dict):
        def __ring_key__(self):
            return self['id']

        # working for rc, no expiration
        # using json coder for non-bytes cache data
        @ring.redis(rc, coder='json')
        def data(self):
            return self.copy()

        # parameters are also ok!
        @ring.redis(rc, coder='json')
        def child(self, child_id):
            return {'user_id': self['id'], 'child_id': child_id}

    user = User(id=42, name='Ring')

    # create and get cache
    user_data = user.data()  # cached
    user['name'] = 'Ding'
    # still cached
    cached_data = user.data()
    assert user_data == cached_data
    # refresh
    updated_data = user.data.update()
    assert user_data != updated_data

    # id is the cache key so...
    user2 = User(id=42)
    # still hitting the same cache
    assert updated_data == user2.data()


Installation
------------

PyPI is the recommended way.

.. sourcecode:: shell

    $ pip install ring

To browse versions and tarballs, visit:
    `<https://pypi.python.org/pypi/ring/>`_


To use memcached or redis, don't forget to install related libraries.
For example: python-memcached, python3-memcached, pylibmc, redis-py, Django etc

It may require to install and run related services on your system too.
Look for `memcached` and `redis` for your system.


Contributors
------------

See contributors list on:
    `<https://github.com/youknowone/ring/graphs/contributors>`_
