cachetools 7.1.2__tar.gz → 7.1.3__tar.gz

cachetools-7.1.3/.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: [tkem]
+custom: ["https://www.paypal.me/tkem"]

cachetools-7.1.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: tkem
+
+---
+
+Before reporting a bug, please make sure you have the latest `cachetools` version installed:
+```
+pip install --upgrade cachetools
+```
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Expected result**
+A clear and concise description of what you expected to happen.
+
+**Actual result**
+A clear and concise description of what happened instead.
+
+**Reproduction steps**
+
+```python
+import cachetools
+
+```

cachetools-7.1.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

cachetools-7.1.3/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,10 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: tkem
+
+---
+
+Sorry, but `cachetools` is not accepting feature requests at this time.

cachetools-7.1.3/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,28 @@
+# Description
+
+A clear and concise description of your changes.
+
+## Motivation and Context
+
+Why is this change required?  What problem does it solve?
+
+## Related Issue
+
+Except for trivial changes like correcting typos, this project only
+accepts pull requests related to open issues.  If suggesting a new
+feature or change, please discuss it in an issue first.  If fixing a
+bug, there should be an issue describing the bug, with steps to
+reproduce.
+
+Please link to the issue here: https://github.com/tkem/cachetools/issues/###
+
+## Has this been tested and documented?
+
+This project uses [tox](https://tox.wiki) for test automization.
+Before submitting a pull request, run `tox` in the project's root and
+make sure all tests are passing.
+
+When adding new features or code not already covered by existing unit
+tests, please also add some tests covering your changes under the
+`tests` directory.  For new features, please consider adding to the
+existing documentation under the `docs` directory.

cachetools-7.1.3/.github/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Supported Versions
+
+Security updates are applied only to the latest release.
+
+## Reporting a Vulnerability
+
+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.
+
+Please disclose it at [security advisory](https://github.com/tkem/cachetools/security/advisories/new).
+
+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.

cachetools-7.1.3/.github/copilot-instructions.md

@@ -0,0 +1,83 @@
+# Copilot Instructions for cachetools
+
+## Architecture Overview
+**cachetools** provides extensible memoizing collections and decorators, including variants of Python's `@lru_cache`. Pure Python 3.10+, no external runtime dependencies.
+
+### Core Design Pattern
+- All caches inherit from `Cache` (a `MutableMapping` with `maxsize`, `currsize`, and `getsizeof`)
+- Subclasses override `__setitem__`, `__getitem__`, `__delitem__`, and `popitem()` to implement eviction policies
+- **Critical:** Subclasses use default parameter trick (e.g., `cache_setitem=Cache.__setitem__`) to call parent methods efficiently while avoiding recursion
+
+### Cache Types
+- `FIFOCache`: Evicts oldest inserted (`OrderedDict`)
+- `LRUCache`: Evicts least recently used (`OrderedDict.move_to_end()`)
+- `LFUCache`: Evicts least frequently used (doubly-linked list of frequency buckets)
+- `RRCache`: Random eviction (`__keys` list with `__index` dict for O(1) removal)
+- `TTLCache`/`TLRUCache`: Time-based eviction via `_TimedCache` base; `_Timer` context manager freezes time during operations to prevent TOCTOU bugs; `expire()` returns `list[tuple[key, value]]`
+
+### Decorators
+- `@cached` (`_cached.py`): Function memoization; separate wrappers for each lock/condition/info combination; supports `cache=None` via `_uncached`/`_uncached_info` wrappers (pass-through without caching)
+- `@cachedmethod` (`_cachedmethod.py`): Method memoization via descriptor protocol (`__set_name__`/`__get__`); class hierarchy: `_WrapperBase` (per-instance callable) → `_DescriptorBase` (descriptor with `__set_name__`/`__get__`, replaces self in instance `__dict__` via `setdefault` for thread safety) → `_DeprecatedDescriptorBase` (backward-compatible `@classmethod` support with warnings); the backward-compatible `_condition` variant uses `weakref.WeakKeyDictionary` for per-instance pending sets
+- Both support `key`, `lock`, `condition`, and `info` parameters; when `condition` is given without `lock`, `condition` serves as both lock and condition
+- `info=True` adds `cache_info()`/`cache_clear()`; `info=False` (default) only provides `cache_clear()`
+- `func.py`: `functools.lru_cache`-compatible wrappers; all use `threading.Condition()` by default for thread safety + stampede prevention; `_UnboundTTLCache` extends `TTLCache` with `math.inf` maxsize for `maxsize=None`
+
+### Thread Safety
+3-tier locking: **Unlocked** | **Locked** (release during compute) | **Condition** (lock + pending set + `wait_for`/`notify_all` to prevent thundering herd)
+
+`_AbstractCondition` protocol in `__init__.pyi`: extends `AbstractContextManager[Any]` + `Protocol` with `wait()`, `wait_for()`, `notify()`, `notify_all()`. Only `wait_for()` and `notify_all()` are used at runtime.
+
+### Key Generation (`keys.py`)
+- `hashkey`: Default key function; `_HashedTuple` caches hash values
+- `methodkey`: Drops `self` from key; `typedkey`/`typedmethodkey`: Adds `type()` info
+
+## Developer Workflows
+
+### Testing
+```bash
+pytest                                    # Run all tests
+pytest --cov=cachetools --cov-report term-missing  # With coverage
+tox -e py                                 # Just tests
+tox -e ruff                               # Linting (ruff check)
+tox -e ruff-format                        # Format check (ruff format --diff)
+tox -e pyright                            # Type checking
+tox -e docs                               # Build docs
+tox -e doctest                            # Run doctests
+```
+
+- `tests/__init__.py`: `CacheTestMixin` (16 standard tests), `_TestCaseProtocol`, `CountedLock`, `CountedCondition` (implements full `_AbstractCondition` protocol)
+- Each cache test inherits `unittest.TestCase` + `CacheTestMixin`
+- `test_cached.py` / `test_cachedmethod.py` use `DecoratorTestMixin` / `MethodDecoratorTestMixin` for all lock/condition/info combos
+- Threading stampede tests gated by `THREADING_TESTS` env var (enabled in `tox.ini` via `setenv`)
+
+### Code Style
+- **ruff** formatter and linter (`tox -e ruff-format`, `tox -e ruff`)
+
+## Conventions
+
+### Adding New Cache Types
+1. Inherit from `Cache` or `_TimedCache`
+2. Override `__setitem__`, `__delitem__`, `popitem()` (optionally `__getitem__`)
+3. Use default parameters to call parent: `def __setitem__(self, key, value, cache_setitem=Cache.__setitem__)`
+4. Handle `__missing__` edge case: check `if key in self` after parent call
+5. Add test class inheriting `CacheTestMixin`
+
+### Type Stubs
+Inline stubs ship with the package (`py.typed` marker):
+- `@overload` distinguishes `info=True` vs `info=False`; `Literal[False]` overload listed last
+- `_TimedCache` uses `Generic[_KT, _VT, _TT]` with `_TT` defaulting to `float`
+- `_AbstractCondition` is `@type_check_only` `Protocol` for `condition` params and `cache_condition` attributes
+- `_cached_wrapper` / `_cachedmethod_wrapper` use `ParamSpec(_P)` to preserve decorated function signatures; `__call__` uses `_P.args`/`_P.kwargs`
+- `_cachedmethod_wrapper` models the descriptor protocol: `__set_name__`, `__get__`, `__call__`; uses `Concatenate[Any, _P]` so `_P` excludes `self`
+- `_cachedmethod.py` uses `# type: ignore` for `functools.update_wrapper()` (typeshed #9846)
+- Validate stubs with `tox -e pyright`
+
+## Key Files
+- `src/cachetools/__init__.py` — All cache implementations
+- `src/cachetools/__init__.pyi` — Type stubs for caches and decorators
+- `src/cachetools/_cached.py` — `@cached` decorator variants
+- `src/cachetools/_cachedmethod.py` — `@cachedmethod` descriptor variants
+- `src/cachetools/keys.py` / `keys.pyi` — Key functions
+- `src/cachetools/func.py` / `func.pyi` — Functools-compatible wrappers (`lru_cache`, `ttl_cache`, etc.)
+- `tests/__init__.py` — Test mixin and helpers
+- `pyproject.toml` — Build config, version: `{attr = "cachetools.__version__"}`

cachetools-7.1.3/.github/copilot-review.md

@@ -0,0 +1,54 @@
+# Code Review — cachetools 7.1.3
+
+**Date:** 2026-05-18
+**CI status:** All green (tox: py, ruff, ruff-format, pyright, docs, doctest)
+
+## Type Stubs (`__init__.pyi`, `keys.pyi`, `func.pyi`)
+
+No issues. `cached` and `cachedmethod` stubs use `ParamSpec(_P)` to
+preserve decorated function signatures (`__call__` uses `_P.args`/`_P.kwargs`).
+`cachedmethod` stubs use `Concatenate[Any, _P]` to strip `self` from
+`ParamSpec`, and `_cachedmethod_wrapper` models the descriptor protocol
+(`__set_name__`, `__get__`, `__call__`). Overload ordering is correct
+(`Literal[True]` before `Literal[False]` default).
+
+`func.pyi` deliberately uses `Callable[..., _R]` instead of `ParamSpec`
+for `_cachetools_cache_wrapper` since the `func.*_cache` decorators
+rewrite signatures (adding `cache_info`, `cache_clear`, `cache_parameters`).
+
+## Code — Potential Issues
+
+| # | Severity | Location | Finding |
+|---|----------|----------|---------|
+| 1 | Low | `Cache.__init__` | `maxsize` is not validated. Negative values cause confusing `popitem` errors at insertion time rather than a clear early `ValueError`. Docs note `maxsize` must be positive, but code does not enforce it. |
+| 2 | Low | `Cache.__setitem__`/`__delitem__` | Size accounting assumes value size is stable after insert. In-place mutation of cached values can desync `currsize`. By design (documented), but a known footgun. |
+| 3 | Low | `_cachedmethod.py` condition variants | Stampede prevention uses per-instance pending sets. Two instances sharing one cache+condition won't coordinate pending keys across instances. |
+| 4 | Info | `_cachedmethod.py` / `_cached.py` condition variants | Same-thread recursive re-entry on the same key will deadlock (`wait_for` on own pending marker). |
+
+No implementation bugs found.
+
+## Tests — Gaps
+
+| # | Priority | Finding |
+|---|----------|---------|
+| 1 | Medium | Threading tests join workers without timeout (`test_threading.py`), so a deadlock regression hangs CI instead of failing. |
+| 2 | Medium | Lock-only race resolution (`cache.setdefault` in locked wrappers) is not stress-tested under real concurrency — only condition-based wrappers have threading tests. |
+| 3 | Low | `@cached` condition wrappers lack an error-path test (pending cleanup on exception). Equivalent coverage exists for `@cachedmethod` (`test_decorator_cond_error`) but not for `@cached`. |
+| 4 | Low | `CacheTestMixin` assertions are intentionally weak on eviction-order correctness (checks key existence, not specific eviction victim), relying on per-cache test files for policy validation. |
+| 5 | Low | `test_cached.py`: zero-size + condition + `info=True` combination is not tested (zero-size only tested for no-lock and lock variants). |
+| 6 | Low | `test_lfu.py`: no tie-breaking test for equal-frequency eviction (current code picks an arbitrary element via `next(iter(curr.keys))`). |
+| 7 | Low | `test_classmethod.py`: limited coverage — only deprecation warnings + basic functionality. No `info=True`, error-path, or shared-cache tests. |
+
+## Docs
+
+| # | Priority | Finding |
+|---|----------|---------|
+| 1 | Low | `condition` docs say it must provide `wait()`, `wait_for()`, `notify()` and `notify_all()`, but only `wait_for()` and `notify_all()` are used at runtime. The `_AbstractCondition` protocol in stubs includes all four for compatibility with `threading.Condition`. |
+| 2 | Info | PEP URLs in examples use legacy `http://www.python.org/dev/peps/` (moved to `peps.python.org`), but these are mocked in doctests so functionally irrelevant. |
+
+## Keys & Func Modules
+
+No issues found. `func.py` correctly uses `threading.Condition()` for
+all decorators, providing stampede prevention by default. `_UnboundTTLCache`
+cleanly extends `TTLCache` with `math.inf` maxsize for the
+`maxsize=None` case.

cachetools-7.1.3/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "monthly"

cachetools-7.1.3/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: read
+
+jobs:
+  main:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.13t", "3.14", "3.14t", "pypy3.10", "pypy3.11"]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python }}
+          allow-prereleases: true
+      - run: pip install coverage tox
+      - run: tox
+      - uses: codecov/codecov-action@57e3a136b779b570ffcdbf80b3bdc90e7fab3de2 # v6.0.0
+        with:
+          name: ${{ matrix.python }}
+          token: ${{ secrets.CODECOV_TOKEN }}

cachetools-7.1.3/.gitignore

@@ -0,0 +1,12 @@
+*.egg-info
+*.pyc
+*.swp
+.cache/
+.coverage
+.pytest_cache/
+.tox/
+MANIFEST
+build/
+dist/
+docs/_build/
+

cachetools-7.1.3/.readthedocs.yaml

@@ -0,0 +1,11 @@
+# Configure ReadTheDocs.
+
+version: 2
+
+build:
+  os: "ubuntu-22.04"
+  tools:
+    python: "3.11"
+
+sphinx:
+  configuration: "docs/conf.py"

{cachetools-7.1.2 → cachetools-7.1.3}/CHANGELOG.rst

@@ -1,3 +1,11 @@
+v7.1.3 (2026-05-18)
+===================
+
+- Minor type stub improvements.
+
+- Update build environment.
+
+
 v7.1.2 (2026-05-16)
 ===================
 

{cachetools-7.1.2/src/cachetools.egg-info → cachetools-7.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.1.2
+Version: 7.1.3
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.1.2 → cachetools-7.1.3}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools >= 61.0.0", "wheel"]
+requires = ["setuptools >= 78", "setuptools-scm >= 8.2"]
 build-backend = "setuptools.build_meta"
 
 [project]

{cachetools-7.1.2 → cachetools-7.1.3}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.1.2"
+__version__ = "7.1.3"
 
 import collections
 import collections.abc
@@ -23,9 +23,6 @@ import time
 
 from . import keys
 
-# Typing stubs for this package are provided by typeshed:
-# https://github.com/python/typeshed/tree/main/stubs/cachetools
-
 
 class _DefaultSize:
     """A minimal "fake" dict that returns a constant size 1 for any key."""

{cachetools-7.1.2 → cachetools-7.1.3}/src/cachetools/func.pyi

@@ -1,19 +1,20 @@
 from collections.abc import Callable, Sequence
-from typing import Any, Final, Generic, TypeVar, overload, type_check_only
+from typing import Any, Final, Generic, ParamSpec, TypeVar, overload, type_check_only
 
 from . import _CacheInfo
 
 __all__: Final = ("fifo_cache", "lfu_cache", "lru_cache", "rr_cache", "ttl_cache")
 
+_P = ParamSpec("_P")
 _T = TypeVar("_T")
 _R = TypeVar("_R")
 
 @type_check_only
-class _cachetools_cache_wrapper(Generic[_R]):
-    __wrapped__: Callable[..., _R]
+class _cachetools_cache_wrapper(Generic[_P, _R]):
+    __wrapped__: Callable[_P, _R]
     __name__: str
     __doc__: str | None
-    def __call__(self, /, *args: Any, **kwargs: Any) -> _R: ...
+    def __call__(self, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
     def cache_info(self) -> _CacheInfo: ...
     def cache_clear(self) -> None: ...
     def cache_parameters(self) -> dict[str, Any]: ...
@@ -21,50 +22,50 @@ class _cachetools_cache_wrapper(Generic[_R]):
 @overload
 def fifo_cache(
     maxsize: int | None = 128, typed: bool = False
-) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+) -> Callable[[Callable[_P, _R]], _cachetools_cache_wrapper[_P, _R]]: ...
 @overload
 def fifo_cache(
-    maxsize: Callable[..., _R], typed: bool = False
-) -> _cachetools_cache_wrapper[_R]: ...
+    maxsize: Callable[_P, _R], typed: bool = False
+) -> _cachetools_cache_wrapper[_P, _R]: ...
 @overload
 def lfu_cache(
     maxsize: int | None = 128, typed: bool = False
-) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+) -> Callable[[Callable[_P, _R]], _cachetools_cache_wrapper[_P, _R]]: ...
 @overload
 def lfu_cache(
-    maxsize: Callable[..., _R], typed: bool = False
-) -> _cachetools_cache_wrapper[_R]: ...
+    maxsize: Callable[_P, _R], typed: bool = False
+) -> _cachetools_cache_wrapper[_P, _R]: ...
 @overload
 def lru_cache(
     maxsize: int | None = 128, typed: bool = False
-) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+) -> Callable[[Callable[_P, _R]], _cachetools_cache_wrapper[_P, _R]]: ...
 @overload
 def lru_cache(
-    maxsize: Callable[..., _R], typed: bool = False
-) -> _cachetools_cache_wrapper[_R]: ...
+    maxsize: Callable[_P, _R], typed: bool = False
+) -> _cachetools_cache_wrapper[_P, _R]: ...
 @overload
 def rr_cache(
     maxsize: int | None = 128,
     choice: Callable[[Sequence[_T]], _T] = ...,
     typed: bool = False,
-) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+) -> Callable[[Callable[_P, _R]], _cachetools_cache_wrapper[_P, _R]]: ...
 @overload
 def rr_cache(
-    maxsize: Callable[..., _R],
+    maxsize: Callable[_P, _R],
     choice: Callable[[Sequence[_T]], _T] = ...,
     typed: bool = False,
-) -> _cachetools_cache_wrapper[_R]: ...
+) -> _cachetools_cache_wrapper[_P, _R]: ...
 @overload
 def ttl_cache(
     maxsize: int | None = 128,
     ttl: Any = 600,
     timer: Callable[[], _T] = ...,
     typed: bool = False,
-) -> Callable[[Callable[..., _R]], _cachetools_cache_wrapper[_R]]: ...
+) -> Callable[[Callable[_P, _R]], _cachetools_cache_wrapper[_P, _R]]: ...
 @overload
 def ttl_cache(
-    maxsize: Callable[..., _R],
+    maxsize: Callable[_P, _R],
     ttl: Any = 600,
     timer: Callable[[], _T] = ...,
     typed: bool = False,
-) -> _cachetools_cache_wrapper[_R]: ...
+) -> _cachetools_cache_wrapper[_P, _R]: ...

{cachetools-7.1.2 → cachetools-7.1.3/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.1.2
+Version: 7.1.3
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.1.2 → cachetools-7.1.3}/src/cachetools.egg-info/SOURCES.txt

@@ -1,8 +1,20 @@
+.gitignore
+.readthedocs.yaml
 CHANGELOG.rst
 LICENSE
 README.rst
 pyproject.toml
 tox.ini
+.github/FUNDING.yml
+.github/PULL_REQUEST_TEMPLATE.md
+.github/SECURITY.md
+.github/copilot-instructions.md
+.github/copilot-review.md
+.github/dependabot.yml
+.github/ISSUE_TEMPLATE/bug_report.md
+.github/ISSUE_TEMPLATE/config.yml
+.github/ISSUE_TEMPLATE/feature_request.md
+.github/workflows/ci.yml
 docs/conf.py
 docs/index.rst
 src/cachetools/__init__.py

{cachetools-7.1.2 → cachetools-7.1.3}/tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = docs,doctest,format,lint,py,pyright
+envlist = py,docs,doctest,ruff,ruff-format,pyright
 
 [testenv]
 deps =
@@ -22,18 +22,18 @@ deps =
 commands =
      sphinx-build -W -b doctest -d {envtmpdir}/doctrees docs {envtmpdir}/doctest
 
-[testenv:format]
+[testenv:ruff]
 deps =
     ruff
 commands =
-    ruff format --diff -q {posargs}
+    ruff check {posargs}
 skip_install = true
 
-[testenv:lint]
+[testenv:ruff-format]
 deps =
     ruff
 commands =
-    ruff check {posargs}
+    ruff format --diff -q {posargs}
 skip_install = true
 
 [testenv:pyright]