expiring-dict

library1.1.2pypypi✓ verified 91d ago

expiring-dict is a Python library that provides a dictionary-like object with Time-To-Live (TTL) support for its values, enabling automatic expiration of cached items. It is designed for simple caching scenarios where items need to be removed after a certain period. The library is currently active, with its latest version released in February 2025, and offers both dictionary-level and key-level expiration settings.

database

pip install expiring-dict

github ↗package ↗

INSTALL

IMPORT

SIG · EXPIRING-DICT

expiring-dict

databasepythonv1.1.2

Install

1.6s avg

Import

16ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.2 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.016s · 18.1MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.016s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ExpiringDict

✓ from expiring_dict import ExpiringDict

Demonstrates creating an ExpiringDict with a global TTL and setting individual TTLs for specific keys. Accessing an expired key returns None, and the key is removed.

from expiring_dict import ExpiringDict import time # Dictionary-level TTL: items expire after 1 second cache_dict_level = ExpiringDict(max_age_seconds=1) cache_dict_level["my_key"] = "my_value" print(f"Initial value (dict-level): {cache_dict_level.get('my_key')}") time.sleep(1.5) print(f"Value after 1.5 seconds (dict-level): {cache_dict_level.get('my_key')}") # Should be None # Key-level TTL: individual keys expire after specified seconds cache_key_level = ExpiringDict() cache_key_level["persistent_key"] = "this never expires by default" cache_key_level.ttl("expiring_key", "this expires in 1 second", 1) print(f"\nPersistent value: {cache_key_level.get('persistent_key')}") print(f"Expiring value (initial): {cache_key_level.get('expiring_key')}") time.sleep(1.5) print(f"Persistent value (after 1.5s): {cache_key_level.get('persistent_key')}") print(f"Expiring value (after 1.5s): {cache_key_level.get('expiring_key')}") # Should be None

Debug

Known issues

gotchaIteration (e.g., `for key in cache` or `cache.keys()`) and checking length (`len(cache)`) do not automatically remove expired items. Expiration only occurs when an item is accessed (e.g., `cache['key']` or `cache.get('key')`). This can lead to seemingly 'stale' or inaccurate views of the dictionary content if not handled explicitly.

fix

Always access items with `cache.get(key)` or `cache[key]` to trigger expiration. If an accurate length or full cleanup is needed, consider manually calling `cache.cleanup()` (if available, check documentation for `expiring-dict`) or iterating through items with a `.get()` call on each.

affects: All versions

gotchaExpiringDict objects may not be reliably picklable due to internal threading locks used for thread safety. Attempting to pickle an ExpiringDict can result in a `TypeError` related to unpicklable lock objects, making it difficult to serialize and deserialize the cache.

fix

Avoid pickling ExpiringDict instances directly. If serialization is required, extract the raw data (e.g., `dict(cache.items_with_timestamp())` if applicable) and reconstruct the ExpiringDict after deserialization. Alternatively, consider a different caching solution if direct pickling of the cache object is a critical requirement.

affects: All versions

gotchaSetting `max_age_seconds` for the `ExpiringDict` applies to *all* keys in the dictionary by default. If you intend for some keys to have no expiration or a different expiration, you must explicitly use the `cache.ttl(key, value, age)` method or ensure `max_age_seconds` is `None` during initialization if you only want key-level TTLs.

fix

Initialize `ExpiringDict(max_age_seconds=None)` if you plan to manage expiration solely on a per-key basis. For keys with specific TTLs, use `cache.ttl(key, value, custom_age)`. Keys set via `cache[key] = value` will inherit the dictionary's `max_age_seconds` if set, or have no expiration if `max_age_seconds` is `None`.

affects: All versions

Errors

Common errors & fixes

KeyError: 'some_key'

Attempting to access an expired key using `cache['key']` instead of `cache.get('key')`. When a key expires, it's effectively removed, so direct access will raise a KeyError.

fix

Always use `value = cache.get('key')` to safely retrieve values. This method returns `None` (or a specified default) if the key does not exist or has expired, preventing a `KeyError`.

TypeError: cannot pickle '_thread.lock' object

You are attempting to serialize an `ExpiringDict` instance using a module like `pickle` or `dill`. `ExpiringDict` uses internal threading locks for thread-safety, which are generally not picklable.

fix

Do not attempt to pickle `ExpiringDict` objects directly. If you need to persist the cached data, extract the key-value pairs (and their timestamps if needed) into a standard dictionary or list of tuples, then pickle that data. Reconstruct the `ExpiringDict` from this data upon deserialization.

Upgrade

Version history

1.1.2latest on PyPI · released Feb 28, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

16 hits · last 30 days

node

Resources

githubhttps://github.com/dparker2/py-expiring-dict ↗

packagehttps://pypi.org/project/expiring-dict/ ↗