{
    "info": {
        "author": "Michal Zmuda",
        "author_email": "zmu.michal@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Developers",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7",
            "Programming Language :: Python :: 3 :: Only",
            "Topic :: Software Development :: Libraries"
        ],
        "description": ".. image:: https://img.shields.io/pypi/v/py-memoize.svg\n    :target: https://pypi.org/project/py-memoize\n\n.. image:: https://img.shields.io/pypi/pyversions/py-memoize.svg\n    :target: https://pypi.org/project/py-memoize\n\n.. image:: https://readthedocs.org/projects/memoize/badge/?version=latest\n    :target: https://memoize.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://travis-ci.com/DreamLab/memoize.svg?token=PCPPzZaRDc9FFFUfKaj9&branch=master\n    :target: https://travis-ci.com/DreamLab/memoize\n\nExtended docs (including API docs) available at `memoize.readthedocs.io <https://memoize.readthedocs.io>`_.\n\nWhat & Why\n==========\n\n**What:** Caching library for asynchronous Python applications.\n\n**Why:** Python deserves library that works in async world\n(for instance handles `dog-piling <https://en.wikipedia.org/wiki/Cache_stampede>`_ )\nand has a proper, extensible API.\n\nEtymology\n=========\n\n*In computing, memoization or memoisation is an optimization technique\nused primarily to speed up computer programs by storing the results of\nexpensive function calls and returning the cached result when the same\ninputs occur again. (\u2026) The term \u201cmemoization\u201d was coined by Donald\nMichie in 1968 and is derived from the Latin word \u201cmemorandum\u201d (\u201cto be\nremembered\u201d), usually truncated as \u201cmemo\u201d in the English language, and\nthus carries the meaning of \u201cturning [the results of] a function into\nsomething to be remembered.\u201d*\n~ `Wikipedia <https://en.wikipedia.org/wiki/Memoization>`_\n\nGetting Started\n===============\n\nInstallation\n------------\n\nBasic Installation\n~~~~~~~~~~~~~~~~~~\n\nTo get you up & running all you need is to install:\n\n.. code-block:: bash\n\n   pip install py-memoize\n\nInstallation of Extras\n~~~~~~~~~~~~~~~~~~~~~~\n\nIf you are going to use ``memoize`` with tornado add a dependency on extra:\n\n.. code-block:: bash\n\n   pip install py-memoize[tornado]\n\nTo harness the power of `ujson <https://pypi.org/project/ujson/>`_ (if JSON SerDe is used) install extra:\n\n.. code-block:: bash\n\n   pip install py-memoize[ujson]\n\nUsage\n-----\n\nProvided examples use default configuration to cache results in memory.\nFor configuration options see `Configurability`_.\n\nYou can use ``memoize`` with both `asyncio <https://docs.python.org/3/library/asyncio.html>`_\nand `Tornado <https://github.com/tornadoweb/tornado>`_ -  please see the appropriate example:\n\nasyncio\n~~~~~~~\n\nTo apply default caching configuration use:\n\n\n.. code-block:: python\n\n    import asyncio\n    import random\n    from memoize.wrapper import memoize\n\n\n    @memoize()\n    async def expensive_computation():\n        return 'expensive-computation-' + str(random.randint(1, 100))\n\n\n    async def main():\n        print(await expensive_computation())\n        print(await expensive_computation())\n        print(await expensive_computation())\n\n\n    if __name__ == \"__main__\":\n        asyncio.get_event_loop().run_until_complete(main())\n\n\nTornado\n~~~~~~~\n\nIf your project is based on Tornado use:\n\n.. code-block:: python\n\n    import random\n\n    from tornado import gen\n    from tornado.ioloop import IOLoop\n\n    from memoize.wrapper import memoize\n\n\n    @memoize()\n    @gen.coroutine\n    def expensive_computation():\n        return 'expensive-computation-' + str(random.randint(1, 100))\n\n\n    @gen.coroutine\n    def main():\n        result1 = yield expensive_computation()\n        print(result1)\n        result2 = yield expensive_computation()\n        print(result2)\n        result3 = yield expensive_computation()\n        print(result3)\n\n\n    if __name__ == \"__main__\":\n        IOLoop.current().run_sync(main)\n\n\n\nFeatures\n========\n\nAsync-first\n-----------\n\nAsynchronous programming is often seen as a huge performance boost in python programming.\nBut with all the benefits it brings there are also new concurrency-related caveats\nlike `dog-piling <https://en.wikipedia.org/wiki/Cache_stampede>`_.\n\nThis library is built async-oriented from the ground-up, what manifests in, for example,\nin `Dog-piling proofness`_ or `Async cache storage`_.\n\n\nTornado & asyncio support\n-------------------------\n\nNo matter what are you using, build-in `asyncio <https://docs.python.org/3/library/asyncio.html>`_\nor its predecessor `Tornado <https://github.com/tornadoweb/tornado>`_\n*memoize* has you covered as you can use it with both.\n**This may come handy if you are planning a migration from Tornado to asyncio.**\n\nUnder the hood *memoize* detects if you are using *Tornado* or *asyncio*\n(by checking if *Tornado* is installed and available to import).\n\nIf have *Tornado* installed but your application uses *asyncio* IO-loop,\nset ``MEMOIZE_FORCE_ASYNCIO=1`` environment variable to force using *asyncio* and ignore *Tornado* instalation.\n\n\nConfigurability\n---------------\n\nWith *memoize* you have under control:\n\n* timeout applied to the cached method;\n* key generation strategy (see `memoize.key.KeyExtractor`);\n  already provided strategies use arguments (both positional & keyword) and method name (or reference);\n* storage for cached entries/items (see `memoize.storage.CacheStorage`);\n  in-memory storage is already provided;\n  for convenience of implementing new storage adapters some SerDe (`memoize.serde.SerDe`) are provided;\n* eviction strategy (see `memoize.eviction.EvictionStrategy`);\n  least-recently-updated strategy is already provided;\n* entry builder (see `memoize.entrybuilder.CacheEntryBuilder`)\n  which has control over ``update_after``  & ``expires_after`` described in `Tunable eviction & async refreshing`_\n\nAll of these elements are open for extension (you can implement and plug-in your own).\nPlease contribute!\n\nExample how to customize default config (everything gets overridden):\n\n.. code-block:: python\n\n    from datetime import timedelta\n\n    from memoize.configuration import MutableCacheConfiguration, DefaultInMemoryCacheConfiguration\n    from memoize.entrybuilder import ProvidedLifeSpanCacheEntryBuilder\n    from memoize.eviction import LeastRecentlyUpdatedEvictionStrategy\n    from memoize.key import EncodedMethodNameAndArgsKeyExtractor\n    from memoize.storage import LocalInMemoryCacheStorage\n    from memoize.wrapper import memoize\n\n\n    @memoize(configuration=MutableCacheConfiguration\n             .initialized_with(DefaultInMemoryCacheConfiguration())\n             .set_method_timeout(value=timedelta(minutes=2))\n             .set_entry_builder(ProvidedLifeSpanCacheEntryBuilder(update_after=timedelta(minutes=2),\n                                                                  expire_after=timedelta(minutes=5)))\n             .set_eviction_strategy(LeastRecentlyUpdatedEvictionStrategy(capacity=2048))\n             .set_key_extractor(EncodedMethodNameAndArgsKeyExtractor(skip_first_arg_as_self=False))\n             .set_storage(LocalInMemoryCacheStorage())\n             )\n    async def cached():\n        return 'dummy'\n\n\nStill, you can use default configuration which:\n\n* sets timeout for underlying method to 2 minutes;\n* uses in-memory storage;\n* uses method instance & arguments to infer cache key;\n* stores up to 4096 elements in cache and evicts entries according to least recently updated policy;\n* refreshes elements after 10 minutes & ignores unrefreshed elements after 30 minutes.\n\nIf that satisfies you, just use default config:\n\n.. code-block:: python\n\n    from memoize.configuration import DefaultInMemoryCacheConfiguration\n    from memoize.wrapper import memoize\n\n\n    @memoize(configuration=DefaultInMemoryCacheConfiguration())\n    async def cached():\n        return 'dummy'\n\n\nTunable eviction & async refreshing\n-----------------------------------\n\nSometimes caching libraries allow providing TTL only. This may result in a scenario where when the cache entry expires\nlatency is increased as the new value needs to be recomputed.\nTo mitigate this periodic extra latency multiple delays are often used. In the case of *memoize* there are two\n(see `memoize.entrybuilder.ProvidedLifeSpanCacheEntryBuilder`):\n\n* ``update_after`` defines delay after which background/async update is executed;\n* ``expire_after`` defines delay after which entry is considered outdated and invalid.\n\nThis allows refreshing cached value in the background without any observable latency.\nMoreover, if some of those background refreshes fail they will be retried still in the background.\nDue to this beneficial feature, it is recommended to ``update_after`` be significantly shorter than ``expire_after``.\n\nDog-piling proofness\n--------------------\n\nIf some resource is accessed asynchronously `dog-piling <https://en.wikipedia.org/wiki/Cache_stampede>`_ may occur.\nCaches designed for synchronous python code\n(like built-in `LRU <https://docs.python.org/3.3/library/functools.html#lru_cache>`_)\nwill allow multiple concurrent tasks to observe a miss for the same resource and will proceed to flood underlying/cached\nbackend with requests for the same resource.\n\n\nAs it breaks the purpose of caching (as backend effectively sometimes is not protected with cache)\n*memoize* has built-in dog-piling protection.\n\nUnder the hood, concurrent requests for the same resource (cache key) get collapsed to a single request to the backend.\nWhen the resource is fetched all requesters obtain the result.\nOn failure, all requesters get an exception (same happens on timeout).\n\nAn example of what it all is about:\n\n.. code-block:: python\n\n    import asyncio\n    from datetime import timedelta\n\n    from aiocache import cached, SimpleMemoryCache  # version 0.10.1 used as example of other cache implementation\n\n    from memoize.configuration import MutableCacheConfiguration, DefaultInMemoryCacheConfiguration\n    from memoize.entrybuilder import ProvidedLifeSpanCacheEntryBuilder\n    from memoize.wrapper import memoize\n\n    # scenario configuration\n    concurrent_requests = 5\n    request_batches_execution_count = 50\n    cached_value_ttl_millis = 200\n    delay_between_request_batches_millis = 70\n\n    # results/statistics\n    unique_calls_under_memoize = 0\n    unique_calls_under_different_cache = 0\n\n\n    @memoize(configuration=MutableCacheConfiguration\n        .initialized_with(DefaultInMemoryCacheConfiguration())\n        .set_entry_builder(\n            ProvidedLifeSpanCacheEntryBuilder(update_after=timedelta(milliseconds=cached_value_ttl_millis))\n        ))\n    async def cached_with_memoize():\n        global unique_calls_under_memoize\n        unique_calls_under_memoize += 1\n        await asyncio.sleep(0.01)\n        return unique_calls_under_memoize\n\n\n    @cached(ttl=cached_value_ttl_millis / 1000, cache=SimpleMemoryCache)\n    async def cached_with_different_cache():\n        global unique_calls_under_different_cache\n        unique_calls_under_different_cache += 1\n        await asyncio.sleep(0.01)\n        return unique_calls_under_different_cache\n\n\n    async def main():\n        for i in range(request_batches_execution_count):\n            await asyncio.gather(*[x() for x in [cached_with_memoize] * concurrent_requests])\n            await asyncio.gather(*[x() for x in [cached_with_different_cache] * concurrent_requests])\n            await asyncio.sleep(delay_between_request_batches_millis / 1000)\n\n        print(\"Memoize generated {} unique backend calls\".format(unique_calls_under_memoize))\n        print(\"Other cache generated {} unique backend calls\".format(unique_calls_under_different_cache))\n        predicted = (delay_between_request_batches_millis * request_batches_execution_count) // cached_value_ttl_millis\n        print(\"Predicted (according to TTL) {} unique backend calls\".format(predicted))\n\n        # Printed:\n        # Memoize generated 17 unique backend calls\n        # Other cache generated 85 unique backend calls\n        # Predicted (according to TTL) 17 unique backend calls\n\n    if __name__ == \"__main__\":\n        asyncio.get_event_loop().run_until_complete(main())\n\n\nAsync cache storage\n-------------------\n\nInterface for cache storage allows you to fully harness benefits of asynchronous programming\n(see interface of `memoize.storage.CacheStorage`).\n\n\nCurrently *memoize* provides only in-memory storage for cache values (internally at *RASP* we have others).\nIf you want (for instance) Redis integration, you need to implement one (please contribute!)\nbut *memoize* will optimally use your async implementation from the start.\n\n",
        "description_content_type": "text/x-rst",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "",
        "keywords": "python cache tornado asyncio",
        "license": "Apache License 2.0",
        "maintainer": "DreamLab",
        "maintainer_email": "",
        "name": "py-memoize",
        "package_url": "https://pypi.org/project/py-memoize/",
        "platform": "Any",
        "project_url": "https://pypi.org/project/py-memoize/",
        "project_urls": null,
        "release_url": "https://pypi.org/project/py-memoize/1.0.1/",
        "requires_dist": [
            "tornado (<5,>4) ; extra == 'tornado'",
            "ujson (>=1.35) ; extra == 'ujson'"
        ],
        "requires_python": "",
        "summary": "Caching library for asynchronous Python applications (both based on asyncio and Tornado) that handles dogpiling properly and provides a configurable & extensible API.",
        "version": "1.0.1"
    },
    "last_serial": 5353070,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "76152f9ea69889a977af6e78e05a91f4",
                    "sha256": "c7851814684e1295fb45b2fd7e18dd95d222dff7fd892efad96eb819954bd915"
                },
                "downloads": -1,
                "filename": "py_memoize-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "76152f9ea69889a977af6e78e05a91f4",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 21028,
                "upload_time": "2019-06-03T13:29:20",
                "url": "https://files.pythonhosted.org/packages/b9/4f/5a9674ab1d0c084516eaae3dedc2466aeff89282d4f343a578eb5dd62c40/py_memoize-1.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "de13d9412e2d2d0daa5a69fa308e9a01",
                    "sha256": "9baa78a6fd7c3ce2cc33a551660f3cf7f6eb7442ee41de698ae531d4826c059a"
                },
                "downloads": -1,
                "filename": "py-memoize-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "de13d9412e2d2d0daa5a69fa308e9a01",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17280,
                "upload_time": "2019-06-03T13:29:22",
                "url": "https://files.pythonhosted.org/packages/9c/97/9c8c4fe5780623c305ada2cbb7a28b7258c24c532ff546a31fb50a240025/py-memoize-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "3abb4bbe9de707110eba5c76fc4121ac",
                    "sha256": "0d0e7fae294e5cd02b6b572f29021cffec2889ebc50cc17262124e6cf95dd3df"
                },
                "downloads": -1,
                "filename": "py_memoize-1.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "3abb4bbe9de707110eba5c76fc4121ac",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 21058,
                "upload_time": "2019-06-03T15:04:05",
                "url": "https://files.pythonhosted.org/packages/f7/f3/ded05e96d70cef85deb0eb0ef457348d5f615ba868945fc59f485b8dc6e3/py_memoize-1.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "ca3656dbe861bbb1e92f643b8ae589ae",
                    "sha256": "4aad1d3ce52efce91778d18b8d31a4d935267e9f3756179b1d8a5339d961be4d"
                },
                "downloads": -1,
                "filename": "py-memoize-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "ca3656dbe861bbb1e92f643b8ae589ae",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 17430,
                "upload_time": "2019-06-03T15:04:07",
                "url": "https://files.pythonhosted.org/packages/31/4e/cbe4182d16f55e6ac9ac2b8ee0c4d50742573d83ac1548a9ad3173a4a46c/py-memoize-1.0.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "3abb4bbe9de707110eba5c76fc4121ac",
                "sha256": "0d0e7fae294e5cd02b6b572f29021cffec2889ebc50cc17262124e6cf95dd3df"
            },
            "downloads": -1,
            "filename": "py_memoize-1.0.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "3abb4bbe9de707110eba5c76fc4121ac",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": null,
            "size": 21058,
            "upload_time": "2019-06-03T15:04:05",
            "url": "https://files.pythonhosted.org/packages/f7/f3/ded05e96d70cef85deb0eb0ef457348d5f615ba868945fc59f485b8dc6e3/py_memoize-1.0.1-py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "ca3656dbe861bbb1e92f643b8ae589ae",
                "sha256": "4aad1d3ce52efce91778d18b8d31a4d935267e9f3756179b1d8a5339d961be4d"
            },
            "downloads": -1,
            "filename": "py-memoize-1.0.1.tar.gz",
            "has_sig": false,
            "md5_digest": "ca3656dbe861bbb1e92f643b8ae589ae",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 17430,
            "upload_time": "2019-06-03T15:04:07",
            "url": "https://files.pythonhosted.org/packages/31/4e/cbe4182d16f55e6ac9ac2b8ee0c4d50742573d83ac1548a9ad3173a4a46c/py-memoize-1.0.1.tar.gz"
        }
    ]
}