{"id":5737,"library":"types-cachetools","title":"Typing stubs for cachetools","description":"types-cachetools provides static type annotations for the cachetools library, enabling type checkers like MyPy and Pyright to validate code that utilizes caching mechanisms. The current version, 6.2.0.20260317, aims to provide accurate annotations for cachetools versions 6.2.*. It is part of the typeshed project, which collects high-quality type stubs for various Python packages.","status":"active","version":"6.2.0.20260317","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","cache","performance","type-checking"],"install":[{"cmd":"pip install types-cachetools","lang":"bash","label":"Install types-cachetools"}],"dependencies":[{"reason":"Provides the runtime functionality for which these stubs are generated. This stub package is intended for cachetools==6.2.*.","package":"cachetools","optional":false},{"reason":"Required runtime version for the stub package itself.","package":"python","optional":false}],"imports":[{"symbol":"LRUCache","correct":"from cachetools import LRUCache"},{"symbol":"TTLCache","correct":"from cachetools import TTLCache"},{"symbol":"cached","correct":"from cachetools import cached"},{"symbol":"cachedmethod","correct":"from cachetools import cachedmethod"},{"note":"While older versions of cachetools might have exposed func decorators directly from the top-level package, the recommended and type-safe way to import them is from the cachetools.func submodule.","wrong":"from cachetools import ttl_cache","symbol":"ttl_cache","correct":"from cachetools.func import ttl_cache"}],"quickstart":{"code":"from cachetools import cached, LRUCache, TTLCache\nimport time\n\n# Example 1: LRUCache decorator\n@cached(cache=LRUCache(maxsize=2))\ndef expensive_function(arg):\n    print(f\"Calculating expensive_function({arg})\")\n    time.sleep(0.1) # Simulate work\n    return arg * 2\n\nprint(\"--- LRUCache Example ---\")\nprint(expensive_function(1)) # Calculates\nprint(expensive_function(2)) # Calculates\nprint(expensive_function(1)) # Cache hit\nprint(expensive_function(3)) # Calculates, evicts 2\nprint(expensive_function(2)) # Calculates again\n\n# Example 2: TTLCache decorator\n@cached(cache=TTLCache(maxsize=1, ttl=0.5))\ndef time_sensitive_data(key):\n    print(f\"Fetching time_sensitive_data({key})\")\n    return f\"Data for {key} @ {time.time():.2f}\"\n\nprint(\"\\n--- TTLCache Example ---\")\nprint(time_sensitive_data(\"report\")) # Calculates\nprint(time_sensitive_data(\"report\")) # Cache hit\ntime.sleep(0.6) # Wait for cache to expire\nprint(time_sensitive_data(\"report\")) # Calculates again\n","lang":"python","description":"This quickstart demonstrates basic usage of `cachetools` decorators like `@cached` with `LRUCache` and `TTLCache`. With `types-cachetools` installed, type checkers will provide static analysis for these caching patterns, helping to ensure correct usage of cache parameters and function signatures."},"warnings":[{"fix":"Update import statements: change `from cachetools.submodule import Symbol` to `from cachetools import Symbol`.","message":"Breaking change in `cachetools` v5.0.0: Deprecated submodules like `cachetools.ttl` were removed. Imports must now be directly from the top-level `cachetools` package (e.g., `from cachetools import TTLCache`).","severity":"breaking","affected_versions":"cachetools >= 5.0.0"},{"fix":"Adjust custom `key` functions for `@cachedmethod` to accept `self` (e.g., `def my_key_func(self, *args, **kwargs): ...`). The default key function correctly ignores `self`.","message":"Breaking change in `cachetools` v5.0.0: The `key` function passed to the `@cachedmethod` decorator now receives `self` as its first positional argument. Custom `key` functions must be updated to accept this argument.","severity":"breaking","affected_versions":"cachetools >= 5.0.0"},{"fix":"Consider using `time.monotonic` for `timer` and `float` for `ttl` for simpler typing. If using `datetime.now`, ensure your type checker configuration is robust or use `typing.cast` / `# type: ignore` as a last resort until stubs are updated to fully support `datetime` types for `TTLCache`'s timer/ttl arguments.","message":"Type checking `TTLCache` with `datetime.now` as `timer` and `datetime.timedelta` for `ttl` might lead to MyPy errors because `types-cachetools` (historically) often expected `float` for `ttl` if the `timer` returns a `float` (like `time.monotonic`). While `cachetools` supports `datetime.datetime` for `timer`, the stubs might not perfectly align without explicit casting or type ignores.","severity":"gotcha","affected_versions":"types-cachetools <= 6.2.x, cachetools >= 5.x"},{"fix":"Migrate away from `MRUCache` to an alternative caching strategy like `LRUCache` or `FIFOCache`.","message":"Breaking change in `cachetools` v6.0.0: The `MRUCache` class and its corresponding `@func.mru_cache` decorator were removed.","severity":"breaking","affected_versions":"cachetools >= 6.0.0"},{"fix":"Remove the `info` positional parameter from `@cached` decorator calls and retrieve cache statistics via `cache.info()`.","message":"Breaking change in `cachetools` v7.0.0: Dropped support for passing `info` as a fourth positional parameter to the `@cached` decorator. The `info` argument should now be accessed as `cache.info()` directly.","severity":"breaking","affected_versions":"cachetools >= 7.0.0"},{"fix":"Review and refactor code that relies on `cache(self)` returning `None` in `@cachedmethod` to disable caching. Implement explicit logic to manage cache entries instead.","message":"Breaking change in `cachetools` v7.0.0: Dropped support for `cache(self)` returning `None` with `@cachedmethod` to suppress caching. Cache suppression should be handled through other means or by modifying the cache itself.","severity":"breaking","affected_versions":"cachetools >= 7.0.0"},{"fix":"Be aware of potential type mismatches. If encountering type errors, temporarily pin `cachetools` to `~=6.2.0` or wait for `types-cachetools` to release stubs compatible with `cachetools` 7.x. Alternatively, use `# type: ignore` sparingly for known incompatibilities.","message":"The `types-cachetools` version 6.2.0.20260317 explicitly states it targets `cachetools==6.2.*`. However, the current `cachetools` release is 7.0.5. Using `types-cachetools` 6.2.x with `cachetools` 7.x may lead to type checking inconsistencies, missing annotations for new `cachetools` 7.x features, or incorrect types for changed APIs.","severity":"gotcha","affected_versions":"types-cachetools 6.2.x, cachetools 7.x"}],"env_vars":null,"last_verified":"2026-03-29T00:00:00.000Z","next_check":"2026-09-29T00:00:00.000Z"}