{ "info": { "author": "Marc Schwarzschild", "author_email": "ms@TheBrookhavenGroup.com", "bugtrack_url": null, "classifiers": [], "description": "=========\nElephants\n=========\n\nThis is a memoize package using StrongDict a class\nintroduced in this package. StrongDict described in\ndetail in the following section uses a linked list of\nstrong references in combination with a weak reference\ndictionary to enable fading memory storage by either\nrestricting the number of items in the store or imposing a\ntime limit on items stored.\n\n\nAbout the name\n--------------\n\nThis package is named Elephants because they are the symbol\nof remembering, or in a modern Python world, memoizing.\n\nExamples\n--------\n\nSimple memoize\n^^^^^^^^^^^^^^\n\n::\n\n from elephants import memo\n\n @memo\n def fib(n):\n if n<2: return 1\n return fib(n-1) + fib(n-2)\n\n \nMemoize with time limit\n^^^^^^^^^^^^^^^^^^^^^^^\n\nThe following pattern demonstrates the @memo_until\ndecorator to cache data object instances for a given\nlength of time.\n\n::\n\n from elephants import memo_until\n\n class MyDataObject(object):\n def __init__(self, x):\n self.x = x\n\n def __str__(self): return str(self.x)\n\n @memo_until(tlimit=3600) # seconds\n def get_my_data_obj_instance(x):\n print 'Getting a new instance for x =', x\n return MyDataObject(x)\n\n\n y = get_my_data_obj_instance(1)\n y = get_my_data_obj_instance(2)\n y = get_my_data_obj_instance(1)\n y = get_my_data_obj_instance(3)\n y = get_my_data_obj_instance(1)\n\n print 'The final value of y should be 1. It is', y\n\nMemoize with length limit\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nThe following pattern demonstrates the @memo_until\ndecorator to cache data object instances for a given\nlength of time.\n\n::\n\n from elephants import nmemo\n\n class MyDataObject(object):\n def __init__(self, x):\n self.x = x\n\n def __str__(self): return str(self.x)\n\n @nmemo(limit=2) # Limit the cache to only two items.\n def get_my_data_obj_instance(x):\n print 'Getting a new instance for x =', x\n return MyDataObject(x)\n\n\n y = get_my_data_obj_instance(1)\n y = get_my_data_obj_instance(2)\n y = get_my_data_obj_instance(3)\n y = get_my_data_obj_instance(1)\n\n print 'At this point the cache should only have 1 and 3.'\n\nStrongDict\n^^^^^^^^^^\n\nA dictionary using strong and weak references.\n\nItems are stored in a WeakValueDictionary. They are also\nstored in a the linked list, the strong cache, holding\nstrong references. Retreival is a fast\nWeakValueDictionary lookup. Items most recently used are\nmoved to the top of the strong cache list. Options are\nprovided to fade from the strong linked list defined by\neither a time limit or a list quantity limit. The default\nis to keep everything in strong linked list forever. If\nan item is removed from the strong cache and later queried\nand found in the WeakValuedictionary it will be added back\nto the strong cache. This can only happen if an reference\nto the removed item exists outside the cache.\n\nAs long as items have a strong reference they will stay in\nthe WeakValueDictionary. However, if an item no longer\nhas a strong reference it is not guaranteed to be in the\nWeakValueDictionary. The WeakValueDictionary will\n\"forget\" about objects not also referenced elsewhere, in\nthis case the StrongDict() strong reference linked list.\n\nThe weakref.WeakValueDictionary() cannot hold native types\nlike int or str. But it can hold a python object that has\nnative types. This StrongDict class uses a Link object\ndefined above to hold all values stored in the cache.\nTherefore the user of StrongDict() does not need to be\nconcerned with this limitation of the weakref package.\n\nCAVEAT EMPTOR: If a class instance is used as key in the\n dictionary then the __hash__() method may\n need to be implmented.\n\nStrongDict Example\n^^^^^^^^^^^^^^^^^^\n\n::\n\n from elephants import StrongDict\n\n w = StrongDict(limit=3)\n\n # populate with test cases\n for i in range(10): w[i] = i * i\n\n # demonstrate limit is imposed and len() works for StrongDict\n assert(len(w) == 3)\n\n assert(6 not in w)\n\n # demonstrate that del works on StrongDict instances\n del w[8]\n assert(len(w) == 2)\n\n # demonstrate that KeyError is thrown when item is not in the dictionary.\n try:\n del w[6]\n assert(False)\n except KeyError:\n 'It cannot delete w[7] since it is not there.'\n assert(True)\n \n # demonstrate for negation on inclusion test.\n del w[9]\n assert(9 not in w)\n\n # demonstrate equals operator\n x = {}\n for i in range(4):\n w[i] = x[i]= i * i\n del x[0]\n assert(w == x)\n\n # demonstrate conversion to dict\n x = dict(w)\n print x\n print type(x)\n\n\nSpecial Note\n^^^^^^^^^^^^\n\n@memo, @nmemo, and @memo_until have two special arguments.\n\nIf a decorated method is called with\n'size_elephant_cache' as the argument it will return the\nnumber of items in the cache. If it is called with\n'clear_elephant_cache' as the argument it will clear the\ncache as shown in the following example.\n\n\nExample\n^^^^^^^\n\n::\n\n from elephants import memo\n\n @memo\n def f(x): return x * x\n\n for i in range(10): f(i)\n\n print 'There are', f('size_elephant_cache'), 'items in the cache.'\n f('clear_elephant_cache')\n print 'There are', f('size_elephant_cache'), 'items in the cache.'\n\nThank you\n=========\n\nA special thank you to Jonathan Arrender Smith for his\nguidance and education.\n", "description_content_type": null, "docs_url": null, "download_url": "UNKNOWN", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "http://github.com/Schwarzschild/Elephants", "keywords": "memo,memoize,cache", "license": "MIT", "maintainer": null, "maintainer_email": null, "name": "Elephants", "package_url": "https://pypi.org/project/Elephants/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/Elephants/", "project_urls": { "Download": "UNKNOWN", "Homepage": "http://github.com/Schwarzschild/Elephants" }, "release_url": "https://pypi.org/project/Elephants/1.0.0/", "requires_dist": null, "requires_python": null, "summary": "Memoization utilities with fading memory.", "version": "1.0.0" }, "last_serial": 1297824, "releases": { "0.1.1": [ { "comment_text": "", "digests": { "md5": "1013c64e6a8bafc00db52acdf7813bd7", "sha256": "7e82ab2399a5bc1ea3290aecce3c56ea7dde5d78bb3fed6b6783284dea974f0a" }, "downloads": -1, "filename": "Elephants-0.1.1.tar.gz", "has_sig": false, "md5_digest": "1013c64e6a8bafc00db52acdf7813bd7", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6506, "upload_time": "2013-05-24T20:26:03", "url": "https://files.pythonhosted.org/packages/2f/f9/7d88753e6d3f1a21ff41116e540d3bd54dc346cb1571ca9cbeef4c8ba9ba/Elephants-0.1.1.tar.gz" } ], "1.0.0": [ { "comment_text": "", "digests": { "md5": "f050963081915a5fe1c78b2c37013226", "sha256": "49fc07a58c33f0e566508c278ab9e1ad27d60b65bbb12de7947a2caa3ad05f63" }, "downloads": -1, "filename": "Elephants-1.0.0.tar.gz", "has_sig": false, "md5_digest": "f050963081915a5fe1c78b2c37013226", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6586, "upload_time": "2014-11-07T01:50:39", "url": "https://files.pythonhosted.org/packages/39/27/b66da8b6fdd74f806d9eefde81f68745226b5ae2754cfd66699033620f1d/Elephants-1.0.0.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "f050963081915a5fe1c78b2c37013226", "sha256": "49fc07a58c33f0e566508c278ab9e1ad27d60b65bbb12de7947a2caa3ad05f63" }, "downloads": -1, "filename": "Elephants-1.0.0.tar.gz", "has_sig": false, "md5_digest": "f050963081915a5fe1c78b2c37013226", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 6586, "upload_time": "2014-11-07T01:50:39", "url": "https://files.pythonhosted.org/packages/39/27/b66da8b6fdd74f806d9eefde81f68745226b5ae2754cfd66699033620f1d/Elephants-1.0.0.tar.gz" } ] }