├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── bug_report.md │ ├── config.yml │ └── feature_request.md ├── SECURITY.md ├── dependabot.yml └── workflows │ └── ci.yml ├── .gitignore ├── .readthedocs.yaml ├── CHANGELOG.rst ├── LICENSE ├── MANIFEST.in ├── README.rst ├── docs ├── conf.py └── index.rst ├── pyproject.toml ├── setup.cfg ├── setup.py ├── src └── cachetools │ ├── __init__.py │ ├── _cached.py │ ├── _cachedmethod.py │ ├── func.py │ └── keys.py ├── tests ├── __init__.py ├── test_cache.py ├── test_cached.py ├── test_cachedmethod.py ├── test_fifo.py ├── test_func.py ├── test_keys.py ├── test_lfu.py ├── test_lru.py ├── test_rr.py ├── test_tlru.py └── test_ttl.py └── tox.ini /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | github: [tkem] 2 | custom: ["https://www.paypal.me/tkem"] 3 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: '' 5 | labels: bug 6 | assignees: tkem 7 | 8 | --- 9 | 10 | Before reporting a bug, please make sure you have the latest `cachetools` version installed: 11 | ``` 12 | pip install --upgrade cachetools 13 | ``` 14 | 15 | **Describe the bug** 16 | A clear and concise description of what the bug is. 17 | 18 | **Expected result** 19 | A clear and concise description of what you expected to happen. 20 | 21 | **Actual result** 22 | A clear and concise description of what happened instead. 23 | 24 | **Reproduction steps** 25 | 26 | ```python 27 | import cachetools 28 | 29 | ``` 30 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/config.yml: -------------------------------------------------------------------------------- 1 | blank_issues_enabled: false 2 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: '' 5 | labels: enhancement 6 | assignees: tkem 7 | 8 | --- 9 | 10 | Sorry, but `cachetools` is not accepting feature requests at this time. 11 | -------------------------------------------------------------------------------- /.github/SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Supported Versions 4 | 5 | Security updates are applied only to the latest release. 6 | 7 | ## Reporting a Vulnerability 8 | 9 | If you have discovered a security vulnerability in this project, please report it privately. **Do not disclose it as a public issue.** This gives us time to work with you to fix the issue before public exposure, reducing the chance that the exploit will be used before a patch is released. 10 | 11 | Please disclose it at [security advisory](https://github.com/tkem/cachetools/security/advisories/new). 12 | 13 | This project is maintained by a single person on a best effort basis. As such, vulnerability reports will be investigated and fixed or disclosed as soon as possible, but there may be delays in response time due to the maintainer's other commitments. 14 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | interval: "monthly" 7 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: [push, pull_request, workflow_dispatch] 4 | 5 | permissions: 6 | contents: read 7 | 8 | jobs: 9 | main: 10 | name: Python ${{ matrix.python }} 11 | runs-on: ubuntu-latest 12 | strategy: 13 | fail-fast: false 14 | matrix: 15 | python: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9", "pypy3.10"] 16 | steps: 17 | - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 18 | - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0 19 | with: 20 | python-version: ${{ matrix.python }} 21 | allow-prereleases: true 22 | - run: pip install coverage tox 23 | - run: tox 24 | - uses: codecov/codecov-action@ad3126e916f78f00edff4ed0317cf185271ccc2d # v5.4.2 25 | with: 26 | name: ${{ matrix.python }} 27 | token: ${{ secrets.CODECOV_TOKEN }} 28 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.egg-info 2 | *.pyc 3 | *.swp 4 | .cache/ 5 | .coverage 6 | .pytest_cache/ 7 | .tox/ 8 | MANIFEST 9 | build/ 10 | dist/ 11 | docs/_build/ 12 | 13 | -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | # Configure ReadTheDocs. 2 | 3 | version: 2 4 | 5 | build: 6 | os: "ubuntu-22.04" 7 | tools: 8 | python: "3.11" 9 | 10 | sphinx: 11 | configuration: "docs/conf.py" 12 | -------------------------------------------------------------------------------- /CHANGELOG.rst: -------------------------------------------------------------------------------- 1 | v6.0.0 (2025-05-23) 2 | =================== 3 | 4 | - Require Python 3.9 or later (breaking change). 5 | 6 | - Remove ``MRUCache`` and the ``@func.mru_cache`` decorator (breaking 7 | change). 8 | 9 | - Add an optional ``condition`` parameter to the ``@cached`` and 10 | ``@cachedmethod`` decorators, which, when used with a 11 | ``threading.Condition`` instance, should improve `cache stampede 12 | `_ issues in massively 13 | parallel environments. Note that this will inflict some performance 14 | penalty, and therefore has to be enabled explicitly. 15 | 16 | - Convert the ``cachetools.func`` decorators to use a 17 | ``threading.Condition`` instance to deal with `cache stampede 18 | `_ issues. Note that 19 | this *may* result in a noticable performance degradation, depending 20 | on your actual use case. 21 | 22 | - Deprecate support for ``cache(self)`` returning ``None`` to suppress 23 | caching with the ``@cachedmethod`` decorator. 24 | 25 | - Improve documentation. 26 | 27 | - Update CI environment. 28 | 29 | 30 | v5.5.2 (2025-02-20) 31 | =================== 32 | 33 | - Reduce number of ``@cached`` lock/unlock operations. 34 | 35 | - Improve documentation. 36 | 37 | - Update CI environment. 38 | 39 | 40 | v5.5.1 (2025-01-21) 41 | =================== 42 | 43 | - Add documentation regarding caching of exceptions. 44 | 45 | - Officially support Python 3.13. 46 | 47 | - Update CI environment. 48 | 49 | 50 | v5.5.0 (2024-08-18) 51 | =================== 52 | 53 | - ``TTLCache.expire()`` returns iterable of expired ``(key, value)`` 54 | pairs. 55 | 56 | - ``TLRUCache.expire()`` returns iterable of expired ``(key, value)`` 57 | pairs. 58 | 59 | - Documentation improvements. 60 | 61 | - Update CI environment. 62 | 63 | 64 | v5.4.0 (2024-07-15) 65 | =================== 66 | 67 | - Add the ``keys.typedmethodkey`` decorator. 68 | 69 | - Deprecate ``MRUCache`` class. 70 | 71 | - Deprecate ``@func.mru_cache`` decorator. 72 | 73 | - Update CI environment. 74 | 75 | 76 | v5.3.3 (2024-02-26) 77 | =================== 78 | 79 | - Documentation improvements. 80 | 81 | - Update CI environment. 82 | 83 | 84 | v5.3.2 (2023-10-24) 85 | =================== 86 | 87 | - Add support for Python 3.12. 88 | 89 | - Various documentation improvements. 90 | 91 | 92 | v5.3.1 (2023-05-27) 93 | =================== 94 | 95 | - Depend on Python >= 3.7. 96 | 97 | 98 | v5.3.0 (2023-01-22) 99 | =================== 100 | 101 | - Add ``cache_info()`` function to ``@cached`` decorator. 102 | 103 | 104 | v5.2.1 (2023-01-08) 105 | =================== 106 | 107 | - Add support for Python 3.11. 108 | 109 | - Correct version information in RTD documentation. 110 | 111 | - ``badges/shields``: Change to GitHub workflow badge routes. 112 | 113 | 114 | v5.2.0 (2022-05-29) 115 | =================== 116 | 117 | - Add ``cachetools.keys.methodkey()``. 118 | 119 | - Add ``cache_clear()`` function to decorators. 120 | 121 | - Add ``src`` directory to ``sys.path`` for Sphinx autodoc. 122 | 123 | - Modernize ``func`` wrappers. 124 | 125 | 126 | v5.1.0 (2022-05-15) 127 | =================== 128 | 129 | - Add cache decorator parameters as wrapper function attributes. 130 | 131 | 132 | v5.0.0 (2021-12-21) 133 | =================== 134 | 135 | - Require Python 3.7 or later (breaking change). 136 | 137 | - Remove deprecated submodules (breaking change). 138 | 139 | The ``cache``, ``fifo``, ``lfu``, ``lru``, ``mru``, ``rr`` and 140 | ``ttl`` submodules have been deleted. Therefore, statements like 141 | 142 | ``from cachetools.ttl import TTLCache`` 143 | 144 | will no longer work. Use 145 | 146 | ``from cachetools import TTLCache`` 147 | 148 | instead. 149 | 150 | - Pass ``self`` to ``@cachedmethod`` key function (breaking change). 151 | 152 | The ``key`` function passed to the ``@cachedmethod`` decorator is 153 | now called as ``key(self, *args, **kwargs)``. 154 | 155 | The default key function has been changed to ignore its first 156 | argument, so this should only affect applications using custom key 157 | functions with the ``@cachedmethod`` decorator. 158 | 159 | - Change exact time of expiration in ``TTLCache`` (breaking change). 160 | 161 | ``TTLCache`` items now get expired if their expiration time is less 162 | than *or equal to* ``timer()``. For applications using the default 163 | ``timer()``, this should be barely noticeable, but it may affect the 164 | use of custom timers with larger tick intervals. Note that this 165 | also implies that a ``TTLCache`` with ``ttl=0`` can no longer hold 166 | any items, since they will expire immediately. 167 | 168 | - Change ``Cache.__repr__()`` format (breaking change). 169 | 170 | String representations of cache instances now use a more compact and 171 | efficient format, e.g. 172 | 173 | ``LRUCache({1: 1, 2: 2}, maxsize=10, currsize=2)`` 174 | 175 | - Add TLRU cache implementation. 176 | 177 | - Documentation improvements. 178 | 179 | 180 | v4.2.4 (2021-09-30) 181 | =================== 182 | 183 | - Add submodule shims for backward compatibility. 184 | 185 | 186 | v4.2.3 (2021-09-29) 187 | =================== 188 | 189 | - Add documentation and tests for using ``TTLCache`` with 190 | ``datetime``. 191 | 192 | - Link to typeshed typing stubs. 193 | 194 | - Flatten package file hierarchy. 195 | 196 | 197 | v4.2.2 (2021-04-27) 198 | =================== 199 | 200 | - Update build environment. 201 | 202 | - Remove Python 2 remnants. 203 | 204 | - Format code with Black. 205 | 206 | 207 | v4.2.1 (2021-01-24) 208 | =================== 209 | 210 | - Handle ``__missing__()`` not storing cache items. 211 | 212 | - Clean up ``__missing__()`` example. 213 | 214 | 215 | v4.2.0 (2020-12-10) 216 | =================== 217 | 218 | - Add FIFO cache implementation. 219 | 220 | - Add MRU cache implementation. 221 | 222 | - Improve behavior of decorators in case of race conditions. 223 | 224 | - Improve documentation regarding mutability of caches values and use 225 | of key functions with decorators. 226 | 227 | - Officially support Python 3.9. 228 | 229 | 230 | v4.1.1 (2020-06-28) 231 | =================== 232 | 233 | - Improve ``popitem()`` exception context handling. 234 | 235 | - Replace ``float('inf')`` with ``math.inf``. 236 | 237 | - Improve "envkey" documentation example. 238 | 239 | 240 | v4.1.0 (2020-04-08) 241 | =================== 242 | 243 | - Support ``user_function`` with ``cachetools.func`` decorators 244 | (Python 3.8 compatibility). 245 | 246 | - Support ``cache_parameters()`` with ``cachetools.func`` decorators 247 | (Python 3.9 compatibility). 248 | 249 | 250 | v4.0.0 (2019-12-15) 251 | =================== 252 | 253 | - Require Python 3.5 or later. 254 | 255 | 256 | v3.1.1 (2019-05-23) 257 | =================== 258 | 259 | - Document how to use shared caches with ``@cachedmethod``. 260 | 261 | - Fix pickling/unpickling of cache keys 262 | 263 | 264 | v3.1.0 (2019-01-29) 265 | =================== 266 | 267 | - Fix Python 3.8 compatibility issue. 268 | 269 | - Use ``time.monotonic`` as default timer if available. 270 | 271 | - Improve documentation regarding thread safety. 272 | 273 | 274 | v3.0.0 (2018-11-04) 275 | =================== 276 | 277 | - Officially support Python 3.7. 278 | 279 | - Drop Python 3.3 support (breaking change). 280 | 281 | - Remove ``missing`` cache constructor parameter (breaking change). 282 | 283 | - Remove ``self`` from ``@cachedmethod`` key arguments (breaking 284 | change). 285 | 286 | - Add support for ``maxsize=None`` in ``cachetools.func`` decorators. 287 | 288 | 289 | v2.1.0 (2018-05-12) 290 | =================== 291 | 292 | - Deprecate ``missing`` cache constructor parameter. 293 | 294 | - Handle overridden ``getsizeof()`` method in subclasses. 295 | 296 | - Fix Python 2.7 ``RRCache`` pickling issues. 297 | 298 | - Various documentation improvements. 299 | 300 | 301 | v2.0.1 (2017-08-11) 302 | =================== 303 | 304 | - Officially support Python 3.6. 305 | 306 | - Move documentation to RTD. 307 | 308 | - Documentation: Update import paths for key functions (courtesy of 309 | slavkoja). 310 | 311 | 312 | v2.0.0 (2016-10-03) 313 | =================== 314 | 315 | - Drop Python 3.2 support (breaking change). 316 | 317 | - Drop support for deprecated features (breaking change). 318 | 319 | - Move key functions to separate package (breaking change). 320 | 321 | - Accept non-integer ``maxsize`` in ``Cache.__repr__()``. 322 | 323 | 324 | v1.1.6 (2016-04-01) 325 | =================== 326 | 327 | - Reimplement ``LRUCache`` and ``TTLCache`` using 328 | ``collections.OrderedDict``. Note that this will break pickle 329 | compatibility with previous versions. 330 | 331 | - Fix ``TTLCache`` not calling ``__missing__()`` of derived classes. 332 | 333 | - Handle ``ValueError`` in ``Cache.__missing__()`` for consistency 334 | with caching decorators. 335 | 336 | - Improve how ``TTLCache`` handles expired items. 337 | 338 | - Use ``Counter.most_common()`` for ``LFUCache.popitem()``. 339 | 340 | 341 | v1.1.5 (2015-10-25) 342 | =================== 343 | 344 | - Refactor ``Cache`` base class. Note that this will break pickle 345 | compatibility with previous versions. 346 | 347 | - Clean up ``LRUCache`` and ``TTLCache`` implementations. 348 | 349 | 350 | v1.1.4 (2015-10-24) 351 | =================== 352 | 353 | - Refactor ``LRUCache`` and ``TTLCache`` implementations. Note that 354 | this will break pickle compatibility with previous versions. 355 | 356 | - Document pending removal of deprecated features. 357 | 358 | - Minor documentation improvements. 359 | 360 | 361 | v1.1.3 (2015-09-15) 362 | =================== 363 | 364 | - Fix pickle tests. 365 | 366 | 367 | v1.1.2 (2015-09-15) 368 | =================== 369 | 370 | - Fix pickling of large ``LRUCache`` and ``TTLCache`` instances. 371 | 372 | 373 | v1.1.1 (2015-09-07) 374 | =================== 375 | 376 | - Improve key functions. 377 | 378 | - Improve documentation. 379 | 380 | - Improve unit test coverage. 381 | 382 | 383 | v1.1.0 (2015-08-28) 384 | =================== 385 | 386 | - Add ``@cached`` function decorator. 387 | 388 | - Add ``hashkey`` and ``typedkey`` functions. 389 | 390 | - Add `key` and `lock` arguments to ``@cachedmethod``. 391 | 392 | - Set ``__wrapped__`` attributes for Python versions < 3.2. 393 | 394 | - Move ``functools`` compatible decorators to ``cachetools.func``. 395 | 396 | - Deprecate ``@cachedmethod`` `typed` argument. 397 | 398 | - Deprecate `cache` attribute for ``@cachedmethod`` wrappers. 399 | 400 | - Deprecate `getsizeof` and `lock` arguments for `cachetools.func` 401 | decorator. 402 | 403 | 404 | v1.0.3 (2015-06-26) 405 | =================== 406 | 407 | - Clear cache statistics when calling ``clear_cache()``. 408 | 409 | 410 | v1.0.2 (2015-06-18) 411 | =================== 412 | 413 | - Allow simple cache instances to be pickled. 414 | 415 | - Refactor ``Cache.getsizeof`` and ``Cache.missing`` default 416 | implementation. 417 | 418 | 419 | v1.0.1 (2015-06-06) 420 | =================== 421 | 422 | - Code cleanup for improved PEP 8 conformance. 423 | 424 | - Add documentation and unit tests for using ``@cachedmethod`` with 425 | generic mutable mappings. 426 | 427 | - Improve documentation. 428 | 429 | 430 | v1.0.0 (2014-12-19) 431 | =================== 432 | 433 | - Provide ``RRCache.choice`` property. 434 | 435 | - Improve documentation. 436 | 437 | 438 | v0.8.2 (2014-12-15) 439 | =================== 440 | 441 | - Use a ``NestedTimer`` for ``TTLCache``. 442 | 443 | 444 | v0.8.1 (2014-12-07) 445 | =================== 446 | 447 | - Deprecate ``Cache.getsize()``. 448 | 449 | 450 | v0.8.0 (2014-12-03) 451 | =================== 452 | 453 | - Ignore ``ValueError`` raised on cache insertion in decorators. 454 | 455 | - Add ``Cache.getsize()``. 456 | 457 | - Add ``Cache.__missing__()``. 458 | 459 | - Feature freeze for `v1.0`. 460 | 461 | 462 | v0.7.1 (2014-11-22) 463 | =================== 464 | 465 | - Fix `MANIFEST.in`. 466 | 467 | 468 | v0.7.0 (2014-11-12) 469 | =================== 470 | 471 | - Deprecate ``TTLCache.ExpiredError``. 472 | 473 | - Add `choice` argument to ``RRCache`` constructor. 474 | 475 | - Refactor ``LFUCache``, ``LRUCache`` and ``TTLCache``. 476 | 477 | - Use custom ``NullContext`` implementation for unsynchronized 478 | function decorators. 479 | 480 | 481 | v0.6.0 (2014-10-13) 482 | =================== 483 | 484 | - Raise ``TTLCache.ExpiredError`` for expired ``TTLCache`` items. 485 | 486 | - Support unsynchronized function decorators. 487 | 488 | - Allow ``@cachedmethod.cache()`` to return None 489 | 490 | 491 | v0.5.1 (2014-09-25) 492 | =================== 493 | 494 | - No formatting of ``KeyError`` arguments. 495 | 496 | - Update ``README.rst``. 497 | 498 | 499 | v0.5.0 (2014-09-23) 500 | =================== 501 | 502 | - Do not delete expired items in TTLCache.__getitem__(). 503 | 504 | - Add ``@ttl_cache`` function decorator. 505 | 506 | - Fix public ``getsizeof()`` usage. 507 | 508 | 509 | v0.4.0 (2014-06-16) 510 | =================== 511 | 512 | - Add ``TTLCache``. 513 | 514 | - Add ``Cache`` base class. 515 | 516 | - Remove ``@cachedmethod`` `lock` parameter. 517 | 518 | 519 | v0.3.1 (2014-05-07) 520 | =================== 521 | 522 | - Add proper locking for ``cache_clear()`` and ``cache_info()``. 523 | 524 | - Report `size` in ``cache_info()``. 525 | 526 | 527 | v0.3.0 (2014-05-06) 528 | =================== 529 | 530 | - Remove ``@cache`` decorator. 531 | 532 | - Add ``size``, ``getsizeof`` members. 533 | 534 | - Add ``@cachedmethod`` decorator. 535 | 536 | 537 | v0.2.0 (2014-04-02) 538 | =================== 539 | 540 | - Add ``@cache`` decorator. 541 | 542 | - Update documentation. 543 | 544 | 545 | v0.1.0 (2014-03-27) 546 | =================== 547 | 548 | - Initial release. 549 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2014-2025 Thomas Kemmer 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of 6 | this software and associated documentation files (the "Software"), to deal in 7 | the Software without restriction, including without limitation the rights to 8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software is furnished to do so, 10 | subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS 17 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 18 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 19 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 20 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /MANIFEST.in: -------------------------------------------------------------------------------- 1 | include CHANGELOG.rst 2 | include LICENSE 3 | include MANIFEST.in 4 | include README.rst 5 | include tox.ini 6 | exclude .readthedocs.yaml 7 | 8 | recursive-include docs * 9 | prune docs/_build 10 | 11 | recursive-include tests *.py 12 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | cachetools 2 | ======================================================================== 3 | 4 | .. image:: https://img.shields.io/pypi/v/cachetools 5 | :target: https://pypi.org/project/cachetools/ 6 | :alt: Latest PyPI version 7 | 8 | .. image:: https://img.shields.io/github/actions/workflow/status/tkem/cachetools/ci.yml 9 | :target: https://github.com/tkem/cachetools/actions/workflows/ci.yml 10 | :alt: CI build status 11 | 12 | .. image:: https://img.shields.io/readthedocs/cachetools 13 | :target: https://cachetools.readthedocs.io/ 14 | :alt: Documentation build status 15 | 16 | .. image:: https://img.shields.io/codecov/c/github/tkem/cachetools/master.svg 17 | :target: https://codecov.io/gh/tkem/cachetools 18 | :alt: Test coverage 19 | 20 | .. image:: https://img.shields.io/librariesio/sourcerank/pypi/cachetools 21 | :target: https://libraries.io/pypi/cachetools 22 | :alt: Libraries.io SourceRank 23 | 24 | .. image:: https://img.shields.io/github/license/tkem/cachetools 25 | :target: https://raw.github.com/tkem/cachetools/master/LICENSE 26 | :alt: License 27 | 28 | .. image:: https://img.shields.io/badge/code%20style-black-000000.svg 29 | :target: https://github.com/psf/black 30 | :alt: Code style: black 31 | 32 | 33 | This module provides various memoizing collections and decorators, 34 | including variants of the Python Standard Library's `@lru_cache`_ 35 | function decorator. 36 | 37 | .. code-block:: python 38 | 39 | from cachetools import cached, LRUCache, TTLCache 40 | 41 | # speed up calculating Fibonacci numbers with dynamic programming 42 | @cached(cache={}) 43 | def fib(n): 44 | return n if n < 2 else fib(n - 1) + fib(n - 2) 45 | 46 | # cache least recently used Python Enhancement Proposals 47 | @cached(cache=LRUCache(maxsize=32)) 48 | def get_pep(num): 49 | url = 'http://www.python.org/dev/peps/pep-%04d/' % num 50 | with urllib.request.urlopen(url) as s: 51 | return s.read() 52 | 53 | # cache weather data for no longer than ten minutes 54 | @cached(cache=TTLCache(maxsize=1024, ttl=600)) 55 | def get_weather(place): 56 | return owm.weather_at_place(place).get_weather() 57 | 58 | For the purpose of this module, a *cache* is a mutable_ mapping_ of a 59 | fixed maximum size. When the cache is full, i.e. by adding another 60 | item the cache would exceed its maximum size, the cache must choose 61 | which item(s) to discard based on a suitable `cache algorithm`_. 62 | 63 | This module provides multiple cache classes based on different cache 64 | algorithms, as well as decorators for easily memoizing function and 65 | method calls. 66 | 67 | 68 | Installation 69 | ------------------------------------------------------------------------ 70 | 71 | cachetools is available from PyPI_ and can be installed by running:: 72 | 73 | pip install cachetools 74 | 75 | Typing stubs for this package are provided by typeshed_ and can be 76 | installed by running:: 77 | 78 | pip install types-cachetools 79 | 80 | 81 | Project Resources 82 | ------------------------------------------------------------------------ 83 | 84 | - `Documentation`_ 85 | - `Issue tracker`_ 86 | - `Source code`_ 87 | - `Change log`_ 88 | 89 | 90 | Related Projects 91 | ------------------------------------------------------------------------ 92 | 93 | - asyncache_: Helpers to use cachetools_ with asyncio. 94 | - cacheing_: Pure Python Cacheing Library. 95 | - CacheToolsUtils_: Stackable cache classes for sharing, encryption, 96 | statistics *and more* on top of cachetools_, redis_ and memcached_. 97 | - shelved-cache_: Persistent cache implementation for Python 98 | cachetools_. 99 | 100 | 101 | License 102 | ------------------------------------------------------------------------ 103 | 104 | Copyright (c) 2014-2025 Thomas Kemmer. 105 | 106 | Licensed under the `MIT License`_. 107 | 108 | 109 | .. _@lru_cache: https://docs.python.org/3/library/functools.html#functools.lru_cache 110 | .. _mutable: https://docs.python.org/dev/glossary.html#term-mutable 111 | .. _mapping: https://docs.python.org/dev/glossary.html#term-mapping 112 | .. _cache algorithm: https://en.wikipedia.org/wiki/Cache_algorithms 113 | 114 | .. _PyPI: https://pypi.org/project/cachetools/ 115 | .. _typeshed: https://github.com/python/typeshed/ 116 | .. _Documentation: https://cachetools.readthedocs.io/ 117 | .. _Issue tracker: https://github.com/tkem/cachetools/issues/ 118 | .. _Source code: https://github.com/tkem/cachetools/ 119 | .. _Change log: https://github.com/tkem/cachetools/blob/master/CHANGELOG.rst 120 | .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE 121 | 122 | .. _asyncache: https://pypi.org/project/asyncache/ 123 | .. _cacheing: https://pypi.org/project/cacheing/ 124 | .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/ 125 | .. _shelved-cache: https://pypi.org/project/shelved-cache/ 126 | .. _cachetools: https://pypi.org/project/cachetools/ 127 | .. _redis: https://redis.io/ 128 | .. _memcached: https://memcached.org/ 129 | -------------------------------------------------------------------------------- /docs/conf.py: -------------------------------------------------------------------------------- 1 | import pathlib 2 | import sys 3 | 4 | src_directory = (pathlib.Path(__file__).parent.parent / "src").resolve() 5 | sys.path.insert(0, str(src_directory)) 6 | 7 | 8 | # Extract the current version from the source. 9 | def get_version(): 10 | """Get the version and release from the source code.""" 11 | 12 | text = (src_directory / "cachetools/__init__.py").read_text() 13 | for line in text.splitlines(): 14 | if not line.strip().startswith("__version__"): 15 | continue 16 | full_version = line.partition("=")[2].strip().strip("\"'") 17 | partial_version = ".".join(full_version.split(".")[:2]) 18 | return full_version, partial_version 19 | 20 | 21 | project = "cachetools" 22 | copyright = "2014-2025 Thomas Kemmer" 23 | release, version = get_version() 24 | 25 | extensions = [ 26 | "sphinx.ext.autodoc", 27 | "sphinx.ext.coverage", 28 | "sphinx.ext.doctest", 29 | "sphinx.ext.intersphinx", 30 | "sphinx.ext.todo", 31 | ] 32 | exclude_patterns = ["_build"] 33 | master_doc = "index" 34 | html_theme = "classic" 35 | intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} 36 | -------------------------------------------------------------------------------- /docs/index.rst: -------------------------------------------------------------------------------- 1 | :tocdepth: 3 2 | 3 | ********************************************************************* 4 | :mod:`cachetools` --- Extensible memoizing collections and decorators 5 | ********************************************************************* 6 | 7 | .. module:: cachetools 8 | 9 | This module provides various memoizing collections and decorators, 10 | including variants of the Python Standard Library's `@lru_cache`_ 11 | function decorator. 12 | 13 | For the purpose of this module, a *cache* is a mutable_ mapping_ of a 14 | fixed maximum size. When the cache is full, i.e. by adding another 15 | item the cache would exceed its maximum size, the cache must choose 16 | which item(s) to discard based on a suitable `cache algorithm`_. 17 | 18 | This module provides multiple cache classes based on different cache 19 | algorithms, as well as decorators for easily memoizing function and 20 | method calls. 21 | 22 | .. testsetup:: * 23 | 24 | from cachetools import cached, cachedmethod, LRUCache, TLRUCache, TTLCache 25 | 26 | from unittest import mock 27 | urllib = mock.MagicMock() 28 | 29 | import time 30 | 31 | 32 | Cache implementations 33 | ===================== 34 | 35 | This module provides several classes implementing caches using 36 | different cache algorithms. All these classes derive from class 37 | :class:`Cache`, which in turn derives from 38 | :class:`collections.MutableMapping`, and provide :attr:`maxsize` and 39 | :attr:`currsize` properties to retrieve the maximum and current size 40 | of the cache. When a cache is full, :meth:`Cache.__setitem__()` calls 41 | :meth:`self.popitem()` repeatedly until there is enough room for the 42 | item to be added. 43 | 44 | .. note:: 45 | 46 | Please be aware that `maxsize` must be a positive number. If you 47 | really want your cache to grow without bounds, use 48 | :const:`math.inf` or something similar. 49 | 50 | In general, a cache's size is the total size of its item's values. 51 | Therefore, :class:`Cache` provides a :meth:`getsizeof` method, which 52 | returns the size of a given `value`. The default implementation of 53 | :meth:`getsizeof` returns :const:`1` irrespective of its argument, 54 | making the cache's size equal to the number of its items, or 55 | `len(cache)`. For convenience, all cache classes accept an optional 56 | named constructor parameter `getsizeof`, which may specify a function 57 | of one argument used to retrieve the size of an item's value. 58 | 59 | The values of a :class:`Cache` are mutable by default, as are e.g. the 60 | values of a :class:`dict`. It is the user's responsibility to take 61 | care that cached values are not accidentally modified. This is 62 | especially important when using a custom `getsizeof` function, since 63 | the size of an item's value will only be computed when the item is 64 | inserted into the cache. 65 | 66 | .. note:: 67 | 68 | Please be aware that all these classes are *not* thread-safe. 69 | Access to a shared cache from multiple threads must be properly 70 | synchronized, e.g. by using one of the memoizing decorators with a 71 | suitable `lock` object. 72 | 73 | .. autoclass:: Cache(maxsize, getsizeof=None) 74 | :members: currsize, getsizeof, maxsize 75 | 76 | This class discards arbitrary items using :meth:`popitem` to make 77 | space when necessary. Derived classes may override :meth:`popitem` 78 | to implement specific caching strategies. If a subclass has to 79 | keep track of item access, insertion or deletion, it may 80 | additionally need to override :meth:`__getitem__`, 81 | :meth:`__setitem__` and :meth:`__delitem__`. 82 | 83 | .. autoclass:: FIFOCache(maxsize, getsizeof=None) 84 | :members: popitem 85 | 86 | This class evicts items in the order they were added to make space 87 | when necessary. 88 | 89 | .. autoclass:: LFUCache(maxsize, getsizeof=None) 90 | :members: popitem 91 | 92 | This class counts how often an item is retrieved, and discards the 93 | items used least often to make space when necessary. 94 | 95 | .. autoclass:: LRUCache(maxsize, getsizeof=None) 96 | :members: popitem 97 | 98 | This class discards the least recently used items first to make 99 | space when necessary. 100 | 101 | .. autoclass:: RRCache(maxsize, choice=random.choice, getsizeof=None) 102 | :members: choice, popitem 103 | 104 | This class randomly selects candidate items and discards them to 105 | make space when necessary. 106 | 107 | By default, items are selected from the list of cache keys using 108 | :func:`random.choice`. The optional argument `choice` may specify 109 | an alternative function that returns an arbitrary element from a 110 | non-empty sequence. 111 | 112 | .. autoclass:: TTLCache(maxsize, ttl, timer=time.monotonic, getsizeof=None) 113 | :members: popitem, timer, ttl 114 | 115 | This class associates a time-to-live value with each item. Items 116 | that expire because they have exceeded their time-to-live will be 117 | no longer accessible, and will be removed eventually. If no 118 | expired items are there to remove, the least recently used items 119 | will be discarded first to make space when necessary. 120 | 121 | By default, the time-to-live is specified in seconds and 122 | :func:`time.monotonic` is used to retrieve the current time. 123 | 124 | .. testcode:: 125 | 126 | cache = TTLCache(maxsize=10, ttl=60) 127 | 128 | A custom `timer` function can also be supplied, which does not have 129 | to return seconds, or even a numeric value. The expression 130 | `timer() + ttl` at the time of insertion defines the expiration 131 | time of a cache item and must be comparable against later results 132 | of `timer()`, but `ttl` does not necessarily have to be a number, 133 | either. 134 | 135 | .. testcode:: 136 | 137 | from datetime import datetime, timedelta 138 | 139 | cache = TTLCache(maxsize=10, ttl=timedelta(hours=12), timer=datetime.now) 140 | 141 | .. method:: expire(self, time=None) 142 | 143 | Expired items will be removed from a cache only at the next 144 | mutating operation, e.g. :meth:`__setitem__` or 145 | :meth:`__delitem__`, and therefore may still claim memory. 146 | Calling this method removes all items whose time-to-live would 147 | have expired by `time`, so garbage collection is free to reuse 148 | their memory. If `time` is :const:`None`, this removes all 149 | items that have expired by the current value returned by 150 | :attr:`timer`. 151 | 152 | :returns: An iterable of expired `(key, value)` pairs. 153 | 154 | .. autoclass:: TLRUCache(maxsize, ttu, timer=time.monotonic, getsizeof=None) 155 | :members: popitem, timer, ttu 156 | 157 | Similar to :class:`TTLCache`, this class also associates an 158 | expiration time with each item. However, for :class:`TLRUCache` 159 | items, expiration time is calculated by a user-provided time-to-use 160 | (`ttu`) function, which is passed three arguments at the time of 161 | insertion: the new item's key and value, as well as the current 162 | value of `timer()`. 163 | 164 | .. testcode:: 165 | 166 | def my_ttu(_key, value, now): 167 | # assume value.ttu contains the item's time-to-use in seconds 168 | # note that the _key argument is ignored in this example 169 | return now + value.ttu 170 | 171 | cache = TLRUCache(maxsize=10, ttu=my_ttu) 172 | 173 | The expression `ttu(key, value, timer())` defines the expiration 174 | time of a cache item, and must be comparable against later results 175 | of `timer()`. As with :class:`TTLCache`, a custom `timer` function 176 | can be supplied, which does not have to return a numeric value. 177 | 178 | .. testcode:: 179 | 180 | from datetime import datetime, timedelta 181 | 182 | def datetime_ttu(_key, value, now): 183 | # assume now to be of type datetime.datetime, and 184 | # value.hours to contain the item's time-to-use in hours 185 | return now + timedelta(hours=value.hours) 186 | 187 | cache = TLRUCache(maxsize=10, ttu=datetime_ttu, timer=datetime.now) 188 | 189 | Items that expire because they have exceeded their time-to-use will 190 | be no longer accessible, and will be removed eventually. If no 191 | expired items are there to remove, the least recently used items 192 | will be discarded first to make space when necessary. 193 | 194 | .. method:: expire(self, time=None) 195 | 196 | Expired items will be removed from a cache only at the next 197 | mutating operation, e.g. :meth:`__setitem__` or 198 | :meth:`__delitem__`, and therefore may still claim memory. 199 | Calling this method removes all items whose time-to-use would 200 | have expired by `time`, so garbage collection is free to reuse 201 | their memory. If `time` is :const:`None`, this removes all 202 | items that have expired by the current value returned by 203 | :attr:`timer`. 204 | 205 | :returns: An iterable of expired `(key, value)` pairs. 206 | 207 | 208 | Extending cache classes 209 | ======================= 210 | 211 | Sometimes it may be desirable to notice when and what cache items are 212 | evicted, i.e. removed from a cache to make room for new items. Since 213 | all cache implementations call :meth:`popitem` to evict items from the 214 | cache, this can be achieved by overriding this method in a subclass: 215 | 216 | .. doctest:: 217 | :pyversion: >= 3 218 | 219 | >>> class MyCache(LRUCache): 220 | ... def popitem(self): 221 | ... key, value = super().popitem() 222 | ... print('Key "%s" evicted with value "%s"' % (key, value)) 223 | ... return key, value 224 | 225 | >>> c = MyCache(maxsize=2) 226 | >>> c['a'] = 1 227 | >>> c['b'] = 2 228 | >>> c['c'] = 3 229 | Key "a" evicted with value "1" 230 | 231 | With :class:`TTLCache` and :class:`TLRUCache`, items may also be 232 | removed after they expire. In this case, :meth:`popitem` will *not* 233 | be called, but :meth:`expire` will be called from the next mutating 234 | operation and will return an iterable of the expired `(key, value)` 235 | pairs. By overrding :meth:`expire`, a subclass will be able to track 236 | expired items: 237 | 238 | .. doctest:: 239 | :pyversion: >= 3 240 | 241 | >>> class ExpCache(TTLCache): 242 | ... def expire(self, time=None): 243 | ... items = super().expire(time) 244 | ... print(f"Expired items: {items}") 245 | ... return items 246 | 247 | >>> c = ExpCache(maxsize=10, ttl=1.0) 248 | >>> c['a'] = 1 249 | Expired items: [] 250 | >>> c['b'] = 2 251 | Expired items: [] 252 | >>> time.sleep(1.5) 253 | >>> c['c'] = 3 254 | Expired items: [('a', 1), ('b', 2)] 255 | 256 | Similar to the standard library's :class:`collections.defaultdict`, 257 | subclasses of :class:`Cache` may implement a :meth:`__missing__` 258 | method which is called by :meth:`Cache.__getitem__` if the requested 259 | key is not found: 260 | 261 | .. doctest:: 262 | :pyversion: >= 3 263 | 264 | >>> class PepStore(LRUCache): 265 | ... def __missing__(self, key): 266 | ... """Retrieve text of a Python Enhancement Proposal""" 267 | ... url = 'http://www.python.org/dev/peps/pep-%04d/' % key 268 | ... with urllib.request.urlopen(url) as s: 269 | ... pep = s.read() 270 | ... self[key] = pep # store text in cache 271 | ... return pep 272 | 273 | >>> peps = PepStore(maxsize=4) 274 | >>> for n in 8, 9, 290, 308, 320, 8, 218, 320, 279, 289, 320: 275 | ... pep = peps[n] 276 | >>> print(sorted(peps.keys())) 277 | [218, 279, 289, 320] 278 | 279 | Note, though, that such a class does not really behave like a *cache* 280 | any more, and will lead to surprising results when used with any of 281 | the memoizing decorators described below. However, it may be useful 282 | in its own right. 283 | 284 | 285 | Memoizing decorators 286 | ==================== 287 | 288 | The :mod:`cachetools` module provides decorators for memoizing 289 | function and method calls. This can save time when a function is 290 | often called with the same arguments: 291 | 292 | .. doctest:: 293 | 294 | >>> @cached(cache={}) 295 | ... def fib(n): 296 | ... 'Compute the nth number in the Fibonacci sequence' 297 | ... return n if n < 2 else fib(n - 1) + fib(n - 2) 298 | 299 | >>> fib(42) 300 | 267914296 301 | 302 | .. decorator:: cached(cache, key=cachetools.keys.hashkey, lock=None, condition=None, info=False) 303 | 304 | Decorator to wrap a function with a memoizing callable that saves 305 | results in a cache. 306 | 307 | The `cache` argument specifies a cache object to store previous 308 | function arguments and return values. Note that `cache` need not 309 | be an instance of the cache implementations provided by the 310 | :mod:`cachetools` module. :func:`cached` will work with any 311 | mutable mapping type, including plain :class:`dict` and 312 | :class:`weakref.WeakValueDictionary`. 313 | 314 | `key` specifies a function that will be called with the same 315 | positional and keyword arguments as the wrapped function itself, 316 | and which has to return a suitable cache key. Since caches are 317 | mappings, the object returned by `key` must be hashable. The 318 | default is to call :func:`cachetools.keys.hashkey`. 319 | 320 | If `lock` is not :const:`None`, it must specify an object 321 | implementing the `context manager`_ protocol. Any access to the 322 | cache will then be nested in a ``with lock:`` statement. This can 323 | be used for synchronizing thread access to the cache by providing a 324 | :class:`threading.Lock` or :class:`threading.RLock` instance, for 325 | example. 326 | 327 | .. note:: 328 | 329 | The `lock` context manager is used only to guard access to the 330 | cache object. The underlying wrapped function will be called 331 | outside the `with` statement to allow concurrent execution, and 332 | therefore must be `thread-safe`_ by itself. 333 | 334 | If `condition` is not :const:`None`, it must specify a `condition 335 | variable`_, i.e. an object providing :func:`wait()`, 336 | :func:`wait_for()`, :func:`notify()` and :func:`notify_all()` 337 | methods as defined by :class:`threading.Condition`. Using a 338 | `condition` variable will prevent concurrent execution of the 339 | wrapped function with *identical* parameters, or cache keys. 340 | Instead, a calling thread will check if an identical function call 341 | is already executing, and will then :func:`wait()` for the pending 342 | call to finish. The executing thread will :func:`notify()` any 343 | waiting threads as soon as the function completes, which will then 344 | return the cached function result. 345 | 346 | .. note:: 347 | 348 | Although providing a `lock` alone is generally sufficient to 349 | make :func:`cached` `thread-safe`_, it may still be subject to 350 | `cache stampede`_ issues under high load, depending on your 351 | actual use case. Providing a `condition` variable will mitigate 352 | these situations, but will inflict some performance penalty. 353 | 354 | If no separate `lock` parameter is provided, `condition` must also 355 | implement the `context manager`_ protocol, and will also be used to 356 | guard access to the cache. 357 | 358 | The decorator's `cache`, `key`, `lock` and `condition` parameters 359 | are also available as :attr:`cache`, :attr:`cache_key`, 360 | :attr:`cache_lock` and :attr:`cache_condition` attributes of the 361 | memoizing wrapper function. These can be used for clearing the 362 | cache or invalidating individual cache items, for example. 363 | 364 | .. testcode:: 365 | 366 | from threading import Lock 367 | 368 | # 640K should be enough for anyone... 369 | @cached(cache=LRUCache(maxsize=640*1024, getsizeof=len), lock=Lock()) 370 | def get_pep(num): 371 | 'Retrieve text of a Python Enhancement Proposal' 372 | url = 'http://www.python.org/dev/peps/pep-%04d/' % num 373 | with urllib.request.urlopen(url) as s: 374 | return s.read() 375 | 376 | # make sure access to cache is synchronized 377 | with get_pep.cache_lock: 378 | get_pep.cache.clear() 379 | 380 | # always use the key function for accessing cache items 381 | with get_pep.cache_lock: 382 | get_pep.cache.pop(get_pep.cache_key(42), None) 383 | 384 | For the common use case of clearing or invalidating the cache, the 385 | decorator also provides a :func:`cache_clear()` function which 386 | takes care of locking automatically, if needed: 387 | 388 | .. testcode:: 389 | 390 | # no need for get_pep.cache_lock here 391 | get_pep.cache_clear() 392 | 393 | If `info` is set to :const:`True`, the wrapped function is 394 | instrumented with a :func:`cache_info()` function that returns a 395 | named tuple showing `hits`, `misses`, `maxsize` and `currsize`, to 396 | help measure the effectiveness of the cache. 397 | 398 | .. note:: 399 | 400 | Note that this will inflict some performance penalty, so it has 401 | to be enabled explicitly. 402 | 403 | .. doctest:: 404 | :pyversion: >= 3 405 | 406 | >>> @cached(cache=LRUCache(maxsize=32), info=True) 407 | ... def get_pep(num): 408 | ... url = 'http://www.python.org/dev/peps/pep-%04d/' % num 409 | ... with urllib.request.urlopen(url) as s: 410 | ... return s.read() 411 | 412 | >>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991: 413 | ... pep = get_pep(n) 414 | 415 | >>> get_pep.cache_info() 416 | CacheInfo(hits=3, misses=8, maxsize=32, currsize=8) 417 | 418 | The original underlying function is accessible through the 419 | :attr:`__wrapped__` attribute. This can be used for introspection 420 | or for bypassing the cache. 421 | 422 | It is also possible to use a single shared cache object with 423 | multiple functions. However, care must be taken that different 424 | cache keys are generated for each function, even for identical 425 | function arguments: 426 | 427 | .. doctest:: 428 | :options: +ELLIPSIS 429 | 430 | >>> from cachetools.keys import hashkey 431 | >>> from functools import partial 432 | 433 | >>> # shared cache for integer sequences 434 | >>> numcache = {} 435 | 436 | >>> # compute Fibonacci numbers 437 | >>> @cached(numcache, key=partial(hashkey, 'fib')) 438 | ... def fib(n): 439 | ... return n if n < 2 else fib(n - 1) + fib(n - 2) 440 | 441 | >>> # compute Lucas numbers 442 | >>> @cached(numcache, key=partial(hashkey, 'luc')) 443 | ... def luc(n): 444 | ... return 2 - n if n < 2 else luc(n - 1) + luc(n - 2) 445 | 446 | >>> fib(42) 447 | 267914296 448 | >>> luc(42) 449 | 599074578 450 | >>> list(sorted(numcache.items())) 451 | [..., (('fib', 42), 267914296), ..., (('luc', 42), 599074578)] 452 | 453 | 454 | Function invocations are _not_ cached if any exception are raised. 455 | To cache some (or all) calls raising exceptions, additional 456 | function wrappers may be introduced which wrap exceptions as 457 | regular function results for caching purposes: 458 | 459 | .. testcode:: 460 | 461 | @cached(cache=LRUCache(maxsize=10), info=True) 462 | def _get_pep_wrapped(num): 463 | url = "http://www.python.org/dev/peps/pep-%04d/" % num 464 | try: 465 | with urllib.request.urlopen(url) as s: 466 | return s.read() 467 | except urllib.error.HTTPError as e: 468 | # note that only HTTPError instances are cached 469 | return e 470 | 471 | def get_pep(num): 472 | "Retrieve text of a Python Enhancement Proposal" 473 | 474 | res = _get_pep_wrapped(num) 475 | if isinstance(res, Exception): 476 | raise res 477 | else: 478 | return res 479 | 480 | try: 481 | get_pep(100_000_000) 482 | except Exception as e: 483 | print(e, "-", _get_pep_wrapped.cache_info()) 484 | 485 | try: 486 | get_pep(100_000_000) 487 | except Exception as e: 488 | print(e, "-", _get_pep_wrapped.cache_info()) 489 | 490 | 491 | .. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None) 492 | 493 | Decorator to wrap a class or instance method with a memoizing 494 | callable that saves results in a (possibly shared) cache. 495 | 496 | The main difference between this and the :func:`cached` function 497 | decorator is that `cache`, `lock` and `condition` are not passed 498 | objects, but functions. Those will be called with :const:`self` 499 | (or :const:`cls` for class methods) as their sole argument to 500 | retrieve the cache, lock, or condition object for the method's 501 | respective instance or class. 502 | 503 | .. note:: 504 | 505 | As with :func:`cached`, the context manager obtained by calling 506 | `lock(self)` will only guard access to the cache itself. It is 507 | the user's responsibility to handle concurrent calls to the 508 | underlying wrapped method in a multithreaded environment. 509 | 510 | The `key` function will be called as `key(self, *args, **kwargs)` 511 | to retrieve a suitable cache key. Note that the default `key` 512 | function, :func:`cachetools.keys.methodkey`, ignores its first 513 | argument, i.e. :const:`self`. This has mostly historical reasons, 514 | but also ensures that :const:`self` does not have to be hashable. 515 | You may provide a different `key` function, 516 | e.g. :func:`cachetools.keys.hashkey`, if you need :const:`self` to 517 | be part of the cache key. 518 | 519 | One advantage of :func:`cachedmethod` over the :func:`cached` 520 | function decorator is that cache properties such as `maxsize` can 521 | be set at runtime: 522 | 523 | .. testcode:: 524 | 525 | from cachetools.keys import hashkey 526 | from functools import partial 527 | 528 | class CachedPEPs: 529 | 530 | def __init__(self, cachesize): 531 | self.cache = LRUCache(maxsize=cachesize) 532 | 533 | @cachedmethod(lambda self: self.cache) 534 | def get(self, num): 535 | """Retrieve text of a Python Enhancement Proposal""" 536 | url = 'http://www.python.org/dev/peps/pep-%04d/' % num 537 | with urllib.request.urlopen(url) as s: 538 | return s.read() 539 | 540 | peps = CachedPEPs(cachesize=10) 541 | print("PEP #1: %s" % peps.get(1)) 542 | 543 | .. testoutput:: 544 | :hide: 545 | :options: +ELLIPSIS 546 | 547 | PEP #1: ... 548 | 549 | When using a shared cache for multiple methods, be aware that 550 | different cache keys must be created for each method even when 551 | function arguments are the same, just as with the `@cached` 552 | decorator: 553 | 554 | .. testcode:: 555 | 556 | from cachetools.keys import methodkey 557 | from functools import partial 558 | 559 | class CachedReferences: 560 | 561 | def __init__(self, cachesize): 562 | self.cache = LRUCache(maxsize=cachesize) 563 | 564 | @cachedmethod(lambda self: self.cache, key=partial(methodkey, method='pep')) 565 | def get_pep(self, num): 566 | """Retrieve text of a Python Enhancement Proposal""" 567 | url = 'http://www.python.org/dev/peps/pep-%04d/' % num 568 | with urllib.request.urlopen(url) as s: 569 | return s.read() 570 | 571 | @cachedmethod(lambda self: self.cache, key=partial(methodkey, method='rfc')) 572 | def get_rfc(self, num): 573 | """Retrieve text of an IETF Request for Comments""" 574 | url = 'https://tools.ietf.org/rfc/rfc%d.txt' % num 575 | with urllib.request.urlopen(url) as s: 576 | return s.read() 577 | 578 | docs = CachedReferences(cachesize=100) 579 | print("PEP #20: %s" % docs.get_pep(20)) 580 | print("RFC #20: %s" % docs.get_rfc(20)) 581 | assert len(docs.cache) == 2 582 | 583 | .. testoutput:: 584 | :hide: 585 | :options: +ELLIPSIS 586 | 587 | PEP #20: ... 588 | RFC #20: ... 589 | 590 | Note how keyword arguments are used with :func:`functools.partial` 591 | to create distinct cache keys, to avoid issues with 592 | :func:`methodkey` skipping its initial `self` argument. 593 | 594 | .. deprecated:: 6.0 595 | 596 | Support for `cache(self)` returning :const:`None` to suppress any 597 | caching has been deprecated. `cache(self)` should always return a 598 | valid cache object. 599 | 600 | 601 | ***************************************************************** 602 | :mod:`cachetools.keys` --- Key functions for memoizing decorators 603 | ***************************************************************** 604 | 605 | .. module:: cachetools.keys 606 | 607 | This module provides several functions that can be used as key 608 | functions with the :func:`cached` and :func:`cachedmethod` decorators: 609 | 610 | .. autofunction:: hashkey 611 | 612 | This function returns a :class:`tuple` instance suitable as a cache 613 | key, provided the positional and keywords arguments are hashable. 614 | 615 | .. autofunction:: methodkey 616 | 617 | This function is similar to :func:`hashkey`, but ignores its 618 | first positional argument, i.e. `self` when used with the 619 | :func:`cachedmethod` decorator. 620 | 621 | .. autofunction:: typedkey 622 | 623 | This function is similar to :func:`hashkey`, but arguments of 624 | different types will yield distinct cache keys. For example, 625 | `typedkey(3)` and `typedkey(3.0)` will return different results. 626 | 627 | .. autofunction:: typedmethodkey 628 | 629 | This function is similar to :func:`typedkey`, but ignores its 630 | first positional argument, i.e. `self` when used with the 631 | :func:`cachedmethod` decorator. 632 | 633 | These functions can also be helpful when implementing custom key 634 | functions for handling some non-hashable arguments. For example, 635 | calling the following function with a dictionary as its `env` argument 636 | will raise a :class:`TypeError`, since :class:`dict` is not hashable:: 637 | 638 | @cached(LRUCache(maxsize=128)) 639 | def foo(x, y, z, env={}): 640 | pass 641 | 642 | However, if `env` always holds only hashable values itself, a custom 643 | key function can be written that handles the `env` keyword argument 644 | specially:: 645 | 646 | def envkey(*args, env={}, **kwargs): 647 | key = hashkey(*args, **kwargs) 648 | key += tuple(sorted(env.items())) 649 | return key 650 | 651 | The :func:`envkey` function can then be used in decorator declarations 652 | like this:: 653 | 654 | @cached(LRUCache(maxsize=128), key=envkey) 655 | def foo(x, y, z, env={}): 656 | pass 657 | 658 | foo(1, 2, 3, env=dict(a='a', b='b')) 659 | 660 | 661 | **************************************************************************** 662 | :mod:`cachetools.func` --- :func:`functools.lru_cache` compatible decorators 663 | **************************************************************************** 664 | 665 | .. module:: cachetools.func 666 | 667 | To ease migration from (or to) Python 3's :func:`functools.lru_cache`, 668 | this module provides several memoizing function decorators with a 669 | similar API. All these decorators wrap a function with a memoizing 670 | callable that saves up to the `maxsize` most recent calls, using 671 | different caching strategies. If `maxsize` is set to :const:`None`, 672 | the caching strategy is effectively disabled and the cache can grow 673 | without bound. 674 | 675 | If the optional argument `typed` is set to :const:`True`, function 676 | arguments of different types will be cached separately. For example, 677 | `f(3)` and `f(3.0)` will be treated as distinct calls with distinct 678 | results. 679 | 680 | If a `user_function` is specified instead, it must be a callable. 681 | This allows the decorator to be applied directly to a user function, 682 | leaving the `maxsize` at its default value of 128:: 683 | 684 | @cachetools.func.lru_cache 685 | def count_vowels(sentence): 686 | sentence = sentence.casefold() 687 | return sum(sentence.count(vowel) for vowel in 'aeiou') 688 | 689 | The wrapped function is instrumented with a :func:`cache_parameters` 690 | function that returns a new :class:`dict` showing the values for 691 | `maxsize` and `typed`. This is for information purposes only. 692 | Mutating the values has no effect. 693 | 694 | The wrapped function is also instrumented with :func:`cache_info` and 695 | :func:`cache_clear` functions to provide information about cache 696 | performance and clear the cache. Please see the 697 | :func:`functools.lru_cache` documentation for details. Also note that 698 | all the decorators in this module are thread-safe by default. 699 | 700 | 701 | .. decorator:: fifo_cache(user_function) 702 | fifo_cache(maxsize=128, typed=False) 703 | 704 | Decorator that wraps a function with a memoizing callable that 705 | saves up to `maxsize` results based on a First In First Out 706 | (FIFO) algorithm. 707 | 708 | .. decorator:: lfu_cache(user_function) 709 | lfu_cache(maxsize=128, typed=False) 710 | 711 | Decorator that wraps a function with a memoizing callable that 712 | saves up to `maxsize` results based on a Least Frequently Used 713 | (LFU) algorithm. 714 | 715 | .. decorator:: lru_cache(user_function) 716 | lru_cache(maxsize=128, typed=False) 717 | 718 | Decorator that wraps a function with a memoizing callable that 719 | saves up to `maxsize` results based on a Least Recently Used (LRU) 720 | algorithm. 721 | 722 | .. decorator:: rr_cache(user_function) 723 | rr_cache(maxsize=128, choice=random.choice, typed=False) 724 | 725 | Decorator that wraps a function with a memoizing callable that 726 | saves up to `maxsize` results based on a Random Replacement (RR) 727 | algorithm. 728 | 729 | .. decorator:: ttl_cache(user_function) 730 | ttl_cache(maxsize=128, ttl=600, timer=time.monotonic, typed=False) 731 | 732 | Decorator to wrap a function with a memoizing callable that saves 733 | up to `maxsize` results based on a Least Recently Used (LRU) 734 | algorithm with a per-item time-to-live (TTL) value. 735 | 736 | 737 | .. _@lru_cache: https://docs.python.org/3/library/functools.html#functools.lru_cache 738 | .. _cache algorithm: https://en.wikipedia.org/wiki/Cache_algorithms 739 | .. _cache stampede: https://en.wikipedia.org/wiki/Cache_stampede 740 | .. _condition variable: https://docs.python.org/3/library/threading.html#condition-objects 741 | .. _context manager: https://docs.python.org/dev/glossary.html#term-context-manager 742 | .. _mapping: https://docs.python.org/dev/glossary.html#term-mapping 743 | .. _mutable: https://docs.python.org/dev/glossary.html#term-mutable 744 | .. _thread-safe: https://en.wikipedia.org/wiki/Thread_safety 745 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [build-system] 2 | requires = ["setuptools >= 46.4.0", "wheel"] 3 | build-backend = "setuptools.build_meta" 4 | -------------------------------------------------------------------------------- /setup.cfg: -------------------------------------------------------------------------------- 1 | [metadata] 2 | name = cachetools 3 | version = attr: cachetools.__version__ 4 | url = https://github.com/tkem/cachetools/ 5 | author = Thomas Kemmer 6 | author_email = tkemmer@computer.org 7 | license = MIT 8 | license_files = LICENSE 9 | description = Extensible memoizing collections and decorators 10 | long_description = file: README.rst 11 | classifiers = 12 | Development Status :: 5 - Production/Stable 13 | Environment :: Other Environment 14 | Intended Audience :: Developers 15 | License :: OSI Approved :: MIT License 16 | Operating System :: OS Independent 17 | Programming Language :: Python 18 | Programming Language :: Python :: 3 19 | Programming Language :: Python :: 3.9 20 | Programming Language :: Python :: 3.10 21 | Programming Language :: Python :: 3.11 22 | Programming Language :: Python :: 3.12 23 | Programming Language :: Python :: 3.13 24 | Topic :: Software Development :: Libraries :: Python Modules 25 | 26 | [options] 27 | package_dir = 28 | = src 29 | packages = find: 30 | python_requires = >= 3.9 31 | 32 | [options.packages.find] 33 | where = src 34 | 35 | [flake8] 36 | max-line-length = 80 37 | exclude = .git, .tox, build 38 | select = C, E, F, W, B, B950, I, N 39 | # F401: imported but unused (submodule shims) 40 | # E501: line too long (black) 41 | ignore = F401, E501 42 | 43 | [build_sphinx] 44 | source-dir = docs/ 45 | build-dir = docs/_build 46 | all_files = 1 47 | -------------------------------------------------------------------------------- /setup.py: -------------------------------------------------------------------------------- 1 | from setuptools import setup 2 | 3 | setup() 4 | -------------------------------------------------------------------------------- /src/cachetools/__init__.py: -------------------------------------------------------------------------------- 1 | """Extensible memoizing collections and decorators.""" 2 | 3 | __all__ = ( 4 | "Cache", 5 | "FIFOCache", 6 | "LFUCache", 7 | "LRUCache", 8 | "RRCache", 9 | "TLRUCache", 10 | "TTLCache", 11 | "cached", 12 | "cachedmethod", 13 | ) 14 | 15 | __version__ = "6.0.0" 16 | 17 | import collections 18 | import collections.abc 19 | import functools 20 | import heapq 21 | import random 22 | import time 23 | 24 | from . import keys 25 | 26 | 27 | class _DefaultSize: 28 | __slots__ = () 29 | 30 | def __getitem__(self, _): 31 | return 1 32 | 33 | def __setitem__(self, _, value): 34 | assert value == 1 35 | 36 | def pop(self, _): 37 | return 1 38 | 39 | 40 | class Cache(collections.abc.MutableMapping): 41 | """Mutable mapping to serve as a simple cache or cache base class.""" 42 | 43 | __marker = object() 44 | 45 | __size = _DefaultSize() 46 | 47 | def __init__(self, maxsize, getsizeof=None): 48 | if getsizeof: 49 | self.getsizeof = getsizeof 50 | if self.getsizeof is not Cache.getsizeof: 51 | self.__size = dict() 52 | self.__data = dict() 53 | self.__currsize = 0 54 | self.__maxsize = maxsize 55 | 56 | def __repr__(self): 57 | return "%s(%s, maxsize=%r, currsize=%r)" % ( 58 | self.__class__.__name__, 59 | repr(self.__data), 60 | self.__maxsize, 61 | self.__currsize, 62 | ) 63 | 64 | def __getitem__(self, key): 65 | try: 66 | return self.__data[key] 67 | except KeyError: 68 | return self.__missing__(key) 69 | 70 | def __setitem__(self, key, value): 71 | maxsize = self.__maxsize 72 | size = self.getsizeof(value) 73 | if size > maxsize: 74 | raise ValueError("value too large") 75 | if key not in self.__data or self.__size[key] < size: 76 | while self.__currsize + size > maxsize: 77 | self.popitem() 78 | if key in self.__data: 79 | diffsize = size - self.__size[key] 80 | else: 81 | diffsize = size 82 | self.__data[key] = value 83 | self.__size[key] = size 84 | self.__currsize += diffsize 85 | 86 | def __delitem__(self, key): 87 | size = self.__size.pop(key) 88 | del self.__data[key] 89 | self.__currsize -= size 90 | 91 | def __contains__(self, key): 92 | return key in self.__data 93 | 94 | def __missing__(self, key): 95 | raise KeyError(key) 96 | 97 | def __iter__(self): 98 | return iter(self.__data) 99 | 100 | def __len__(self): 101 | return len(self.__data) 102 | 103 | def get(self, key, default=None): 104 | if key in self: 105 | return self[key] 106 | else: 107 | return default 108 | 109 | def pop(self, key, default=__marker): 110 | if key in self: 111 | value = self[key] 112 | del self[key] 113 | elif default is self.__marker: 114 | raise KeyError(key) 115 | else: 116 | value = default 117 | return value 118 | 119 | def setdefault(self, key, default=None): 120 | if key in self: 121 | value = self[key] 122 | else: 123 | self[key] = value = default 124 | return value 125 | 126 | @property 127 | def maxsize(self): 128 | """The maximum size of the cache.""" 129 | return self.__maxsize 130 | 131 | @property 132 | def currsize(self): 133 | """The current size of the cache.""" 134 | return self.__currsize 135 | 136 | @staticmethod 137 | def getsizeof(value): 138 | """Return the size of a cache element's value.""" 139 | return 1 140 | 141 | 142 | class FIFOCache(Cache): 143 | """First In First Out (FIFO) cache implementation.""" 144 | 145 | def __init__(self, maxsize, getsizeof=None): 146 | Cache.__init__(self, maxsize, getsizeof) 147 | self.__order = collections.OrderedDict() 148 | 149 | def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): 150 | cache_setitem(self, key, value) 151 | try: 152 | self.__order.move_to_end(key) 153 | except KeyError: 154 | self.__order[key] = None 155 | 156 | def __delitem__(self, key, cache_delitem=Cache.__delitem__): 157 | cache_delitem(self, key) 158 | del self.__order[key] 159 | 160 | def popitem(self): 161 | """Remove and return the `(key, value)` pair first inserted.""" 162 | try: 163 | key = next(iter(self.__order)) 164 | except StopIteration: 165 | raise KeyError("%s is empty" % type(self).__name__) from None 166 | else: 167 | return (key, self.pop(key)) 168 | 169 | 170 | class LFUCache(Cache): 171 | """Least Frequently Used (LFU) cache implementation.""" 172 | 173 | def __init__(self, maxsize, getsizeof=None): 174 | Cache.__init__(self, maxsize, getsizeof) 175 | self.__counter = collections.Counter() 176 | 177 | def __getitem__(self, key, cache_getitem=Cache.__getitem__): 178 | value = cache_getitem(self, key) 179 | if key in self: # __missing__ may not store item 180 | self.__counter[key] -= 1 181 | return value 182 | 183 | def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): 184 | cache_setitem(self, key, value) 185 | self.__counter[key] -= 1 186 | 187 | def __delitem__(self, key, cache_delitem=Cache.__delitem__): 188 | cache_delitem(self, key) 189 | del self.__counter[key] 190 | 191 | def popitem(self): 192 | """Remove and return the `(key, value)` pair least frequently used.""" 193 | try: 194 | ((key, _),) = self.__counter.most_common(1) 195 | except ValueError: 196 | raise KeyError("%s is empty" % type(self).__name__) from None 197 | else: 198 | return (key, self.pop(key)) 199 | 200 | 201 | class LRUCache(Cache): 202 | """Least Recently Used (LRU) cache implementation.""" 203 | 204 | def __init__(self, maxsize, getsizeof=None): 205 | Cache.__init__(self, maxsize, getsizeof) 206 | self.__order = collections.OrderedDict() 207 | 208 | def __getitem__(self, key, cache_getitem=Cache.__getitem__): 209 | value = cache_getitem(self, key) 210 | if key in self: # __missing__ may not store item 211 | self.__touch(key) 212 | return value 213 | 214 | def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): 215 | cache_setitem(self, key, value) 216 | self.__touch(key) 217 | 218 | def __delitem__(self, key, cache_delitem=Cache.__delitem__): 219 | cache_delitem(self, key) 220 | del self.__order[key] 221 | 222 | def popitem(self): 223 | """Remove and return the `(key, value)` pair least recently used.""" 224 | try: 225 | key = next(iter(self.__order)) 226 | except StopIteration: 227 | raise KeyError("%s is empty" % type(self).__name__) from None 228 | else: 229 | return (key, self.pop(key)) 230 | 231 | def __touch(self, key): 232 | """Mark as recently used""" 233 | try: 234 | self.__order.move_to_end(key) 235 | except KeyError: 236 | self.__order[key] = None 237 | 238 | 239 | class RRCache(Cache): 240 | """Random Replacement (RR) cache implementation.""" 241 | 242 | def __init__(self, maxsize, choice=random.choice, getsizeof=None): 243 | Cache.__init__(self, maxsize, getsizeof) 244 | self.__choice = choice 245 | 246 | @property 247 | def choice(self): 248 | """The `choice` function used by the cache.""" 249 | return self.__choice 250 | 251 | def popitem(self): 252 | """Remove and return a random `(key, value)` pair.""" 253 | try: 254 | key = self.__choice(list(self)) 255 | except IndexError: 256 | raise KeyError("%s is empty" % type(self).__name__) from None 257 | else: 258 | return (key, self.pop(key)) 259 | 260 | 261 | class _TimedCache(Cache): 262 | """Base class for time aware cache implementations.""" 263 | 264 | class _Timer: 265 | def __init__(self, timer): 266 | self.__timer = timer 267 | self.__nesting = 0 268 | 269 | def __call__(self): 270 | if self.__nesting == 0: 271 | return self.__timer() 272 | else: 273 | return self.__time 274 | 275 | def __enter__(self): 276 | if self.__nesting == 0: 277 | self.__time = time = self.__timer() 278 | else: 279 | time = self.__time 280 | self.__nesting += 1 281 | return time 282 | 283 | def __exit__(self, *exc): 284 | self.__nesting -= 1 285 | 286 | def __reduce__(self): 287 | return _TimedCache._Timer, (self.__timer,) 288 | 289 | def __getattr__(self, name): 290 | return getattr(self.__timer, name) 291 | 292 | def __init__(self, maxsize, timer=time.monotonic, getsizeof=None): 293 | Cache.__init__(self, maxsize, getsizeof) 294 | self.__timer = _TimedCache._Timer(timer) 295 | 296 | def __repr__(self, cache_repr=Cache.__repr__): 297 | with self.__timer as time: 298 | self.expire(time) 299 | return cache_repr(self) 300 | 301 | def __len__(self, cache_len=Cache.__len__): 302 | with self.__timer as time: 303 | self.expire(time) 304 | return cache_len(self) 305 | 306 | @property 307 | def currsize(self): 308 | with self.__timer as time: 309 | self.expire(time) 310 | return super().currsize 311 | 312 | @property 313 | def timer(self): 314 | """The timer function used by the cache.""" 315 | return self.__timer 316 | 317 | def clear(self): 318 | with self.__timer as time: 319 | self.expire(time) 320 | Cache.clear(self) 321 | 322 | def get(self, *args, **kwargs): 323 | with self.__timer: 324 | return Cache.get(self, *args, **kwargs) 325 | 326 | def pop(self, *args, **kwargs): 327 | with self.__timer: 328 | return Cache.pop(self, *args, **kwargs) 329 | 330 | def setdefault(self, *args, **kwargs): 331 | with self.__timer: 332 | return Cache.setdefault(self, *args, **kwargs) 333 | 334 | 335 | class TTLCache(_TimedCache): 336 | """LRU Cache implementation with per-item time-to-live (TTL) value.""" 337 | 338 | class _Link: 339 | __slots__ = ("key", "expires", "next", "prev") 340 | 341 | def __init__(self, key=None, expires=None): 342 | self.key = key 343 | self.expires = expires 344 | 345 | def __reduce__(self): 346 | return TTLCache._Link, (self.key, self.expires) 347 | 348 | def unlink(self): 349 | next = self.next 350 | prev = self.prev 351 | prev.next = next 352 | next.prev = prev 353 | 354 | def __init__(self, maxsize, ttl, timer=time.monotonic, getsizeof=None): 355 | _TimedCache.__init__(self, maxsize, timer, getsizeof) 356 | self.__root = root = TTLCache._Link() 357 | root.prev = root.next = root 358 | self.__links = collections.OrderedDict() 359 | self.__ttl = ttl 360 | 361 | def __contains__(self, key): 362 | try: 363 | link = self.__links[key] # no reordering 364 | except KeyError: 365 | return False 366 | else: 367 | return self.timer() < link.expires 368 | 369 | def __getitem__(self, key, cache_getitem=Cache.__getitem__): 370 | try: 371 | link = self.__getlink(key) 372 | except KeyError: 373 | expired = False 374 | else: 375 | expired = not (self.timer() < link.expires) 376 | if expired: 377 | return self.__missing__(key) 378 | else: 379 | return cache_getitem(self, key) 380 | 381 | def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): 382 | with self.timer as time: 383 | self.expire(time) 384 | cache_setitem(self, key, value) 385 | try: 386 | link = self.__getlink(key) 387 | except KeyError: 388 | self.__links[key] = link = TTLCache._Link(key) 389 | else: 390 | link.unlink() 391 | link.expires = time + self.__ttl 392 | link.next = root = self.__root 393 | link.prev = prev = root.prev 394 | prev.next = root.prev = link 395 | 396 | def __delitem__(self, key, cache_delitem=Cache.__delitem__): 397 | cache_delitem(self, key) 398 | link = self.__links.pop(key) 399 | link.unlink() 400 | if not (self.timer() < link.expires): 401 | raise KeyError(key) 402 | 403 | def __iter__(self): 404 | root = self.__root 405 | curr = root.next 406 | while curr is not root: 407 | # "freeze" time for iterator access 408 | with self.timer as time: 409 | if time < curr.expires: 410 | yield curr.key 411 | curr = curr.next 412 | 413 | def __setstate__(self, state): 414 | self.__dict__.update(state) 415 | root = self.__root 416 | root.prev = root.next = root 417 | for link in sorted(self.__links.values(), key=lambda obj: obj.expires): 418 | link.next = root 419 | link.prev = prev = root.prev 420 | prev.next = root.prev = link 421 | self.expire(self.timer()) 422 | 423 | @property 424 | def ttl(self): 425 | """The time-to-live value of the cache's items.""" 426 | return self.__ttl 427 | 428 | def expire(self, time=None): 429 | """Remove expired items from the cache and return an iterable of the 430 | expired `(key, value)` pairs. 431 | 432 | """ 433 | if time is None: 434 | time = self.timer() 435 | root = self.__root 436 | curr = root.next 437 | links = self.__links 438 | expired = [] 439 | cache_delitem = Cache.__delitem__ 440 | cache_getitem = Cache.__getitem__ 441 | while curr is not root and not (time < curr.expires): 442 | expired.append((curr.key, cache_getitem(self, curr.key))) 443 | cache_delitem(self, curr.key) 444 | del links[curr.key] 445 | next = curr.next 446 | curr.unlink() 447 | curr = next 448 | return expired 449 | 450 | def popitem(self): 451 | """Remove and return the `(key, value)` pair least recently used that 452 | has not already expired. 453 | 454 | """ 455 | with self.timer as time: 456 | self.expire(time) 457 | try: 458 | key = next(iter(self.__links)) 459 | except StopIteration: 460 | raise KeyError("%s is empty" % type(self).__name__) from None 461 | else: 462 | return (key, self.pop(key)) 463 | 464 | def __getlink(self, key): 465 | value = self.__links[key] 466 | self.__links.move_to_end(key) 467 | return value 468 | 469 | 470 | class TLRUCache(_TimedCache): 471 | """Time aware Least Recently Used (TLRU) cache implementation.""" 472 | 473 | @functools.total_ordering 474 | class _Item: 475 | __slots__ = ("key", "expires", "removed") 476 | 477 | def __init__(self, key=None, expires=None): 478 | self.key = key 479 | self.expires = expires 480 | self.removed = False 481 | 482 | def __lt__(self, other): 483 | return self.expires < other.expires 484 | 485 | def __init__(self, maxsize, ttu, timer=time.monotonic, getsizeof=None): 486 | _TimedCache.__init__(self, maxsize, timer, getsizeof) 487 | self.__items = collections.OrderedDict() 488 | self.__order = [] 489 | self.__ttu = ttu 490 | 491 | def __contains__(self, key): 492 | try: 493 | item = self.__items[key] # no reordering 494 | except KeyError: 495 | return False 496 | else: 497 | return self.timer() < item.expires 498 | 499 | def __getitem__(self, key, cache_getitem=Cache.__getitem__): 500 | try: 501 | item = self.__getitem(key) 502 | except KeyError: 503 | expired = False 504 | else: 505 | expired = not (self.timer() < item.expires) 506 | if expired: 507 | return self.__missing__(key) 508 | else: 509 | return cache_getitem(self, key) 510 | 511 | def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): 512 | with self.timer as time: 513 | expires = self.__ttu(key, value, time) 514 | if not (time < expires): 515 | return # skip expired items 516 | self.expire(time) 517 | cache_setitem(self, key, value) 518 | # removing an existing item would break the heap structure, so 519 | # only mark it as removed for now 520 | try: 521 | self.__getitem(key).removed = True 522 | except KeyError: 523 | pass 524 | self.__items[key] = item = TLRUCache._Item(key, expires) 525 | heapq.heappush(self.__order, item) 526 | 527 | def __delitem__(self, key, cache_delitem=Cache.__delitem__): 528 | with self.timer as time: 529 | # no self.expire() for performance reasons, e.g. self.clear() [#67] 530 | cache_delitem(self, key) 531 | item = self.__items.pop(key) 532 | item.removed = True 533 | if not (time < item.expires): 534 | raise KeyError(key) 535 | 536 | def __iter__(self): 537 | for curr in self.__order: 538 | # "freeze" time for iterator access 539 | with self.timer as time: 540 | if time < curr.expires and not curr.removed: 541 | yield curr.key 542 | 543 | @property 544 | def ttu(self): 545 | """The local time-to-use function used by the cache.""" 546 | return self.__ttu 547 | 548 | def expire(self, time=None): 549 | """Remove expired items from the cache and return an iterable of the 550 | expired `(key, value)` pairs. 551 | 552 | """ 553 | if time is None: 554 | time = self.timer() 555 | items = self.__items 556 | order = self.__order 557 | # clean up the heap if too many items are marked as removed 558 | if len(order) > len(items) * 2: 559 | self.__order = order = [item for item in order if not item.removed] 560 | heapq.heapify(order) 561 | expired = [] 562 | cache_delitem = Cache.__delitem__ 563 | cache_getitem = Cache.__getitem__ 564 | while order and (order[0].removed or not (time < order[0].expires)): 565 | item = heapq.heappop(order) 566 | if not item.removed: 567 | expired.append((item.key, cache_getitem(self, item.key))) 568 | cache_delitem(self, item.key) 569 | del items[item.key] 570 | return expired 571 | 572 | def popitem(self): 573 | """Remove and return the `(key, value)` pair least recently used that 574 | has not already expired. 575 | 576 | """ 577 | with self.timer as time: 578 | self.expire(time) 579 | try: 580 | key = next(iter(self.__items)) 581 | except StopIteration: 582 | raise KeyError("%s is empty" % self.__class__.__name__) from None 583 | else: 584 | return (key, self.pop(key)) 585 | 586 | def __getitem(self, key): 587 | value = self.__items[key] 588 | self.__items.move_to_end(key) 589 | return value 590 | 591 | 592 | _CacheInfo = collections.namedtuple( 593 | "CacheInfo", ["hits", "misses", "maxsize", "currsize"] 594 | ) 595 | 596 | 597 | def cached(cache, key=keys.hashkey, lock=None, condition=None, info=False): 598 | """Decorator to wrap a function with a memoizing callable that saves 599 | results in a cache. 600 | 601 | """ 602 | from ._cached import _wrapper 603 | 604 | if isinstance(condition, bool): 605 | from warnings import warn 606 | 607 | warn( 608 | "passing `info` as positional parameter is deprecated", 609 | DeprecationWarning, 610 | stacklevel=2, 611 | ) 612 | info = condition 613 | condition = None 614 | 615 | def decorator(func): 616 | if info: 617 | if isinstance(cache, Cache): 618 | 619 | def make_info(hits, misses): 620 | return _CacheInfo(hits, misses, cache.maxsize, cache.currsize) 621 | 622 | elif isinstance(cache, collections.abc.Mapping): 623 | 624 | def make_info(hits, misses): 625 | return _CacheInfo(hits, misses, None, len(cache)) 626 | 627 | else: 628 | 629 | def make_info(hits, misses): 630 | return _CacheInfo(hits, misses, 0, 0) 631 | 632 | return _wrapper(func, cache, key, lock, condition, info=make_info) 633 | else: 634 | return _wrapper(func, cache, key, lock, condition) 635 | 636 | return decorator 637 | 638 | 639 | def cachedmethod(cache, key=keys.methodkey, lock=None, condition=None): 640 | """Decorator to wrap a class or instance method with a memoizing 641 | callable that saves results in a cache. 642 | 643 | """ 644 | from ._cachedmethod import _wrapper 645 | 646 | def decorator(method): 647 | return _wrapper(method, cache, key, lock, condition) 648 | 649 | return decorator 650 | -------------------------------------------------------------------------------- /src/cachetools/_cached.py: -------------------------------------------------------------------------------- 1 | """Function decorator helpers.""" 2 | 3 | import functools 4 | 5 | 6 | def _condition_info(func, cache, key, lock, cond, info): 7 | hits = misses = 0 8 | pending = set() 9 | 10 | def wrapper(*args, **kwargs): 11 | nonlocal hits, misses 12 | k = key(*args, **kwargs) 13 | with lock: 14 | cond.wait_for(lambda: k not in pending) 15 | try: 16 | result = cache[k] 17 | hits += 1 18 | return result 19 | except KeyError: 20 | pending.add(k) 21 | misses += 1 22 | try: 23 | v = func(*args, **kwargs) 24 | with lock: 25 | try: 26 | cache[k] = v 27 | except ValueError: 28 | pass # value too large 29 | return v 30 | finally: 31 | with lock: 32 | pending.remove(k) 33 | cond.notify_all() 34 | 35 | def cache_clear(): 36 | nonlocal hits, misses 37 | with lock: 38 | cache.clear() 39 | hits = misses = 0 40 | 41 | def cache_info(): 42 | with lock: 43 | return info(hits, misses) 44 | 45 | wrapper.cache_clear = cache_clear 46 | wrapper.cache_info = cache_info 47 | return wrapper 48 | 49 | 50 | def _locked_info(func, cache, key, lock, info): 51 | hits = misses = 0 52 | 53 | def wrapper(*args, **kwargs): 54 | nonlocal hits, misses 55 | k = key(*args, **kwargs) 56 | with lock: 57 | try: 58 | result = cache[k] 59 | hits += 1 60 | return result 61 | except KeyError: 62 | misses += 1 63 | v = func(*args, **kwargs) 64 | with lock: 65 | try: 66 | # in case of a race, prefer the item already in the cache 67 | return cache.setdefault(k, v) 68 | except ValueError: 69 | return v # value too large 70 | 71 | def cache_clear(): 72 | nonlocal hits, misses 73 | with lock: 74 | cache.clear() 75 | hits = misses = 0 76 | 77 | def cache_info(): 78 | with lock: 79 | return info(hits, misses) 80 | 81 | wrapper.cache_clear = cache_clear 82 | wrapper.cache_info = cache_info 83 | return wrapper 84 | 85 | 86 | def _unlocked_info(func, cache, key, info): 87 | hits = misses = 0 88 | 89 | def wrapper(*args, **kwargs): 90 | nonlocal hits, misses 91 | k = key(*args, **kwargs) 92 | try: 93 | result = cache[k] 94 | hits += 1 95 | return result 96 | except KeyError: 97 | misses += 1 98 | v = func(*args, **kwargs) 99 | try: 100 | cache[k] = v 101 | except ValueError: 102 | pass # value too large 103 | return v 104 | 105 | def cache_clear(): 106 | nonlocal hits, misses 107 | cache.clear() 108 | hits = misses = 0 109 | 110 | wrapper.cache_clear = cache_clear 111 | wrapper.cache_info = lambda: info(hits, misses) 112 | return wrapper 113 | 114 | 115 | def _uncached_info(func, info): 116 | misses = 0 117 | 118 | def wrapper(*args, **kwargs): 119 | nonlocal misses 120 | misses += 1 121 | return func(*args, **kwargs) 122 | 123 | def cache_clear(): 124 | nonlocal misses 125 | misses = 0 126 | 127 | wrapper.cache_clear = cache_clear 128 | wrapper.cache_info = lambda: info(0, misses) 129 | return wrapper 130 | 131 | 132 | def _condition(func, cache, key, lock, cond): 133 | pending = set() 134 | 135 | def wrapper(*args, **kwargs): 136 | k = key(*args, **kwargs) 137 | with lock: 138 | cond.wait_for(lambda: k not in pending) 139 | try: 140 | result = cache[k] 141 | return result 142 | except KeyError: 143 | pending.add(k) 144 | try: 145 | v = func(*args, **kwargs) 146 | with lock: 147 | try: 148 | cache[k] = v 149 | except ValueError: 150 | pass # value too large 151 | return v 152 | finally: 153 | with lock: 154 | pending.remove(k) 155 | cond.notify_all() 156 | 157 | def cache_clear(): 158 | with lock: 159 | cache.clear() 160 | 161 | wrapper.cache_clear = cache_clear 162 | return wrapper 163 | 164 | 165 | def _locked(func, cache, key, lock): 166 | def wrapper(*args, **kwargs): 167 | k = key(*args, **kwargs) 168 | with lock: 169 | try: 170 | return cache[k] 171 | except KeyError: 172 | pass # key not found 173 | v = func(*args, **kwargs) 174 | with lock: 175 | try: 176 | # in case of a race, prefer the item already in the cache 177 | return cache.setdefault(k, v) 178 | except ValueError: 179 | return v # value too large 180 | 181 | def cache_clear(): 182 | with lock: 183 | cache.clear() 184 | 185 | wrapper.cache_clear = cache_clear 186 | return wrapper 187 | 188 | 189 | def _unlocked(func, cache, key): 190 | def wrapper(*args, **kwargs): 191 | k = key(*args, **kwargs) 192 | try: 193 | return cache[k] 194 | except KeyError: 195 | pass # key not found 196 | v = func(*args, **kwargs) 197 | try: 198 | cache[k] = v 199 | except ValueError: 200 | pass # value too large 201 | return v 202 | 203 | wrapper.cache_clear = lambda: cache.clear() 204 | return wrapper 205 | 206 | 207 | def _uncached(func): 208 | def wrapper(*args, **kwargs): 209 | return func(*args, **kwargs) 210 | 211 | wrapper.cache_clear = lambda: None 212 | return wrapper 213 | 214 | 215 | def _wrapper(func, cache, key, lock=None, cond=None, info=None): 216 | if info is not None: 217 | if cache is None: 218 | wrapper = _uncached_info(func, info) 219 | elif cond is not None and lock is not None: 220 | wrapper = _condition_info(func, cache, key, lock, cond, info) 221 | elif cond is not None: 222 | wrapper = _condition_info(func, cache, key, cond, cond, info) 223 | elif lock is not None: 224 | wrapper = _locked_info(func, cache, key, lock, info) 225 | else: 226 | wrapper = _unlocked_info(func, cache, key, info) 227 | else: 228 | if cache is None: 229 | wrapper = _uncached(func) 230 | elif cond is not None and lock is not None: 231 | wrapper = _condition(func, cache, key, lock, cond) 232 | elif cond is not None: 233 | wrapper = _condition(func, cache, key, cond, cond) 234 | elif lock is not None: 235 | wrapper = _locked(func, cache, key, lock) 236 | else: 237 | wrapper = _unlocked(func, cache, key) 238 | wrapper.cache_info = None 239 | 240 | wrapper.cache = cache 241 | wrapper.cache_key = key 242 | wrapper.cache_lock = lock if lock is not None else cond 243 | wrapper.cache_condition = cond 244 | 245 | return functools.update_wrapper(wrapper, func) 246 | -------------------------------------------------------------------------------- /src/cachetools/_cachedmethod.py: -------------------------------------------------------------------------------- 1 | """Method decorator helpers.""" 2 | 3 | import functools 4 | import weakref 5 | 6 | 7 | def warn_cache_none(): 8 | from warnings import warn 9 | 10 | warn( 11 | "returning `None` from `cache(self)` is deprecated", 12 | DeprecationWarning, 13 | stacklevel=3, 14 | ) 15 | 16 | 17 | def _condition(method, cache, key, lock, cond): 18 | pending = weakref.WeakKeyDictionary() 19 | 20 | def wrapper(self, *args, **kwargs): 21 | c = cache(self) 22 | if c is None: 23 | warn_cache_none() 24 | return method(self, *args, **kwargs) 25 | k = key(self, *args, **kwargs) 26 | with lock(self): 27 | p = pending.setdefault(self, set()) 28 | cond(self).wait_for(lambda: k not in p) 29 | try: 30 | return c[k] 31 | except KeyError: 32 | p.add(k) 33 | try: 34 | v = method(self, *args, **kwargs) 35 | with lock(self): 36 | try: 37 | c[k] = v 38 | except ValueError: 39 | pass # value too large 40 | return v 41 | finally: 42 | with lock(self): 43 | pending[self].remove(k) 44 | cond(self).notify_all() 45 | 46 | def cache_clear(self): 47 | c = cache(self) 48 | if c is not None: 49 | with lock(self): 50 | c.clear() 51 | 52 | wrapper.cache_clear = cache_clear 53 | return wrapper 54 | 55 | 56 | def _locked(method, cache, key, lock): 57 | def wrapper(self, *args, **kwargs): 58 | c = cache(self) 59 | if c is None: 60 | warn_cache_none() 61 | return method(self, *args, **kwargs) 62 | k = key(self, *args, **kwargs) 63 | with lock(self): 64 | try: 65 | return c[k] 66 | except KeyError: 67 | pass # key not found 68 | v = method(self, *args, **kwargs) 69 | # in case of a race, prefer the item already in the cache 70 | with lock(self): 71 | try: 72 | return c.setdefault(k, v) 73 | except ValueError: 74 | return v # value too large 75 | 76 | def cache_clear(self): 77 | c = cache(self) 78 | if c is not None: 79 | with lock(self): 80 | c.clear() 81 | 82 | wrapper.cache_clear = cache_clear 83 | return wrapper 84 | 85 | 86 | def _unlocked(method, cache, key): 87 | def wrapper(self, *args, **kwargs): 88 | c = cache(self) 89 | if c is None: 90 | warn_cache_none() 91 | return method(self, *args, **kwargs) 92 | k = key(self, *args, **kwargs) 93 | try: 94 | return c[k] 95 | except KeyError: 96 | pass # key not found 97 | v = method(self, *args, **kwargs) 98 | try: 99 | c[k] = v 100 | except ValueError: 101 | pass # value too large 102 | return v 103 | 104 | def cache_clear(self): 105 | c = cache(self) 106 | if c is not None: 107 | c.clear() 108 | 109 | wrapper.cache_clear = cache_clear 110 | return wrapper 111 | 112 | 113 | def _wrapper(method, cache, key, lock=None, cond=None): 114 | if cond is not None and lock is not None: 115 | wrapper = _condition(method, cache, key, lock, cond) 116 | elif cond is not None: 117 | wrapper = _condition(method, cache, key, cond, cond) 118 | elif lock is not None: 119 | wrapper = _locked(method, cache, key, lock) 120 | else: 121 | wrapper = _unlocked(method, cache, key) 122 | 123 | wrapper.cache = cache 124 | wrapper.cache_key = key 125 | wrapper.cache_lock = lock if lock is not None else cond 126 | wrapper.cache_condition = cond 127 | 128 | return functools.update_wrapper(wrapper, method) 129 | -------------------------------------------------------------------------------- /src/cachetools/func.py: -------------------------------------------------------------------------------- 1 | """`functools.lru_cache` compatible memoizing function decorators.""" 2 | 3 | __all__ = ("fifo_cache", "lfu_cache", "lru_cache", "rr_cache", "ttl_cache") 4 | 5 | import functools 6 | import math 7 | import random 8 | import time 9 | from threading import Condition 10 | 11 | from . import FIFOCache, LFUCache, LRUCache, RRCache, TTLCache 12 | from . import cached 13 | from . import keys 14 | 15 | 16 | class _UnboundTTLCache(TTLCache): 17 | def __init__(self, ttl, timer): 18 | TTLCache.__init__(self, math.inf, ttl, timer) 19 | 20 | @property 21 | def maxsize(self): 22 | return None 23 | 24 | 25 | def _cache(cache, maxsize, typed): 26 | def decorator(func): 27 | key = keys.typedkey if typed else keys.hashkey 28 | wrapper = cached(cache=cache, key=key, condition=Condition(), info=True)(func) 29 | wrapper.cache_parameters = lambda: {"maxsize": maxsize, "typed": typed} 30 | return wrapper 31 | 32 | return decorator 33 | 34 | 35 | def fifo_cache(maxsize=128, typed=False): 36 | """Decorator to wrap a function with a memoizing callable that saves 37 | up to `maxsize` results based on a First In First Out (FIFO) 38 | algorithm. 39 | 40 | """ 41 | if maxsize is None: 42 | return _cache({}, None, typed) 43 | elif callable(maxsize): 44 | return _cache(FIFOCache(128), 128, typed)(maxsize) 45 | else: 46 | return _cache(FIFOCache(maxsize), maxsize, typed) 47 | 48 | 49 | def lfu_cache(maxsize=128, typed=False): 50 | """Decorator to wrap a function with a memoizing callable that saves 51 | up to `maxsize` results based on a Least Frequently Used (LFU) 52 | algorithm. 53 | 54 | """ 55 | if maxsize is None: 56 | return _cache({}, None, typed) 57 | elif callable(maxsize): 58 | return _cache(LFUCache(128), 128, typed)(maxsize) 59 | else: 60 | return _cache(LFUCache(maxsize), maxsize, typed) 61 | 62 | 63 | def lru_cache(maxsize=128, typed=False): 64 | """Decorator to wrap a function with a memoizing callable that saves 65 | up to `maxsize` results based on a Least Recently Used (LRU) 66 | algorithm. 67 | 68 | """ 69 | if maxsize is None: 70 | return _cache({}, None, typed) 71 | elif callable(maxsize): 72 | return _cache(LRUCache(128), 128, typed)(maxsize) 73 | else: 74 | return _cache(LRUCache(maxsize), maxsize, typed) 75 | 76 | 77 | def rr_cache(maxsize=128, choice=random.choice, typed=False): 78 | """Decorator to wrap a function with a memoizing callable that saves 79 | up to `maxsize` results based on a Random Replacement (RR) 80 | algorithm. 81 | 82 | """ 83 | if maxsize is None: 84 | return _cache({}, None, typed) 85 | elif callable(maxsize): 86 | return _cache(RRCache(128, choice), 128, typed)(maxsize) 87 | else: 88 | return _cache(RRCache(maxsize, choice), maxsize, typed) 89 | 90 | 91 | def ttl_cache(maxsize=128, ttl=600, timer=time.monotonic, typed=False): 92 | """Decorator to wrap a function with a memoizing callable that saves 93 | up to `maxsize` results based on a Least Recently Used (LRU) 94 | algorithm with a per-item time-to-live (TTL) value. 95 | """ 96 | if maxsize is None: 97 | return _cache(_UnboundTTLCache(ttl, timer), None, typed) 98 | elif callable(maxsize): 99 | return _cache(TTLCache(128, ttl, timer), 128, typed)(maxsize) 100 | else: 101 | return _cache(TTLCache(maxsize, ttl, timer), maxsize, typed) 102 | -------------------------------------------------------------------------------- /src/cachetools/keys.py: -------------------------------------------------------------------------------- 1 | """Key functions for memoizing decorators.""" 2 | 3 | __all__ = ("hashkey", "methodkey", "typedkey", "typedmethodkey") 4 | 5 | 6 | class _HashedTuple(tuple): 7 | """A tuple that ensures that hash() will be called no more than once 8 | per element, since cache decorators will hash the key multiple 9 | times on a cache miss. See also _HashedSeq in the standard 10 | library functools implementation. 11 | 12 | """ 13 | 14 | __hashvalue = None 15 | 16 | def __hash__(self, hash=tuple.__hash__): 17 | hashvalue = self.__hashvalue 18 | if hashvalue is None: 19 | self.__hashvalue = hashvalue = hash(self) 20 | return hashvalue 21 | 22 | def __add__(self, other, add=tuple.__add__): 23 | return _HashedTuple(add(self, other)) 24 | 25 | def __radd__(self, other, add=tuple.__add__): 26 | return _HashedTuple(add(other, self)) 27 | 28 | def __getstate__(self): 29 | return {} 30 | 31 | 32 | # used for separating keyword arguments; we do not use an object 33 | # instance here so identity is preserved when pickling/unpickling 34 | _kwmark = (_HashedTuple,) 35 | 36 | 37 | def hashkey(*args, **kwargs): 38 | """Return a cache key for the specified hashable arguments.""" 39 | 40 | if kwargs: 41 | return _HashedTuple(args + sum(sorted(kwargs.items()), _kwmark)) 42 | else: 43 | return _HashedTuple(args) 44 | 45 | 46 | def methodkey(self, *args, **kwargs): 47 | """Return a cache key for use with cached methods.""" 48 | return hashkey(*args, **kwargs) 49 | 50 | 51 | def typedkey(*args, **kwargs): 52 | """Return a typed cache key for the specified hashable arguments.""" 53 | 54 | key = hashkey(*args, **kwargs) 55 | key += tuple(type(v) for v in args) 56 | key += tuple(type(v) for _, v in sorted(kwargs.items())) 57 | return key 58 | 59 | 60 | def typedmethodkey(self, *args, **kwargs): 61 | """Return a typed cache key for use with cached methods.""" 62 | return typedkey(*args, **kwargs) 63 | -------------------------------------------------------------------------------- /tests/__init__.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | 4 | class CacheTestMixin: 5 | Cache = None 6 | 7 | def test_defaults(self): 8 | cache = self.Cache(maxsize=1) 9 | self.assertEqual(0, len(cache)) 10 | self.assertEqual(1, cache.maxsize) 11 | self.assertEqual(0, cache.currsize) 12 | self.assertEqual(1, cache.getsizeof(None)) 13 | self.assertEqual(1, cache.getsizeof("")) 14 | self.assertEqual(1, cache.getsizeof(0)) 15 | self.assertTrue(repr(cache).startswith(cache.__class__.__name__)) 16 | 17 | def test_insert(self): 18 | cache = self.Cache(maxsize=2) 19 | 20 | cache.update({1: 1, 2: 2}) 21 | self.assertEqual(2, len(cache)) 22 | self.assertEqual(1, cache[1]) 23 | self.assertEqual(2, cache[2]) 24 | 25 | cache[3] = 3 26 | self.assertEqual(2, len(cache)) 27 | self.assertEqual(3, cache[3]) 28 | self.assertTrue(1 in cache or 2 in cache) 29 | 30 | cache[4] = 4 31 | self.assertEqual(2, len(cache)) 32 | self.assertEqual(4, cache[4]) 33 | self.assertTrue(1 in cache or 2 in cache or 3 in cache) 34 | 35 | def test_update(self): 36 | cache = self.Cache(maxsize=2) 37 | 38 | cache.update({1: 1, 2: 2}) 39 | self.assertEqual(2, len(cache)) 40 | self.assertEqual(1, cache[1]) 41 | self.assertEqual(2, cache[2]) 42 | 43 | cache.update({1: 1, 2: 2}) 44 | self.assertEqual(2, len(cache)) 45 | self.assertEqual(1, cache[1]) 46 | self.assertEqual(2, cache[2]) 47 | 48 | cache.update({1: "a", 2: "b"}) 49 | self.assertEqual(2, len(cache)) 50 | self.assertEqual("a", cache[1]) 51 | self.assertEqual("b", cache[2]) 52 | 53 | def test_delete(self): 54 | cache = self.Cache(maxsize=2) 55 | 56 | cache.update({1: 1, 2: 2}) 57 | self.assertEqual(2, len(cache)) 58 | self.assertEqual(1, cache[1]) 59 | self.assertEqual(2, cache[2]) 60 | 61 | del cache[2] 62 | self.assertEqual(1, len(cache)) 63 | self.assertEqual(1, cache[1]) 64 | self.assertNotIn(2, cache) 65 | 66 | del cache[1] 67 | self.assertEqual(0, len(cache)) 68 | self.assertNotIn(1, cache) 69 | self.assertNotIn(2, cache) 70 | 71 | with self.assertRaises(KeyError): 72 | del cache[1] 73 | self.assertEqual(0, len(cache)) 74 | self.assertNotIn(1, cache) 75 | self.assertNotIn(2, cache) 76 | 77 | def test_pop(self): 78 | cache = self.Cache(maxsize=2) 79 | 80 | cache.update({1: 1, 2: 2}) 81 | self.assertEqual(2, cache.pop(2)) 82 | self.assertEqual(1, len(cache)) 83 | self.assertEqual(1, cache.pop(1)) 84 | self.assertEqual(0, len(cache)) 85 | 86 | with self.assertRaises(KeyError): 87 | cache.pop(2) 88 | with self.assertRaises(KeyError): 89 | cache.pop(1) 90 | with self.assertRaises(KeyError): 91 | cache.pop(0) 92 | 93 | self.assertEqual(None, cache.pop(2, None)) 94 | self.assertEqual(None, cache.pop(1, None)) 95 | self.assertEqual(None, cache.pop(0, None)) 96 | 97 | def test_popitem(self): 98 | cache = self.Cache(maxsize=2) 99 | 100 | cache.update({1: 1, 2: 2}) 101 | self.assertIn(cache.pop(1), {1: 1, 2: 2}) 102 | self.assertEqual(1, len(cache)) 103 | self.assertIn(cache.pop(2), {1: 1, 2: 2}) 104 | self.assertEqual(0, len(cache)) 105 | 106 | with self.assertRaises(KeyError): 107 | cache.popitem() 108 | 109 | def test_popitem_exception_context(self): 110 | # since Python 3.7, MutableMapping.popitem() suppresses 111 | # exception context as implementation detail 112 | exception = None 113 | try: 114 | self.Cache(maxsize=2).popitem() 115 | except Exception as e: 116 | exception = e 117 | self.assertIsNone(exception.__cause__) 118 | self.assertTrue(exception.__suppress_context__) 119 | 120 | def test_missing(self): 121 | class DefaultCache(self.Cache): 122 | def __missing__(self, key): 123 | self[key] = key 124 | return key 125 | 126 | cache = DefaultCache(maxsize=2) 127 | 128 | self.assertEqual(0, cache.currsize) 129 | self.assertEqual(2, cache.maxsize) 130 | self.assertEqual(0, len(cache)) 131 | self.assertEqual(1, cache[1]) 132 | self.assertEqual(2, cache[2]) 133 | self.assertEqual(2, len(cache)) 134 | self.assertTrue(1 in cache and 2 in cache) 135 | 136 | self.assertEqual(3, cache[3]) 137 | self.assertEqual(2, len(cache)) 138 | self.assertTrue(3 in cache) 139 | self.assertTrue(1 in cache or 2 in cache) 140 | self.assertTrue(1 not in cache or 2 not in cache) 141 | 142 | self.assertEqual(4, cache[4]) 143 | self.assertEqual(2, len(cache)) 144 | self.assertTrue(4 in cache) 145 | self.assertTrue(1 in cache or 2 in cache or 3 in cache) 146 | 147 | # verify __missing__() is *not* called for any operations 148 | # besides __getitem__() 149 | 150 | self.assertEqual(4, cache.get(4)) 151 | self.assertEqual(None, cache.get(5)) 152 | self.assertEqual(5 * 5, cache.get(5, 5 * 5)) 153 | self.assertEqual(2, len(cache)) 154 | 155 | self.assertEqual(4, cache.pop(4)) 156 | with self.assertRaises(KeyError): 157 | cache.pop(5) 158 | self.assertEqual(None, cache.pop(5, None)) 159 | self.assertEqual(5 * 5, cache.pop(5, 5 * 5)) 160 | self.assertEqual(1, len(cache)) 161 | 162 | cache.clear() 163 | cache[1] = 1 + 1 164 | self.assertEqual(1 + 1, cache.setdefault(1)) 165 | self.assertEqual(1 + 1, cache.setdefault(1, 1)) 166 | self.assertEqual(1 + 1, cache[1]) 167 | self.assertEqual(2 + 2, cache.setdefault(2, 2 + 2)) 168 | self.assertEqual(2 + 2, cache.setdefault(2, None)) 169 | self.assertEqual(2 + 2, cache.setdefault(2)) 170 | self.assertEqual(2 + 2, cache[2]) 171 | self.assertEqual(2, len(cache)) 172 | self.assertTrue(1 in cache and 2 in cache) 173 | self.assertEqual(None, cache.setdefault(3)) 174 | self.assertEqual(2, len(cache)) 175 | self.assertTrue(3 in cache) 176 | self.assertTrue(1 in cache or 2 in cache) 177 | self.assertTrue(1 not in cache or 2 not in cache) 178 | 179 | def test_missing_getsizeof(self): 180 | class DefaultCache(self.Cache): 181 | def __missing__(self, key): 182 | try: 183 | self[key] = key 184 | except ValueError: 185 | pass # not stored 186 | return key 187 | 188 | cache = DefaultCache(maxsize=2, getsizeof=lambda x: x) 189 | 190 | self.assertEqual(0, cache.currsize) 191 | self.assertEqual(2, cache.maxsize) 192 | 193 | self.assertEqual(1, cache[1]) 194 | self.assertEqual(1, len(cache)) 195 | self.assertEqual(1, cache.currsize) 196 | self.assertIn(1, cache) 197 | 198 | self.assertEqual(2, cache[2]) 199 | self.assertEqual(1, len(cache)) 200 | self.assertEqual(2, cache.currsize) 201 | self.assertNotIn(1, cache) 202 | self.assertIn(2, cache) 203 | 204 | self.assertEqual(3, cache[3]) # not stored 205 | self.assertEqual(1, len(cache)) 206 | self.assertEqual(2, cache.currsize) 207 | self.assertEqual(1, cache[1]) 208 | self.assertEqual(1, len(cache)) 209 | self.assertEqual(1, cache.currsize) 210 | self.assertEqual((1, 1), cache.popitem()) 211 | 212 | def _test_getsizeof(self, cache): 213 | self.assertEqual(0, cache.currsize) 214 | self.assertEqual(3, cache.maxsize) 215 | self.assertEqual(1, cache.getsizeof(1)) 216 | self.assertEqual(2, cache.getsizeof(2)) 217 | self.assertEqual(3, cache.getsizeof(3)) 218 | 219 | cache.update({1: 1, 2: 2}) 220 | self.assertEqual(2, len(cache)) 221 | self.assertEqual(3, cache.currsize) 222 | self.assertEqual(1, cache[1]) 223 | self.assertEqual(2, cache[2]) 224 | 225 | cache[1] = 2 226 | self.assertEqual(1, len(cache)) 227 | self.assertEqual(2, cache.currsize) 228 | self.assertEqual(2, cache[1]) 229 | self.assertNotIn(2, cache) 230 | 231 | cache.update({1: 1, 2: 2}) 232 | self.assertEqual(2, len(cache)) 233 | self.assertEqual(3, cache.currsize) 234 | self.assertEqual(1, cache[1]) 235 | self.assertEqual(2, cache[2]) 236 | 237 | cache[3] = 3 238 | self.assertEqual(1, len(cache)) 239 | self.assertEqual(3, cache.currsize) 240 | self.assertEqual(3, cache[3]) 241 | self.assertNotIn(1, cache) 242 | self.assertNotIn(2, cache) 243 | 244 | with self.assertRaises(ValueError): 245 | cache[3] = 4 246 | self.assertEqual(1, len(cache)) 247 | self.assertEqual(3, cache.currsize) 248 | self.assertEqual(3, cache[3]) 249 | 250 | with self.assertRaises(ValueError): 251 | cache[4] = 4 252 | self.assertEqual(1, len(cache)) 253 | self.assertEqual(3, cache.currsize) 254 | self.assertEqual(3, cache[3]) 255 | 256 | def test_getsizeof_param(self): 257 | self._test_getsizeof(self.Cache(maxsize=3, getsizeof=lambda x: x)) 258 | 259 | def test_getsizeof_subclass(self): 260 | class Cache(self.Cache): 261 | def getsizeof(self, value): 262 | return value 263 | 264 | self._test_getsizeof(Cache(maxsize=3)) 265 | 266 | def test_pickle(self): 267 | import pickle 268 | 269 | source = self.Cache(maxsize=2) 270 | source.update({1: 1, 2: 2}) 271 | 272 | cache = pickle.loads(pickle.dumps(source)) 273 | self.assertEqual(source, cache) 274 | 275 | self.assertEqual(2, len(cache)) 276 | self.assertEqual(1, cache[1]) 277 | self.assertEqual(2, cache[2]) 278 | 279 | cache[3] = 3 280 | self.assertEqual(2, len(cache)) 281 | self.assertEqual(3, cache[3]) 282 | self.assertTrue(1 in cache or 2 in cache) 283 | 284 | cache[4] = 4 285 | self.assertEqual(2, len(cache)) 286 | self.assertEqual(4, cache[4]) 287 | self.assertTrue(1 in cache or 2 in cache or 3 in cache) 288 | 289 | self.assertEqual(cache, pickle.loads(pickle.dumps(cache))) 290 | 291 | def test_pickle_maxsize(self): 292 | import pickle 293 | import sys 294 | 295 | # test empty cache, single element, large cache (recursion limit) 296 | for n in [0, 1, sys.getrecursionlimit() * 2]: 297 | source = self.Cache(maxsize=n) 298 | source.update((i, i) for i in range(n)) 299 | cache = pickle.loads(pickle.dumps(source)) 300 | self.assertEqual(n, len(cache)) 301 | self.assertEqual(source, cache) 302 | -------------------------------------------------------------------------------- /tests/test_cache.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | import cachetools 4 | 5 | from . import CacheTestMixin 6 | 7 | 8 | class CacheTest(unittest.TestCase, CacheTestMixin): 9 | Cache = cachetools.Cache 10 | -------------------------------------------------------------------------------- /tests/test_cached.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | import warnings 3 | 4 | import cachetools 5 | import cachetools.keys 6 | 7 | 8 | class CountedLock: 9 | def __init__(self): 10 | self.count = 0 11 | 12 | def __enter__(self): 13 | self.count += 1 14 | 15 | def __exit__(self, *exc): 16 | pass 17 | 18 | 19 | class CountedCondition(CountedLock): 20 | def __init__(self): 21 | CountedLock.__init__(self) 22 | self.wait_count = 0 23 | self.notify_count = 0 24 | 25 | def wait_for(self, predicate): 26 | self.wait_count += 1 27 | 28 | def notify_all(self): 29 | self.notify_count += 1 30 | 31 | 32 | class DecoratorTestMixin: 33 | def cache(self, minsize): 34 | raise NotImplementedError 35 | 36 | def func(self, *args, **kwargs): 37 | if hasattr(self, "count"): 38 | self.count += 1 39 | else: 40 | self.count = 0 41 | return self.count 42 | 43 | def test_decorator(self): 44 | cache = self.cache(2) 45 | wrapper = cachetools.cached(cache)(self.func) 46 | 47 | self.assertEqual(len(cache), 0) 48 | self.assertEqual(wrapper(0), 0) 49 | self.assertEqual(len(cache), 1) 50 | self.assertIn(cachetools.keys.hashkey(0), cache) 51 | self.assertNotIn(cachetools.keys.hashkey(1), cache) 52 | self.assertNotIn(cachetools.keys.hashkey(1.0), cache) 53 | 54 | self.assertEqual(wrapper(1), 1) 55 | self.assertEqual(len(cache), 2) 56 | self.assertIn(cachetools.keys.hashkey(0), cache) 57 | self.assertIn(cachetools.keys.hashkey(1), cache) 58 | self.assertIn(cachetools.keys.hashkey(1.0), cache) 59 | 60 | self.assertEqual(wrapper(1), 1) 61 | self.assertEqual(len(cache), 2) 62 | 63 | self.assertEqual(wrapper(1.0), 1) 64 | self.assertEqual(len(cache), 2) 65 | 66 | self.assertEqual(wrapper(1.0), 1) 67 | self.assertEqual(len(cache), 2) 68 | 69 | def test_decorator_typed(self): 70 | cache = self.cache(3) 71 | key = cachetools.keys.typedkey 72 | wrapper = cachetools.cached(cache, key=key)(self.func) 73 | 74 | self.assertEqual(len(cache), 0) 75 | self.assertEqual(wrapper(0), 0) 76 | self.assertEqual(len(cache), 1) 77 | self.assertIn(cachetools.keys.typedkey(0), cache) 78 | self.assertNotIn(cachetools.keys.typedkey(1), cache) 79 | self.assertNotIn(cachetools.keys.typedkey(1.0), cache) 80 | 81 | self.assertEqual(wrapper(1), 1) 82 | self.assertEqual(len(cache), 2) 83 | self.assertIn(cachetools.keys.typedkey(0), cache) 84 | self.assertIn(cachetools.keys.typedkey(1), cache) 85 | self.assertNotIn(cachetools.keys.typedkey(1.0), cache) 86 | 87 | self.assertEqual(wrapper(1), 1) 88 | self.assertEqual(len(cache), 2) 89 | 90 | self.assertEqual(wrapper(1.0), 2) 91 | self.assertEqual(len(cache), 3) 92 | self.assertIn(cachetools.keys.typedkey(0), cache) 93 | self.assertIn(cachetools.keys.typedkey(1), cache) 94 | self.assertIn(cachetools.keys.typedkey(1.0), cache) 95 | 96 | self.assertEqual(wrapper(1.0), 2) 97 | self.assertEqual(len(cache), 3) 98 | 99 | def test_decorator_lock(self): 100 | cache = self.cache(2) 101 | lock = CountedLock() 102 | wrapper = cachetools.cached(cache, lock=lock)(self.func) 103 | 104 | self.assertEqual(len(cache), 0) 105 | self.assertEqual(wrapper(0), 0) 106 | self.assertEqual(lock.count, 2) 107 | self.assertEqual(wrapper(1), 1) 108 | self.assertEqual(lock.count, 4) 109 | self.assertEqual(wrapper(1), 1) 110 | self.assertEqual(lock.count, 5) 111 | 112 | def test_decorator_condition(self): 113 | cache = self.cache(2) 114 | lock = cond = CountedCondition() 115 | wrapper = cachetools.cached(cache, condition=cond)(self.func) 116 | 117 | self.assertEqual(len(cache), 0) 118 | self.assertEqual(wrapper(0), 0) 119 | self.assertEqual(lock.count, 3) 120 | self.assertEqual(cond.wait_count, 1) 121 | self.assertEqual(cond.notify_count, 1) 122 | self.assertEqual(wrapper(1), 1) 123 | self.assertEqual(lock.count, 6) 124 | self.assertEqual(cond.wait_count, 2) 125 | self.assertEqual(cond.notify_count, 2) 126 | self.assertEqual(wrapper(1), 1) 127 | self.assertEqual(lock.count, 7) 128 | self.assertEqual(cond.wait_count, 3) 129 | self.assertEqual(cond.notify_count, 2) 130 | 131 | def test_decorator_lock_condition(self): 132 | cache = self.cache(2) 133 | lock = CountedLock() 134 | cond = CountedCondition() 135 | wrapper = cachetools.cached(cache, lock=lock, condition=cond)(self.func) 136 | 137 | self.assertEqual(len(cache), 0) 138 | self.assertEqual(wrapper(0), 0) 139 | self.assertEqual(lock.count, 3) 140 | self.assertEqual(cond.wait_count, 1) 141 | self.assertEqual(cond.notify_count, 1) 142 | self.assertEqual(wrapper(1), 1) 143 | self.assertEqual(lock.count, 6) 144 | self.assertEqual(cond.wait_count, 2) 145 | self.assertEqual(cond.notify_count, 2) 146 | self.assertEqual(wrapper(1), 1) 147 | self.assertEqual(lock.count, 7) 148 | self.assertEqual(cond.wait_count, 3) 149 | self.assertEqual(cond.notify_count, 2) 150 | 151 | def test_decorator_wrapped(self): 152 | cache = self.cache(2) 153 | wrapper = cachetools.cached(cache)(self.func) 154 | 155 | self.assertEqual(wrapper.__wrapped__, self.func) 156 | 157 | self.assertEqual(len(cache), 0) 158 | self.assertEqual(wrapper.__wrapped__(0), 0) 159 | self.assertEqual(len(cache), 0) 160 | self.assertEqual(wrapper(0), 1) 161 | self.assertEqual(len(cache), 1) 162 | self.assertEqual(wrapper(0), 1) 163 | self.assertEqual(len(cache), 1) 164 | 165 | def test_decorator_attributes(self): 166 | cache = self.cache(2) 167 | wrapper = cachetools.cached(cache)(self.func) 168 | 169 | self.assertIs(wrapper.cache, cache) 170 | self.assertIs(wrapper.cache_key, cachetools.keys.hashkey) 171 | self.assertIs(wrapper.cache_lock, None) 172 | self.assertIs(wrapper.cache_condition, None) 173 | 174 | def test_decorator_attributes_lock(self): 175 | cache = self.cache(2) 176 | lock = CountedLock() 177 | wrapper = cachetools.cached(cache, lock=lock)(self.func) 178 | 179 | self.assertIs(wrapper.cache, cache) 180 | self.assertIs(wrapper.cache_key, cachetools.keys.hashkey) 181 | self.assertIs(wrapper.cache_lock, lock) 182 | self.assertIs(wrapper.cache_condition, None) 183 | 184 | def test_decorator_attributes_condition(self): 185 | cache = self.cache(2) 186 | lock = cond = CountedCondition() 187 | wrapper = cachetools.cached(cache, condition=cond)(self.func) 188 | 189 | self.assertIs(wrapper.cache, cache) 190 | self.assertIs(wrapper.cache_key, cachetools.keys.hashkey) 191 | self.assertIs(wrapper.cache_lock, lock) 192 | self.assertIs(wrapper.cache_condition, cond) 193 | 194 | def test_decorator_clear(self): 195 | cache = self.cache(2) 196 | wrapper = cachetools.cached(cache)(self.func) 197 | self.assertEqual(wrapper(0), 0) 198 | self.assertEqual(len(cache), 1) 199 | wrapper.cache_clear() 200 | self.assertEqual(len(cache), 0) 201 | 202 | def test_decorator_clear_lock(self): 203 | cache = self.cache(2) 204 | lock = CountedLock() 205 | wrapper = cachetools.cached(cache, lock=lock)(self.func) 206 | self.assertEqual(wrapper(0), 0) 207 | self.assertEqual(len(cache), 1) 208 | self.assertEqual(lock.count, 2) 209 | wrapper.cache_clear() 210 | self.assertEqual(len(cache), 0) 211 | self.assertEqual(lock.count, 3) 212 | 213 | def test_decorator_clear_condition(self): 214 | cache = self.cache(2) 215 | lock = cond = CountedCondition() 216 | wrapper = cachetools.cached(cache, condition=cond)(self.func) 217 | self.assertEqual(wrapper(0), 0) 218 | self.assertEqual(len(cache), 1) 219 | self.assertEqual(lock.count, 3) 220 | wrapper.cache_clear() 221 | self.assertEqual(len(cache), 0) 222 | self.assertEqual(lock.count, 4) 223 | 224 | 225 | class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin): 226 | def cache(self, minsize): 227 | return cachetools.Cache(maxsize=minsize) 228 | 229 | def test_decorator_info(self): 230 | cache = self.cache(2) 231 | wrapper = cachetools.cached(cache, info=True)(self.func) 232 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 233 | self.assertEqual(wrapper(0), 0) 234 | self.assertEqual(wrapper.cache_info(), (0, 1, 2, 1)) 235 | self.assertEqual(wrapper(1), 1) 236 | self.assertEqual(wrapper.cache_info(), (0, 2, 2, 2)) 237 | self.assertEqual(wrapper(0), 0) 238 | self.assertEqual(wrapper.cache_info(), (1, 2, 2, 2)) 239 | wrapper.cache_clear() 240 | self.assertEqual(len(cache), 0) 241 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 242 | 243 | def test_decorator_lock_info(self): 244 | cache = self.cache(2) 245 | lock = CountedLock() 246 | wrapper = cachetools.cached(cache, lock=lock, info=True)(self.func) 247 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 248 | self.assertEqual(lock.count, 1) 249 | self.assertEqual(wrapper(0), 0) 250 | self.assertEqual(lock.count, 3) 251 | self.assertEqual(wrapper.cache_info(), (0, 1, 2, 1)) 252 | self.assertEqual(lock.count, 4) 253 | self.assertEqual(wrapper(1), 1) 254 | self.assertEqual(lock.count, 6) 255 | self.assertEqual(wrapper.cache_info(), (0, 2, 2, 2)) 256 | self.assertEqual(lock.count, 7) 257 | self.assertEqual(wrapper(0), 0) 258 | self.assertEqual(lock.count, 8) 259 | self.assertEqual(wrapper.cache_info(), (1, 2, 2, 2)) 260 | self.assertEqual(lock.count, 9) 261 | wrapper.cache_clear() 262 | self.assertEqual(lock.count, 10) 263 | self.assertEqual(len(cache), 0) 264 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 265 | self.assertEqual(lock.count, 11) 266 | 267 | def test_decorator_lock_info_deprecated(self): 268 | cache = self.cache(2) 269 | key = cachetools.keys.hashkey 270 | lock = CountedLock() 271 | with warnings.catch_warnings(record=True) as w: 272 | warnings.simplefilter("always") 273 | # passing `ìnfo` as positional parameter is deprecated 274 | wrapper = cachetools.cached(cache, key, lock, True)(self.func) 275 | self.assertEqual(len(w), 1) 276 | self.assertIs(w[0].category, DeprecationWarning) 277 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 278 | 279 | def test_decorator_condition_info(self): 280 | cache = self.cache(2) 281 | lock = cond = CountedCondition() 282 | wrapper = cachetools.cached(cache, condition=cond, info=True)(self.func) 283 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 284 | self.assertEqual(lock.count, 1) 285 | self.assertEqual(wrapper(0), 0) 286 | self.assertEqual(lock.count, 4) 287 | self.assertEqual(wrapper.cache_info(), (0, 1, 2, 1)) 288 | self.assertEqual(lock.count, 5) 289 | self.assertEqual(wrapper(1), 1) 290 | self.assertEqual(lock.count, 8) 291 | self.assertEqual(wrapper.cache_info(), (0, 2, 2, 2)) 292 | self.assertEqual(lock.count, 9) 293 | self.assertEqual(wrapper(0), 0) 294 | self.assertEqual(lock.count, 10) 295 | self.assertEqual(wrapper.cache_info(), (1, 2, 2, 2)) 296 | self.assertEqual(lock.count, 11) 297 | wrapper.cache_clear() 298 | self.assertEqual(lock.count, 12) 299 | self.assertEqual(len(cache), 0) 300 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 301 | self.assertEqual(lock.count, 13) 302 | 303 | def test_decorator_lock_condition_info(self): 304 | cache = self.cache(2) 305 | lock = CountedLock() 306 | cond = CountedCondition() 307 | wrapper = cachetools.cached(cache, lock=lock, condition=cond, info=True)( 308 | self.func 309 | ) 310 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 311 | self.assertEqual(lock.count, 1) 312 | self.assertEqual(wrapper(0), 0) 313 | self.assertEqual(lock.count, 4) 314 | self.assertEqual(wrapper.cache_info(), (0, 1, 2, 1)) 315 | self.assertEqual(lock.count, 5) 316 | self.assertEqual(wrapper(1), 1) 317 | self.assertEqual(lock.count, 8) 318 | self.assertEqual(wrapper.cache_info(), (0, 2, 2, 2)) 319 | self.assertEqual(lock.count, 9) 320 | self.assertEqual(wrapper(0), 0) 321 | self.assertEqual(lock.count, 10) 322 | self.assertEqual(wrapper.cache_info(), (1, 2, 2, 2)) 323 | self.assertEqual(lock.count, 11) 324 | wrapper.cache_clear() 325 | self.assertEqual(lock.count, 12) 326 | self.assertEqual(len(cache), 0) 327 | self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0)) 328 | self.assertEqual(lock.count, 13) 329 | 330 | def test_zero_size_cache_decorator(self): 331 | cache = self.cache(0) 332 | wrapper = cachetools.cached(cache)(self.func) 333 | 334 | self.assertEqual(len(cache), 0) 335 | self.assertEqual(wrapper(0), 0) 336 | self.assertEqual(len(cache), 0) 337 | 338 | def test_zero_size_cache_decorator_lock(self): 339 | cache = self.cache(0) 340 | lock = CountedLock() 341 | wrapper = cachetools.cached(cache, lock=lock)(self.func) 342 | 343 | self.assertEqual(len(cache), 0) 344 | self.assertEqual(wrapper(0), 0) 345 | self.assertEqual(len(cache), 0) 346 | self.assertEqual(lock.count, 2) 347 | 348 | def test_zero_size_cache_decorator_condition(self): 349 | cache = self.cache(0) 350 | lock = cond = CountedCondition() 351 | wrapper = cachetools.cached(cache, condition=cond)(self.func) 352 | 353 | self.assertEqual(len(cache), 0) 354 | self.assertEqual(wrapper(0), 0) 355 | self.assertEqual(len(cache), 0) 356 | self.assertEqual(lock.count, 3) 357 | 358 | def test_zero_size_cache_decorator_info(self): 359 | cache = self.cache(0) 360 | wrapper = cachetools.cached(cache, info=True)(self.func) 361 | 362 | self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0)) 363 | self.assertEqual(wrapper(0), 0) 364 | self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0)) 365 | 366 | def test_zero_size_cache_decorator_lock_info(self): 367 | cache = self.cache(0) 368 | lock = CountedLock() 369 | wrapper = cachetools.cached(cache, lock=lock, info=True)(self.func) 370 | 371 | self.assertEqual(len(cache), 0) 372 | self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0)) 373 | self.assertEqual(lock.count, 1) 374 | self.assertEqual(wrapper(0), 0) 375 | self.assertEqual(len(cache), 0) 376 | self.assertEqual(lock.count, 3) 377 | self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0)) 378 | self.assertEqual(lock.count, 4) 379 | 380 | 381 | class DictWrapperTest(unittest.TestCase, DecoratorTestMixin): 382 | def cache(self, minsize): 383 | return dict() 384 | 385 | def test_decorator_info(self): 386 | cache = self.cache(2) 387 | wrapper = cachetools.cached(cache, info=True)(self.func) 388 | self.assertEqual(wrapper.cache_info(), (0, 0, None, 0)) 389 | self.assertEqual(wrapper(0), 0) 390 | self.assertEqual(wrapper.cache_info(), (0, 1, None, 1)) 391 | self.assertEqual(wrapper(1), 1) 392 | self.assertEqual(wrapper.cache_info(), (0, 2, None, 2)) 393 | self.assertEqual(wrapper(0), 0) 394 | self.assertEqual(wrapper.cache_info(), (1, 2, None, 2)) 395 | wrapper.cache_clear() 396 | self.assertEqual(len(cache), 0) 397 | self.assertEqual(wrapper.cache_info(), (0, 0, None, 0)) 398 | 399 | 400 | class NoneWrapperTest(unittest.TestCase): 401 | def func(self, *args, **kwargs): 402 | return args + tuple(kwargs.items()) 403 | 404 | def test_decorator(self): 405 | wrapper = cachetools.cached(None)(self.func) 406 | 407 | self.assertEqual(wrapper(0), (0,)) 408 | self.assertEqual(wrapper(1), (1,)) 409 | self.assertEqual(wrapper(1, foo="bar"), (1, ("foo", "bar"))) 410 | 411 | def test_decorator_attributes(self): 412 | wrapper = cachetools.cached(None)(self.func) 413 | 414 | self.assertIs(wrapper.cache, None) 415 | self.assertIs(wrapper.cache_key, cachetools.keys.hashkey) 416 | self.assertIs(wrapper.cache_lock, None) 417 | 418 | def test_decorator_clear(self): 419 | wrapper = cachetools.cached(None)(self.func) 420 | 421 | wrapper.cache_clear() # no-op 422 | 423 | def test_decorator_info(self): 424 | wrapper = cachetools.cached(None, info=True)(self.func) 425 | 426 | self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0)) 427 | self.assertEqual(wrapper(0), (0,)) 428 | self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0)) 429 | self.assertEqual(wrapper(1), (1,)) 430 | self.assertEqual(wrapper.cache_info(), (0, 2, 0, 0)) 431 | wrapper.cache_clear() 432 | self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0)) 433 | -------------------------------------------------------------------------------- /tests/test_cachedmethod.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | import warnings 3 | 4 | 5 | from cachetools import LRUCache, cachedmethod, keys 6 | 7 | 8 | class Cached: 9 | def __init__(self, cache, count=0): 10 | self.cache = cache 11 | self.count = count 12 | 13 | @cachedmethod(lambda self: self.cache) 14 | def get(self, value): 15 | count = self.count 16 | self.count += 1 17 | return count 18 | 19 | @cachedmethod(lambda self: self.cache, key=keys.typedmethodkey) 20 | def get_typedmethod(self, value): 21 | count = self.count 22 | self.count += 1 23 | return count 24 | 25 | 26 | class Locked: 27 | def __init__(self, cache): 28 | self.cache = cache 29 | self.count = 0 30 | self.lock_count = 0 31 | 32 | @cachedmethod(lambda self: self.cache, lock=lambda self: self) 33 | def get(self, value): 34 | count = self.count 35 | self.count += 1 36 | return count 37 | 38 | def __enter__(self): 39 | self.lock_count += 1 40 | 41 | def __exit__(self, *exc): 42 | pass 43 | 44 | 45 | class Conditioned(Locked): 46 | def __init__(self, cache): 47 | Locked.__init__(self, cache) 48 | self.wait_count = 0 49 | self.notify_count = 0 50 | 51 | @cachedmethod(lambda self: self.cache, condition=lambda self: self) 52 | def get(self, value): 53 | return Locked.get.__wrapped__(self, value) 54 | 55 | @cachedmethod( 56 | lambda self: self.cache, lock=lambda self: self, condition=lambda self: self 57 | ) 58 | def get_lock(self, value): 59 | return Locked.get.__wrapped__(self, value) 60 | 61 | def wait_for(self, predicate): 62 | self.wait_count += 1 63 | 64 | def notify_all(self): 65 | self.notify_count += 1 66 | 67 | 68 | class Unhashable: 69 | def __init__(self, cache): 70 | self.cache = cache 71 | 72 | @cachedmethod(lambda self: self.cache) 73 | def get_default(self, value): 74 | return value 75 | 76 | @cachedmethod(lambda self: self.cache, key=keys.hashkey) 77 | def get_hashkey(self, value): 78 | return value 79 | 80 | # https://github.com/tkem/cachetools/issues/107 81 | def __hash__(self): 82 | raise TypeError("unhashable type") 83 | 84 | 85 | class CachedMethodTest(unittest.TestCase): 86 | def test_dict(self): 87 | cached = Cached({}) 88 | 89 | self.assertEqual(cached.get(0), 0) 90 | self.assertEqual(cached.get(1), 1) 91 | self.assertEqual(cached.get(1), 1) 92 | self.assertEqual(cached.get(1.0), 1) 93 | self.assertEqual(cached.get(1.0), 1) 94 | 95 | cached.cache.clear() 96 | self.assertEqual(cached.get(1), 2) 97 | 98 | def test_typedmethod_dict(self): 99 | cached = Cached(LRUCache(maxsize=2)) 100 | 101 | self.assertEqual(cached.get_typedmethod(0), 0) 102 | self.assertEqual(cached.get_typedmethod(1), 1) 103 | self.assertEqual(cached.get_typedmethod(1), 1) 104 | self.assertEqual(cached.get_typedmethod(1.0), 2) 105 | self.assertEqual(cached.get_typedmethod(1.0), 2) 106 | self.assertEqual(cached.get_typedmethod(0.0), 3) 107 | self.assertEqual(cached.get_typedmethod(0), 4) 108 | 109 | def test_lru(self): 110 | cached = Cached(LRUCache(maxsize=2)) 111 | 112 | self.assertEqual(cached.get(0), 0) 113 | self.assertEqual(cached.get(1), 1) 114 | self.assertEqual(cached.get(1), 1) 115 | self.assertEqual(cached.get(1.0), 1) 116 | self.assertEqual(cached.get(1.0), 1) 117 | 118 | cached.cache.clear() 119 | self.assertEqual(cached.get(1), 2) 120 | 121 | def test_typedmethod_lru(self): 122 | cached = Cached(LRUCache(maxsize=2)) 123 | 124 | self.assertEqual(cached.get_typedmethod(0), 0) 125 | self.assertEqual(cached.get_typedmethod(1), 1) 126 | self.assertEqual(cached.get_typedmethod(1), 1) 127 | self.assertEqual(cached.get_typedmethod(1.0), 2) 128 | self.assertEqual(cached.get_typedmethod(1.0), 2) 129 | self.assertEqual(cached.get_typedmethod(0.0), 3) 130 | self.assertEqual(cached.get_typedmethod(0), 4) 131 | 132 | def test_nospace(self): 133 | cached = Cached(LRUCache(maxsize=0)) 134 | 135 | self.assertEqual(cached.get(0), 0) 136 | self.assertEqual(cached.get(1), 1) 137 | self.assertEqual(cached.get(1), 2) 138 | self.assertEqual(cached.get(1.0), 3) 139 | self.assertEqual(cached.get(1.0), 4) 140 | 141 | def test_nocache(self): 142 | cached = Cached(None) 143 | 144 | with warnings.catch_warnings(record=True) as w: 145 | warnings.simplefilter("always") 146 | 147 | self.assertEqual(cached.get(0), 0) 148 | self.assertEqual(cached.get(1), 1) 149 | self.assertEqual(cached.get(1), 2) 150 | self.assertEqual(cached.get(1.0), 3) 151 | self.assertEqual(cached.get(1.0), 4) 152 | 153 | self.assertEqual(len(w), 5) 154 | self.assertIs(w[0].category, DeprecationWarning) 155 | 156 | def test_weakref(self): 157 | import weakref 158 | import fractions 159 | import gc 160 | 161 | # in Python 3.7, `int` does not support weak references even 162 | # when subclassed, but Fraction apparently does... 163 | class Int(fractions.Fraction): 164 | def __add__(self, other): 165 | return Int(fractions.Fraction.__add__(self, other)) 166 | 167 | cached = Cached(weakref.WeakValueDictionary(), count=Int(0)) 168 | 169 | self.assertEqual(cached.get(0), 0) 170 | gc.collect() 171 | self.assertEqual(cached.get(0), 1) 172 | 173 | ref = cached.get(1) 174 | self.assertEqual(ref, 2) 175 | self.assertEqual(cached.get(1), 2) 176 | self.assertEqual(cached.get(1.0), 2) 177 | 178 | ref = cached.get_typedmethod(1) 179 | self.assertEqual(ref, 3) 180 | self.assertEqual(cached.get_typedmethod(1), 3) 181 | self.assertEqual(cached.get_typedmethod(1.0), 4) 182 | 183 | cached.cache.clear() 184 | self.assertEqual(cached.get(1), 5) 185 | 186 | def test_locked_dict(self): 187 | cached = Locked({}) 188 | 189 | self.assertEqual(cached.get(0), 0) 190 | self.assertEqual(cached.lock_count, 2) 191 | self.assertEqual(cached.get(1), 1) 192 | self.assertEqual(cached.lock_count, 4) 193 | self.assertEqual(cached.get(1), 1) 194 | self.assertEqual(cached.lock_count, 5) 195 | self.assertEqual(cached.get(1.0), 1) 196 | self.assertEqual(cached.lock_count, 6) 197 | self.assertEqual(cached.get(1.0), 1) 198 | self.assertEqual(cached.lock_count, 7) 199 | 200 | cached.cache.clear() 201 | self.assertEqual(cached.get(1), 2) 202 | self.assertEqual(cached.lock_count, 9) 203 | 204 | def test_locked_nospace(self): 205 | cached = Locked(LRUCache(maxsize=0)) 206 | 207 | self.assertEqual(cached.get(0), 0) 208 | self.assertEqual(cached.lock_count, 2) 209 | self.assertEqual(cached.get(1), 1) 210 | self.assertEqual(cached.lock_count, 4) 211 | self.assertEqual(cached.get(1), 2) 212 | self.assertEqual(cached.lock_count, 6) 213 | self.assertEqual(cached.get(1.0), 3) 214 | self.assertEqual(cached.lock_count, 8) 215 | self.assertEqual(cached.get(1.0), 4) 216 | self.assertEqual(cached.lock_count, 10) 217 | 218 | def test_locked_nocache(self): 219 | cached = Locked(None) 220 | 221 | with warnings.catch_warnings(record=True) as w: 222 | warnings.simplefilter("always") 223 | 224 | self.assertEqual(cached.get(0), 0) 225 | self.assertEqual(cached.get(1), 1) 226 | self.assertEqual(cached.get(1), 2) 227 | self.assertEqual(cached.get(1.0), 3) 228 | self.assertEqual(cached.get(1.0), 4) 229 | self.assertEqual(cached.lock_count, 0) 230 | 231 | self.assertEqual(len(w), 5) 232 | self.assertIs(w[0].category, DeprecationWarning) 233 | 234 | def test_condition_dict(self): 235 | cached = Conditioned({}) 236 | 237 | self.assertEqual(cached.get(0), 0) 238 | self.assertEqual(cached.lock_count, 3) 239 | self.assertEqual(cached.wait_count, 1) 240 | self.assertEqual(cached.notify_count, 1) 241 | self.assertEqual(cached.get(1), 1) 242 | self.assertEqual(cached.lock_count, 6) 243 | self.assertEqual(cached.wait_count, 2) 244 | self.assertEqual(cached.notify_count, 2) 245 | self.assertEqual(cached.get(1), 1) 246 | self.assertEqual(cached.lock_count, 7) 247 | self.assertEqual(cached.wait_count, 3) 248 | self.assertEqual(cached.notify_count, 2) 249 | self.assertEqual(cached.get(1.0), 1) 250 | self.assertEqual(cached.lock_count, 8) 251 | self.assertEqual(cached.wait_count, 4) 252 | self.assertEqual(cached.notify_count, 2) 253 | self.assertEqual(cached.get(1.0), 1) 254 | self.assertEqual(cached.lock_count, 9) 255 | self.assertEqual(cached.wait_count, 5) 256 | self.assertEqual(cached.notify_count, 2) 257 | 258 | cached.cache.clear() 259 | self.assertEqual(cached.get(1), 2) 260 | self.assertEqual(cached.lock_count, 12) 261 | self.assertEqual(cached.wait_count, 6) 262 | self.assertEqual(cached.notify_count, 3) 263 | 264 | def test_condition_nospace(self): 265 | cached = Conditioned(LRUCache(maxsize=0)) 266 | 267 | self.assertEqual(cached.get(0), 0) 268 | self.assertEqual(cached.lock_count, 3) 269 | self.assertEqual(cached.wait_count, 1) 270 | self.assertEqual(cached.notify_count, 1) 271 | self.assertEqual(cached.get(1), 1) 272 | self.assertEqual(cached.lock_count, 6) 273 | self.assertEqual(cached.wait_count, 2) 274 | self.assertEqual(cached.notify_count, 2) 275 | self.assertEqual(cached.get(1), 2) 276 | self.assertEqual(cached.lock_count, 9) 277 | self.assertEqual(cached.wait_count, 3) 278 | self.assertEqual(cached.notify_count, 3) 279 | self.assertEqual(cached.get(1.0), 3) 280 | self.assertEqual(cached.lock_count, 12) 281 | self.assertEqual(cached.wait_count, 4) 282 | self.assertEqual(cached.notify_count, 4) 283 | self.assertEqual(cached.get(1.0), 4) 284 | self.assertEqual(cached.lock_count, 15) 285 | self.assertEqual(cached.wait_count, 5) 286 | self.assertEqual(cached.notify_count, 5) 287 | 288 | def test_condition_nocache(self): 289 | cached = Conditioned(None) 290 | 291 | with warnings.catch_warnings(record=True) as w: 292 | warnings.simplefilter("always") 293 | 294 | self.assertEqual(cached.get(0), 0) 295 | self.assertEqual(cached.get(1), 1) 296 | self.assertEqual(cached.get(1), 2) 297 | self.assertEqual(cached.get(1.0), 3) 298 | self.assertEqual(cached.get(1.0), 4) 299 | self.assertEqual(cached.lock_count, 0) 300 | self.assertEqual(cached.wait_count, 0) 301 | self.assertEqual(cached.notify_count, 0) 302 | 303 | self.assertEqual(len(w), 5) 304 | self.assertIs(w[0].category, DeprecationWarning) 305 | 306 | def test_unhashable(self): 307 | cached = Unhashable(LRUCache(maxsize=0)) 308 | 309 | self.assertEqual(cached.get_default(0), 0) 310 | self.assertEqual(cached.get_default(1), 1) 311 | 312 | with self.assertRaises(TypeError): 313 | cached.get_hashkey(0) 314 | 315 | def test_wrapped(self): 316 | cache = {} 317 | cached = Cached(cache) 318 | 319 | self.assertEqual(len(cache), 0) 320 | self.assertEqual(Cached.get.__wrapped__(cached, 0), 0) 321 | self.assertEqual(len(cache), 0) 322 | self.assertEqual(cached.get(0), 1) 323 | self.assertEqual(len(cache), 1) 324 | self.assertEqual(cached.get(0), 1) 325 | self.assertEqual(len(cache), 1) 326 | 327 | def test_attributes(self): 328 | cache = {} 329 | cached = Cached(cache) 330 | 331 | self.assertIs(Cached.get.cache(cached), cache) 332 | self.assertIs(Cached.get.cache_key, keys.methodkey) 333 | self.assertIs(Cached.get.cache_lock, None) 334 | self.assertIs(Cached.get.cache_condition, None) 335 | 336 | def test_attributes_lock(self): 337 | cache = {} 338 | cached = Locked(cache) 339 | 340 | self.assertIs(Locked.get.cache(cached), cache) 341 | self.assertIs(Locked.get.cache_key, keys.methodkey) 342 | self.assertIs(Locked.get.cache_lock(cached), cached) 343 | self.assertIs(Locked.get.cache_condition, None) 344 | 345 | def test_attributes_cond(self): 346 | cache = {} 347 | cached = Conditioned(cache) 348 | 349 | self.assertIs(Conditioned.get.cache(cached), cache) 350 | self.assertIs(Conditioned.get.cache_key, keys.methodkey) 351 | self.assertIs(Conditioned.get.cache_lock(cached), cached) 352 | self.assertIs(Conditioned.get.cache_condition(cached), cached) 353 | 354 | def test_clear(self): 355 | cache = {} 356 | cached = Cached(cache) 357 | 358 | self.assertEqual(cached.get(0), 0) 359 | self.assertEqual(len(cache), 1) 360 | Cached.get.cache_clear(cached) 361 | self.assertEqual(len(cache), 0) 362 | 363 | def test_clear_locked(self): 364 | cache = {} 365 | cached = Locked(cache) 366 | 367 | self.assertEqual(cached.get(0), 0) 368 | self.assertEqual(len(cache), 1) 369 | self.assertEqual(cached.lock_count, 2) 370 | Locked.get.cache_clear(cached) 371 | self.assertEqual(len(cache), 0) 372 | self.assertEqual(cached.lock_count, 3) 373 | 374 | def test_clear_condition(self): 375 | cache = {} 376 | cached = Conditioned(cache) 377 | 378 | self.assertEqual(cached.get(0), 0) 379 | self.assertEqual(len(cache), 1) 380 | self.assertEqual(cached.lock_count, 3) 381 | Conditioned.get.cache_clear(cached) 382 | self.assertEqual(len(cache), 0) 383 | self.assertEqual(cached.lock_count, 4) 384 | -------------------------------------------------------------------------------- /tests/test_fifo.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | from cachetools import FIFOCache 4 | 5 | from . import CacheTestMixin 6 | 7 | 8 | class LRUCacheTest(unittest.TestCase, CacheTestMixin): 9 | Cache = FIFOCache 10 | 11 | def test_fifo(self): 12 | cache = FIFOCache(maxsize=2) 13 | 14 | cache[1] = 1 15 | cache[2] = 2 16 | cache[3] = 3 17 | 18 | self.assertEqual(len(cache), 2) 19 | self.assertEqual(cache[2], 2) 20 | self.assertEqual(cache[3], 3) 21 | self.assertNotIn(1, cache) 22 | 23 | cache[2] 24 | cache[4] = 4 25 | self.assertEqual(len(cache), 2) 26 | self.assertEqual(cache[3], 3) 27 | self.assertEqual(cache[4], 4) 28 | self.assertNotIn(2, cache) 29 | 30 | cache[5] = 5 31 | self.assertEqual(len(cache), 2) 32 | self.assertEqual(cache[4], 4) 33 | self.assertEqual(cache[5], 5) 34 | self.assertNotIn(3, cache) 35 | 36 | def test_fifo_getsizeof(self): 37 | cache = FIFOCache(maxsize=3, getsizeof=lambda x: x) 38 | 39 | cache[1] = 1 40 | cache[2] = 2 41 | 42 | self.assertEqual(len(cache), 2) 43 | self.assertEqual(cache[1], 1) 44 | self.assertEqual(cache[2], 2) 45 | 46 | cache[3] = 3 47 | 48 | self.assertEqual(len(cache), 1) 49 | self.assertEqual(cache[3], 3) 50 | self.assertNotIn(1, cache) 51 | self.assertNotIn(2, cache) 52 | 53 | with self.assertRaises(ValueError): 54 | cache[4] = 4 55 | self.assertEqual(len(cache), 1) 56 | self.assertEqual(cache[3], 3) 57 | -------------------------------------------------------------------------------- /tests/test_func.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | import cachetools.func 4 | 5 | 6 | class DecoratorTestMixin: 7 | def decorator(self, maxsize, **kwargs): 8 | return self.DECORATOR(maxsize, **kwargs) 9 | 10 | def test_decorator(self): 11 | cached = self.decorator(maxsize=2)(lambda n: n) 12 | self.assertEqual(cached.cache_parameters(), {"maxsize": 2, "typed": False}) 13 | self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) 14 | self.assertEqual(cached(1), 1) 15 | self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) 16 | self.assertEqual(cached(1), 1) 17 | self.assertEqual(cached.cache_info(), (1, 1, 2, 1)) 18 | self.assertEqual(cached(1.0), 1.0) 19 | self.assertEqual(cached.cache_info(), (2, 1, 2, 1)) 20 | 21 | def test_decorator_clear(self): 22 | cached = self.decorator(maxsize=2)(lambda n: n) 23 | self.assertEqual(cached.cache_parameters(), {"maxsize": 2, "typed": False}) 24 | self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) 25 | self.assertEqual(cached(1), 1) 26 | self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) 27 | cached.cache_clear() 28 | self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) 29 | self.assertEqual(cached(1), 1) 30 | self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) 31 | 32 | def test_decorator_nocache(self): 33 | cached = self.decorator(maxsize=0)(lambda n: n) 34 | self.assertEqual(cached.cache_parameters(), {"maxsize": 0, "typed": False}) 35 | self.assertEqual(cached.cache_info(), (0, 0, 0, 0)) 36 | self.assertEqual(cached(1), 1) 37 | self.assertEqual(cached.cache_info(), (0, 1, 0, 0)) 38 | self.assertEqual(cached(1), 1) 39 | self.assertEqual(cached.cache_info(), (0, 2, 0, 0)) 40 | self.assertEqual(cached(1.0), 1.0) 41 | self.assertEqual(cached.cache_info(), (0, 3, 0, 0)) 42 | 43 | def test_decorator_unbound(self): 44 | cached = self.decorator(maxsize=None)(lambda n: n) 45 | self.assertEqual(cached.cache_parameters(), {"maxsize": None, "typed": False}) 46 | self.assertEqual(cached.cache_info(), (0, 0, None, 0)) 47 | self.assertEqual(cached(1), 1) 48 | self.assertEqual(cached.cache_info(), (0, 1, None, 1)) 49 | self.assertEqual(cached(1), 1) 50 | self.assertEqual(cached.cache_info(), (1, 1, None, 1)) 51 | self.assertEqual(cached(1.0), 1.0) 52 | self.assertEqual(cached.cache_info(), (2, 1, None, 1)) 53 | 54 | def test_decorator_typed(self): 55 | cached = self.decorator(maxsize=2, typed=True)(lambda n: n) 56 | self.assertEqual(cached.cache_parameters(), {"maxsize": 2, "typed": True}) 57 | self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) 58 | self.assertEqual(cached(1), 1) 59 | self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) 60 | self.assertEqual(cached(1), 1) 61 | self.assertEqual(cached.cache_info(), (1, 1, 2, 1)) 62 | self.assertEqual(cached(1.0), 1.0) 63 | self.assertEqual(cached.cache_info(), (1, 2, 2, 2)) 64 | self.assertEqual(cached(1.0), 1.0) 65 | self.assertEqual(cached.cache_info(), (2, 2, 2, 2)) 66 | 67 | def test_decorator_user_function(self): 68 | cached = self.decorator(lambda n: n) 69 | self.assertEqual(cached.cache_parameters(), {"maxsize": 128, "typed": False}) 70 | self.assertEqual(cached.cache_info(), (0, 0, 128, 0)) 71 | self.assertEqual(cached(1), 1) 72 | self.assertEqual(cached.cache_info(), (0, 1, 128, 1)) 73 | self.assertEqual(cached(1), 1) 74 | self.assertEqual(cached.cache_info(), (1, 1, 128, 1)) 75 | self.assertEqual(cached(1.0), 1.0) 76 | self.assertEqual(cached.cache_info(), (2, 1, 128, 1)) 77 | 78 | def test_decorator_needs_rlock(self): 79 | cached = self.decorator(lambda n: n) 80 | 81 | class RecursiveEquals: 82 | def __init__(self, use_cache): 83 | self._use_cache = use_cache 84 | 85 | def __hash__(self): 86 | return hash(self._use_cache) 87 | 88 | def __eq__(self, other): 89 | if self._use_cache: 90 | # This call will happen while the cache-lock is held, 91 | # requiring a reentrant lock to avoid deadlock. 92 | cached(self) 93 | return self._use_cache == other._use_cache 94 | 95 | # Prime the cache. 96 | cached(RecursiveEquals(False)) 97 | cached(RecursiveEquals(True)) 98 | # Then do a call which will cause a deadlock with a non-reentrant lock. 99 | self.assertEqual(cached(RecursiveEquals(True)), RecursiveEquals(True)) 100 | 101 | 102 | class FIFODecoratorTest(unittest.TestCase, DecoratorTestMixin): 103 | DECORATOR = staticmethod(cachetools.func.fifo_cache) 104 | 105 | 106 | class LFUDecoratorTest(unittest.TestCase, DecoratorTestMixin): 107 | DECORATOR = staticmethod(cachetools.func.lfu_cache) 108 | 109 | 110 | class LRUDecoratorTest(unittest.TestCase, DecoratorTestMixin): 111 | DECORATOR = staticmethod(cachetools.func.lru_cache) 112 | 113 | 114 | class RRDecoratorTest(unittest.TestCase, DecoratorTestMixin): 115 | DECORATOR = staticmethod(cachetools.func.rr_cache) 116 | 117 | 118 | class TTLDecoratorTest(unittest.TestCase, DecoratorTestMixin): 119 | DECORATOR = staticmethod(cachetools.func.ttl_cache) 120 | -------------------------------------------------------------------------------- /tests/test_keys.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | import cachetools.keys 4 | 5 | 6 | class CacheKeysTest(unittest.TestCase): 7 | def test_hashkey(self, key=cachetools.keys.hashkey): 8 | self.assertEqual(key(), key()) 9 | self.assertEqual(hash(key()), hash(key())) 10 | self.assertEqual(key(1, 2, 3), key(1, 2, 3)) 11 | self.assertEqual(hash(key(1, 2, 3)), hash(key(1, 2, 3))) 12 | self.assertEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=0)) 13 | self.assertEqual(hash(key(1, 2, 3, x=0)), hash(key(1, 2, 3, x=0))) 14 | self.assertNotEqual(key(1, 2, 3), key(3, 2, 1)) 15 | self.assertNotEqual(key(1, 2, 3), key(1, 2, 3, x=None)) 16 | self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=None)) 17 | self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, y=0)) 18 | with self.assertRaises(TypeError): 19 | hash(key({})) 20 | # untyped keys compare equal 21 | self.assertEqual(key(1, 2, 3), key(1.0, 2.0, 3.0)) 22 | self.assertEqual(hash(key(1, 2, 3)), hash(key(1.0, 2.0, 3.0))) 23 | 24 | def methodkey(self, key=cachetools.keys.methodkey): 25 | # similar to hashkey(), but ignores its first positional argument 26 | self.assertEqual(key("x"), key("y")) 27 | self.assertEqual(hash(key("x")), hash(key("y"))) 28 | self.assertEqual(key("x", 1, 2, 3), key("y", 1, 2, 3)) 29 | self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1, 2, 3))) 30 | self.assertEqual(key("x", 1, 2, 3, x=0), key("y", 1, 2, 3, x=0)) 31 | self.assertEqual(hash(key("x", 1, 2, 3, x=0)), hash(key("y", 1, 2, 3, x=0))) 32 | self.assertNotEqual(key("x", 1, 2, 3), key("x", 3, 2, 1)) 33 | self.assertNotEqual(key("x", 1, 2, 3), key("x", 1, 2, 3, x=None)) 34 | self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, x=None)) 35 | self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, y=0)) 36 | with self.assertRaises(TypeError): 37 | hash("x", key({})) 38 | # untyped keys compare equal 39 | self.assertEqual(key("x", 1, 2, 3), key("y", 1.0, 2.0, 3.0)) 40 | self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1.0, 2.0, 3.0))) 41 | 42 | def test_typedkey(self, key=cachetools.keys.typedkey): 43 | self.assertEqual(key(), key()) 44 | self.assertEqual(hash(key()), hash(key())) 45 | self.assertEqual(key(1, 2, 3), key(1, 2, 3)) 46 | self.assertEqual(hash(key(1, 2, 3)), hash(key(1, 2, 3))) 47 | self.assertEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=0)) 48 | self.assertEqual(hash(key(1, 2, 3, x=0)), hash(key(1, 2, 3, x=0))) 49 | self.assertNotEqual(key(1, 2, 3), key(3, 2, 1)) 50 | self.assertNotEqual(key(1, 2, 3), key(1, 2, 3, x=None)) 51 | self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=None)) 52 | self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, y=0)) 53 | with self.assertRaises(TypeError): 54 | hash(key({})) 55 | # typed keys compare unequal 56 | self.assertNotEqual(key(1, 2, 3), key(1.0, 2.0, 3.0)) 57 | 58 | def test_typedmethodkey(self, key=cachetools.keys.typedmethodkey): 59 | # similar to typedkey(), but ignores its first positional argument 60 | self.assertEqual(key("x"), key("y")) 61 | self.assertEqual(hash(key("x")), hash(key("y"))) 62 | self.assertEqual(key("x", 1, 2, 3), key("y", 1, 2, 3)) 63 | self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1, 2, 3))) 64 | self.assertEqual(key("x", 1, 2, 3, x=0), key("y", 1, 2, 3, x=0)) 65 | self.assertEqual(hash(key("x", 1, 2, 3, x=0)), hash(key("y", 1, 2, 3, x=0))) 66 | self.assertNotEqual(key("x", 1, 2, 3), key("x", 3, 2, 1)) 67 | self.assertNotEqual(key("x", 1, 2, 3), key("x", 1, 2, 3, x=None)) 68 | self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, x=None)) 69 | self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, y=0)) 70 | with self.assertRaises(TypeError): 71 | hash(key("x", {})) 72 | # typed keys compare unequal 73 | self.assertNotEqual(key("x", 1, 2, 3), key("x", 1.0, 2.0, 3.0)) 74 | 75 | def test_addkeys(self, key=cachetools.keys.hashkey): 76 | self.assertIsInstance(key(), tuple) 77 | self.assertIsInstance(key(1, 2, 3) + key(4, 5, 6), type(key())) 78 | self.assertIsInstance(key(1, 2, 3) + (4, 5, 6), type(key())) 79 | self.assertIsInstance((1, 2, 3) + key(4, 5, 6), type(key())) 80 | 81 | def test_pickle(self, key=cachetools.keys.hashkey): 82 | import pickle 83 | 84 | for k in [key(), key("abc"), key("abc", 123), key("abc", q="abc")]: 85 | # white-box test: assert cached hash value is not pickled 86 | self.assertEqual(len(k.__dict__), 0) 87 | h = hash(k) 88 | self.assertEqual(len(k.__dict__), 1) 89 | pickled = pickle.loads(pickle.dumps(k)) 90 | self.assertEqual(len(pickled.__dict__), 0) 91 | self.assertEqual(k, pickled) 92 | self.assertEqual(h, hash(pickled)) 93 | -------------------------------------------------------------------------------- /tests/test_lfu.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | from cachetools import LFUCache 4 | 5 | from . import CacheTestMixin 6 | 7 | 8 | class LFUCacheTest(unittest.TestCase, CacheTestMixin): 9 | Cache = LFUCache 10 | 11 | def test_lfu(self): 12 | cache = LFUCache(maxsize=2) 13 | 14 | cache[1] = 1 15 | cache[1] 16 | cache[2] = 2 17 | cache[3] = 3 18 | 19 | self.assertEqual(len(cache), 2) 20 | self.assertEqual(cache[1], 1) 21 | self.assertTrue(2 in cache or 3 in cache) 22 | self.assertTrue(2 not in cache or 3 not in cache) 23 | 24 | cache[4] = 4 25 | self.assertEqual(len(cache), 2) 26 | self.assertEqual(cache[4], 4) 27 | self.assertEqual(cache[1], 1) 28 | 29 | def test_lfu_getsizeof(self): 30 | cache = LFUCache(maxsize=3, getsizeof=lambda x: x) 31 | 32 | cache[1] = 1 33 | cache[2] = 2 34 | 35 | self.assertEqual(len(cache), 2) 36 | self.assertEqual(cache[1], 1) 37 | self.assertEqual(cache[2], 2) 38 | 39 | cache[3] = 3 40 | 41 | self.assertEqual(len(cache), 1) 42 | self.assertEqual(cache[3], 3) 43 | self.assertNotIn(1, cache) 44 | self.assertNotIn(2, cache) 45 | 46 | with self.assertRaises(ValueError): 47 | cache[4] = 4 48 | self.assertEqual(len(cache), 1) 49 | self.assertEqual(cache[3], 3) 50 | -------------------------------------------------------------------------------- /tests/test_lru.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | from cachetools import LRUCache 4 | 5 | from . import CacheTestMixin 6 | 7 | 8 | class LRUCacheTest(unittest.TestCase, CacheTestMixin): 9 | Cache = LRUCache 10 | 11 | def test_lru(self): 12 | cache = LRUCache(maxsize=2) 13 | 14 | cache[1] = 1 15 | cache[2] = 2 16 | cache[3] = 3 17 | 18 | self.assertEqual(len(cache), 2) 19 | self.assertEqual(cache[2], 2) 20 | self.assertEqual(cache[3], 3) 21 | self.assertNotIn(1, cache) 22 | 23 | cache[2] 24 | cache[4] = 4 25 | self.assertEqual(len(cache), 2) 26 | self.assertEqual(cache[2], 2) 27 | self.assertEqual(cache[4], 4) 28 | self.assertNotIn(3, cache) 29 | 30 | cache[5] = 5 31 | self.assertEqual(len(cache), 2) 32 | self.assertEqual(cache[4], 4) 33 | self.assertEqual(cache[5], 5) 34 | self.assertNotIn(2, cache) 35 | 36 | def test_lru_getsizeof(self): 37 | cache = LRUCache(maxsize=3, getsizeof=lambda x: x) 38 | 39 | cache[1] = 1 40 | cache[2] = 2 41 | 42 | self.assertEqual(len(cache), 2) 43 | self.assertEqual(cache[1], 1) 44 | self.assertEqual(cache[2], 2) 45 | 46 | cache[3] = 3 47 | 48 | self.assertEqual(len(cache), 1) 49 | self.assertEqual(cache[3], 3) 50 | self.assertNotIn(1, cache) 51 | self.assertNotIn(2, cache) 52 | 53 | with self.assertRaises(ValueError): 54 | cache[4] = 4 55 | self.assertEqual(len(cache), 1) 56 | self.assertEqual(cache[3], 3) 57 | -------------------------------------------------------------------------------- /tests/test_rr.py: -------------------------------------------------------------------------------- 1 | import unittest 2 | 3 | from cachetools import RRCache 4 | 5 | from . import CacheTestMixin 6 | 7 | 8 | class RRCacheTest(unittest.TestCase, CacheTestMixin): 9 | Cache = RRCache 10 | 11 | def test_rr(self): 12 | cache = RRCache(maxsize=2, choice=min) 13 | self.assertEqual(min, cache.choice) 14 | 15 | cache[1] = 1 16 | cache[2] = 2 17 | cache[3] = 3 18 | 19 | self.assertEqual(2, len(cache)) 20 | self.assertEqual(2, cache[2]) 21 | self.assertEqual(3, cache[3]) 22 | self.assertNotIn(1, cache) 23 | 24 | cache[0] = 0 25 | self.assertEqual(2, len(cache)) 26 | self.assertEqual(0, cache[0]) 27 | self.assertEqual(3, cache[3]) 28 | self.assertNotIn(2, cache) 29 | 30 | cache[4] = 4 31 | self.assertEqual(2, len(cache)) 32 | self.assertEqual(3, cache[3]) 33 | self.assertEqual(4, cache[4]) 34 | self.assertNotIn(0, cache) 35 | -------------------------------------------------------------------------------- /tests/test_tlru.py: -------------------------------------------------------------------------------- 1 | import math 2 | import unittest 3 | 4 | from cachetools import TLRUCache 5 | 6 | from . import CacheTestMixin 7 | 8 | 9 | class Timer: 10 | def __init__(self, auto=False): 11 | self.auto = auto 12 | self.time = 0 13 | 14 | def __call__(self): 15 | if self.auto: 16 | self.time += 1 17 | return self.time 18 | 19 | def tick(self): 20 | self.time += 1 21 | 22 | 23 | class TLRUTestCache(TLRUCache): 24 | def default_ttu(_key, _value, _time): 25 | return math.inf 26 | 27 | def __init__(self, maxsize, ttu=default_ttu, **kwargs): 28 | TLRUCache.__init__(self, maxsize, ttu, timer=Timer(), **kwargs) 29 | 30 | 31 | class TLRUCacheTest(unittest.TestCase, CacheTestMixin): 32 | Cache = TLRUTestCache 33 | 34 | def test_ttu(self): 35 | cache = TLRUCache(maxsize=6, ttu=lambda _, v, t: t + v + 1, timer=Timer()) 36 | self.assertEqual(0, cache.timer()) 37 | self.assertEqual(3, cache.ttu(None, 1, 1)) 38 | 39 | cache[1] = 1 40 | self.assertEqual(1, cache[1]) 41 | self.assertEqual(1, len(cache)) 42 | self.assertEqual({1}, set(cache)) 43 | 44 | cache.timer.tick() 45 | self.assertEqual(1, cache[1]) 46 | self.assertEqual(1, len(cache)) 47 | self.assertEqual({1}, set(cache)) 48 | 49 | cache[2] = 2 50 | self.assertEqual(1, cache[1]) 51 | self.assertEqual(2, cache[2]) 52 | self.assertEqual(2, len(cache)) 53 | self.assertEqual({1, 2}, set(cache)) 54 | 55 | cache.timer.tick() 56 | self.assertNotIn(1, cache) 57 | self.assertEqual(2, cache[2]) 58 | self.assertEqual(1, len(cache)) 59 | self.assertEqual({2}, set(cache)) 60 | 61 | cache[3] = 3 62 | self.assertNotIn(1, cache) 63 | self.assertEqual(2, cache[2]) 64 | self.assertEqual(3, cache[3]) 65 | self.assertEqual(2, len(cache)) 66 | self.assertEqual({2, 3}, set(cache)) 67 | 68 | cache.timer.tick() 69 | self.assertNotIn(1, cache) 70 | self.assertEqual(2, cache[2]) 71 | self.assertEqual(3, cache[3]) 72 | self.assertEqual(2, len(cache)) 73 | self.assertEqual({2, 3}, set(cache)) 74 | 75 | cache[1] = 1 76 | self.assertEqual(1, cache[1]) 77 | self.assertEqual(2, cache[2]) 78 | self.assertEqual(3, cache[3]) 79 | self.assertEqual(3, len(cache)) 80 | self.assertEqual({1, 2, 3}, set(cache)) 81 | 82 | cache.timer.tick() 83 | self.assertEqual(1, cache[1]) 84 | self.assertNotIn(2, cache) 85 | self.assertEqual(3, cache[3]) 86 | self.assertEqual(2, len(cache)) 87 | self.assertEqual({1, 3}, set(cache)) 88 | 89 | cache.timer.tick() 90 | self.assertNotIn(1, cache) 91 | self.assertNotIn(2, cache) 92 | self.assertEqual(3, cache[3]) 93 | self.assertEqual(1, len(cache)) 94 | self.assertEqual({3}, set(cache)) 95 | 96 | cache.timer.tick() 97 | self.assertNotIn(1, cache) 98 | self.assertNotIn(2, cache) 99 | self.assertNotIn(3, cache) 100 | 101 | with self.assertRaises(KeyError): 102 | del cache[1] 103 | with self.assertRaises(KeyError): 104 | cache.pop(2) 105 | with self.assertRaises(KeyError): 106 | del cache[3] 107 | 108 | self.assertEqual(0, len(cache)) 109 | self.assertEqual(set(), set(cache)) 110 | 111 | def test_ttu_lru(self): 112 | cache = TLRUCache(maxsize=2, ttu=lambda k, v, t: t + 1, timer=Timer()) 113 | self.assertEqual(0, cache.timer()) 114 | self.assertEqual(2, cache.ttu(None, None, 1)) 115 | 116 | cache[1] = 1 117 | cache[2] = 2 118 | cache[3] = 3 119 | 120 | self.assertEqual(len(cache), 2) 121 | self.assertNotIn(1, cache) 122 | self.assertEqual(cache[2], 2) 123 | self.assertEqual(cache[3], 3) 124 | 125 | cache[2] 126 | cache[4] = 4 127 | self.assertEqual(len(cache), 2) 128 | self.assertNotIn(1, cache) 129 | self.assertEqual(cache[2], 2) 130 | self.assertNotIn(3, cache) 131 | self.assertEqual(cache[4], 4) 132 | 133 | cache[5] = 5 134 | self.assertEqual(len(cache), 2) 135 | self.assertNotIn(1, cache) 136 | self.assertNotIn(2, cache) 137 | self.assertNotIn(3, cache) 138 | self.assertEqual(cache[4], 4) 139 | self.assertEqual(cache[5], 5) 140 | 141 | def test_ttu_expire(self): 142 | cache = TLRUCache(maxsize=3, ttu=lambda k, v, t: t + 3, timer=Timer()) 143 | with cache.timer as time: 144 | self.assertEqual(time, cache.timer()) 145 | 146 | cache[1] = 1 147 | cache.timer.tick() 148 | cache[2] = 2 149 | cache.timer.tick() 150 | cache[3] = 3 151 | self.assertEqual(2, cache.timer()) 152 | 153 | self.assertEqual({1, 2, 3}, set(cache)) 154 | self.assertEqual(3, len(cache)) 155 | self.assertEqual(1, cache[1]) 156 | self.assertEqual(2, cache[2]) 157 | self.assertEqual(3, cache[3]) 158 | 159 | items = cache.expire() 160 | self.assertEqual(set(), set(items)) 161 | self.assertEqual({1, 2, 3}, set(cache)) 162 | self.assertEqual(3, len(cache)) 163 | self.assertEqual(1, cache[1]) 164 | self.assertEqual(2, cache[2]) 165 | self.assertEqual(3, cache[3]) 166 | 167 | items = cache.expire(3) 168 | self.assertEqual({(1, 1)}, set(items)) 169 | self.assertEqual({2, 3}, set(cache)) 170 | self.assertEqual(2, len(cache)) 171 | self.assertNotIn(1, cache) 172 | self.assertEqual(2, cache[2]) 173 | self.assertEqual(3, cache[3]) 174 | 175 | items = cache.expire(4) 176 | self.assertEqual({(2, 2)}, set(items)) 177 | self.assertEqual({3}, set(cache)) 178 | self.assertEqual(1, len(cache)) 179 | self.assertNotIn(1, cache) 180 | self.assertNotIn(2, cache) 181 | self.assertEqual(3, cache[3]) 182 | 183 | items = cache.expire(5) 184 | self.assertEqual({(3, 3)}, set(items)) 185 | self.assertEqual(set(), set(cache)) 186 | self.assertEqual(0, len(cache)) 187 | self.assertNotIn(1, cache) 188 | self.assertNotIn(2, cache) 189 | self.assertNotIn(3, cache) 190 | 191 | def test_ttu_expired(self): 192 | cache = TLRUCache(maxsize=1, ttu=lambda k, _, t: t + k, timer=Timer()) 193 | cache[1] = None 194 | self.assertEqual(cache[1], None) 195 | self.assertEqual(1, len(cache)) 196 | cache[0] = None 197 | self.assertNotIn(0, cache) 198 | self.assertEqual(cache[1], None) 199 | self.assertEqual(1, len(cache)) 200 | cache[-1] = None 201 | self.assertNotIn(-1, cache) 202 | self.assertNotIn(0, cache) 203 | self.assertEqual(cache[1], None) 204 | self.assertEqual(1, len(cache)) 205 | 206 | def test_ttu_atomic(self): 207 | cache = TLRUCache(maxsize=1, ttu=lambda k, v, t: t + 2, timer=Timer(auto=True)) 208 | cache[1] = 1 209 | self.assertEqual(1, cache[1]) 210 | cache[1] = 1 211 | self.assertEqual(1, cache.get(1)) 212 | cache[1] = 1 213 | self.assertEqual(1, cache.pop(1)) 214 | cache[1] = 1 215 | self.assertEqual(1, cache.setdefault(1)) 216 | cache[1] = 1 217 | cache.clear() 218 | self.assertEqual(0, len(cache)) 219 | 220 | def test_ttu_tuple_key(self): 221 | cache = TLRUCache(maxsize=1, ttu=lambda k, v, t: t + 1, timer=Timer()) 222 | 223 | cache[(1, 2, 3)] = 42 224 | self.assertEqual(42, cache[(1, 2, 3)]) 225 | cache.timer.tick() 226 | with self.assertRaises(KeyError): 227 | cache[(1, 2, 3)] 228 | self.assertNotIn((1, 2, 3), cache) 229 | 230 | def test_ttu_reverse_insert(self): 231 | cache = TLRUCache(maxsize=4, ttu=lambda k, v, t: t + v, timer=Timer()) 232 | self.assertEqual(0, cache.timer()) 233 | 234 | cache[3] = 3 235 | cache[2] = 2 236 | cache[1] = 1 237 | cache[0] = 0 238 | 239 | self.assertEqual({1, 2, 3}, set(cache)) 240 | self.assertEqual(3, len(cache)) 241 | self.assertNotIn(0, cache) 242 | self.assertEqual(1, cache[1]) 243 | self.assertEqual(2, cache[2]) 244 | self.assertEqual(3, cache[3]) 245 | 246 | cache.timer.tick() 247 | 248 | self.assertEqual({2, 3}, set(cache)) 249 | self.assertEqual(2, len(cache)) 250 | self.assertNotIn(0, cache) 251 | self.assertNotIn(1, cache) 252 | self.assertEqual(2, cache[2]) 253 | self.assertEqual(3, cache[3]) 254 | 255 | cache.timer.tick() 256 | 257 | self.assertEqual({3}, set(cache)) 258 | self.assertEqual(1, len(cache)) 259 | self.assertNotIn(0, cache) 260 | self.assertNotIn(1, cache) 261 | self.assertNotIn(2, cache) 262 | self.assertEqual(3, cache[3]) 263 | 264 | cache.timer.tick() 265 | 266 | self.assertEqual(set(), set(cache)) 267 | self.assertEqual(0, len(cache)) 268 | self.assertNotIn(0, cache) 269 | self.assertNotIn(1, cache) 270 | self.assertNotIn(2, cache) 271 | self.assertNotIn(3, cache) 272 | -------------------------------------------------------------------------------- /tests/test_ttl.py: -------------------------------------------------------------------------------- 1 | import math 2 | import unittest 3 | 4 | from cachetools import TTLCache 5 | 6 | from . import CacheTestMixin 7 | 8 | 9 | class Timer: 10 | def __init__(self, auto=False): 11 | self.auto = auto 12 | self.time = 0 13 | 14 | def __call__(self): 15 | if self.auto: 16 | self.time += 1 17 | return self.time 18 | 19 | def tick(self): 20 | self.time += 1 21 | 22 | 23 | class TTLTestCache(TTLCache): 24 | def __init__(self, maxsize, ttl=math.inf, **kwargs): 25 | TTLCache.__init__(self, maxsize, ttl=ttl, timer=Timer(), **kwargs) 26 | 27 | 28 | class TTLCacheTest(unittest.TestCase, CacheTestMixin): 29 | Cache = TTLTestCache 30 | 31 | def test_ttl(self): 32 | cache = TTLCache(maxsize=2, ttl=2, timer=Timer()) 33 | self.assertEqual(0, cache.timer()) 34 | self.assertEqual(2, cache.ttl) 35 | 36 | cache[1] = 1 37 | self.assertEqual(1, cache[1]) 38 | self.assertEqual(1, len(cache)) 39 | self.assertEqual({1}, set(cache)) 40 | 41 | cache.timer.tick() 42 | self.assertEqual(1, cache[1]) 43 | self.assertEqual(1, len(cache)) 44 | self.assertEqual({1}, set(cache)) 45 | 46 | cache[2] = 2 47 | self.assertEqual(1, cache[1]) 48 | self.assertEqual(2, cache[2]) 49 | self.assertEqual(2, len(cache)) 50 | self.assertEqual({1, 2}, set(cache)) 51 | 52 | cache.timer.tick() 53 | self.assertNotIn(1, cache) 54 | self.assertEqual(2, cache[2]) 55 | self.assertEqual(1, len(cache)) 56 | self.assertEqual({2}, set(cache)) 57 | 58 | cache[3] = 3 59 | self.assertNotIn(1, cache) 60 | self.assertEqual(2, cache[2]) 61 | self.assertEqual(3, cache[3]) 62 | self.assertEqual(2, len(cache)) 63 | self.assertEqual({2, 3}, set(cache)) 64 | 65 | cache.timer.tick() 66 | self.assertNotIn(1, cache) 67 | self.assertNotIn(2, cache) 68 | self.assertEqual(3, cache[3]) 69 | self.assertEqual(1, len(cache)) 70 | self.assertEqual({3}, set(cache)) 71 | 72 | cache.timer.tick() 73 | self.assertNotIn(1, cache) 74 | self.assertNotIn(2, cache) 75 | self.assertNotIn(3, cache) 76 | 77 | with self.assertRaises(KeyError): 78 | del cache[1] 79 | with self.assertRaises(KeyError): 80 | cache.pop(2) 81 | with self.assertRaises(KeyError): 82 | del cache[3] 83 | 84 | self.assertEqual(0, len(cache)) 85 | self.assertEqual(set(), set(cache)) 86 | 87 | def test_ttl_lru(self): 88 | cache = TTLCache(maxsize=2, ttl=1, timer=Timer()) 89 | 90 | cache[1] = 1 91 | cache[2] = 2 92 | cache[3] = 3 93 | 94 | self.assertEqual(len(cache), 2) 95 | self.assertNotIn(1, cache) 96 | self.assertEqual(cache[2], 2) 97 | self.assertEqual(cache[3], 3) 98 | 99 | cache[2] 100 | cache[4] = 4 101 | self.assertEqual(len(cache), 2) 102 | self.assertNotIn(1, cache) 103 | self.assertEqual(cache[2], 2) 104 | self.assertNotIn(3, cache) 105 | self.assertEqual(cache[4], 4) 106 | 107 | cache[5] = 5 108 | self.assertEqual(len(cache), 2) 109 | self.assertNotIn(1, cache) 110 | self.assertNotIn(2, cache) 111 | self.assertNotIn(3, cache) 112 | self.assertEqual(cache[4], 4) 113 | self.assertEqual(cache[5], 5) 114 | 115 | def test_ttl_expire(self): 116 | cache = TTLCache(maxsize=3, ttl=3, timer=Timer()) 117 | with cache.timer as time: 118 | self.assertEqual(time, cache.timer()) 119 | self.assertEqual(3, cache.ttl) 120 | 121 | cache[1] = 1 122 | cache.timer.tick() 123 | cache[2] = 2 124 | cache.timer.tick() 125 | cache[3] = 3 126 | self.assertEqual(2, cache.timer()) 127 | 128 | self.assertEqual({1, 2, 3}, set(cache)) 129 | self.assertEqual(3, len(cache)) 130 | self.assertEqual(1, cache[1]) 131 | self.assertEqual(2, cache[2]) 132 | self.assertEqual(3, cache[3]) 133 | 134 | items = cache.expire() 135 | self.assertEqual(set(), set(items)) 136 | self.assertEqual({1, 2, 3}, set(cache)) 137 | self.assertEqual(3, len(cache)) 138 | self.assertEqual(1, cache[1]) 139 | self.assertEqual(2, cache[2]) 140 | self.assertEqual(3, cache[3]) 141 | 142 | items = cache.expire(3) 143 | self.assertEqual({(1, 1)}, set(items)) 144 | self.assertEqual({2, 3}, set(cache)) 145 | self.assertEqual(2, len(cache)) 146 | self.assertNotIn(1, cache) 147 | self.assertEqual(2, cache[2]) 148 | self.assertEqual(3, cache[3]) 149 | 150 | items = cache.expire(4) 151 | self.assertEqual({(2, 2)}, set(items)) 152 | self.assertEqual({3}, set(cache)) 153 | self.assertEqual(1, len(cache)) 154 | self.assertNotIn(1, cache) 155 | self.assertNotIn(2, cache) 156 | self.assertEqual(3, cache[3]) 157 | 158 | items = cache.expire(5) 159 | self.assertEqual({(3, 3)}, set(items)) 160 | self.assertEqual(set(), set(cache)) 161 | self.assertEqual(0, len(cache)) 162 | self.assertNotIn(1, cache) 163 | self.assertNotIn(2, cache) 164 | self.assertNotIn(3, cache) 165 | 166 | def test_ttl_atomic(self): 167 | cache = TTLCache(maxsize=1, ttl=2, timer=Timer(auto=True)) 168 | cache[1] = 1 169 | self.assertEqual(1, cache[1]) 170 | cache[1] = 1 171 | self.assertEqual(1, cache.get(1)) 172 | cache[1] = 1 173 | self.assertEqual(1, cache.pop(1)) 174 | cache[1] = 1 175 | self.assertEqual(1, cache.setdefault(1)) 176 | cache[1] = 1 177 | cache.clear() 178 | self.assertEqual(0, len(cache)) 179 | 180 | def test_ttl_tuple_key(self): 181 | cache = TTLCache(maxsize=1, ttl=1, timer=Timer()) 182 | self.assertEqual(1, cache.ttl) 183 | 184 | cache[(1, 2, 3)] = 42 185 | self.assertEqual(42, cache[(1, 2, 3)]) 186 | cache.timer.tick() 187 | with self.assertRaises(KeyError): 188 | cache[(1, 2, 3)] 189 | self.assertNotIn((1, 2, 3), cache) 190 | 191 | def test_ttl_datetime(self): 192 | from datetime import datetime, timedelta 193 | 194 | cache = TTLCache(maxsize=1, ttl=timedelta(days=1), timer=datetime.now) 195 | 196 | cache[1] = 1 197 | self.assertEqual(1, len(cache)) 198 | items = cache.expire(datetime.now()) 199 | self.assertEqual([], list(items)) 200 | self.assertEqual(1, len(cache)) 201 | items = cache.expire(datetime.now() + timedelta(days=1)) 202 | self.assertEqual([(1, 1)], list(items)) 203 | self.assertEqual(0, len(cache)) 204 | -------------------------------------------------------------------------------- /tox.ini: -------------------------------------------------------------------------------- 1 | [tox] 2 | envlist = check-manifest,docs,doctest,flake8,py 3 | 4 | [testenv] 5 | deps = 6 | pytest 7 | pytest-cov 8 | commands = 9 | py.test --basetemp={envtmpdir} --cov=cachetools --cov-report term-missing {posargs} 10 | 11 | [testenv:check-manifest] 12 | deps = 13 | check-manifest 14 | commands = 15 | check-manifest 16 | skip_install = true 17 | 18 | [testenv:docs] 19 | deps = 20 | sphinx 21 | commands = 22 | sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html 23 | 24 | [testenv:doctest] 25 | deps = 26 | sphinx 27 | commands = 28 | sphinx-build -W -b doctest -d {envtmpdir}/doctrees docs {envtmpdir}/doctest 29 | 30 | [testenv:flake8] 31 | deps = 32 | flake8 33 | flake8-black 34 | flake8-bugbear 35 | flake8-import-order 36 | commands = 37 | flake8 38 | skip_install = true 39 | --------------------------------------------------------------------------------