expiringdict

1.2.2 · maintenance · verified Thu Apr 09

expiringdict is a Python library that provides a dictionary-like object whose values automatically expire after a specified time-to-live (TTL). It's commonly used for caching purposes where stale data needs to be automatically removed. The current version is 1.2.2. The project appears to be stable with infrequent updates, indicating a maintenance phase rather than active feature development.

Warnings

gotcha expiringdict is explicitly not thread-safe. Concurrent access from multiple threads without external locking will lead to unpredictable behavior and potential data corruption.
Fix: Ensure external locking mechanisms (e.g., threading.Lock) are used when accessing ExpiringDict from multiple threads, or use it in single-threaded contexts only.
gotcha Setting `max_age_seconds` to 0 does not mean items expire immediately; it means items will *never* expire based on age. Only `max_len` will trigger eviction.
Fix: To have items expire based on time, set `max_age_seconds` to a positive integer. If immediate removal is desired, manually delete the key or set a very small positive `max_age_seconds`.
gotcha Iterating over an ExpiringDict while items are expiring (or being added/removed) can lead to a `RuntimeError` ('dictionary changed size during iteration') or inconsistent results, as the underlying dictionary is being modified.
Fix: If iteration is required, convert the dictionary items to a list first (e.g., `list(exp_dict.items())`) or acquire a lock around the iteration if in a multithreaded context and ensure no other threads modify the dictionary.

Install

pip install expiringdict Install stable version

Imports

ExpiringDict
```
from expiringdict import ExpiringDict
```

Quickstart

Initialize an ExpiringDict with a maximum length and item age, then demonstrate adding an item, retrieving it, and verifying its expiration after the TTL.

from expiringdict import ExpiringDict
import time

# Create an expiring dictionary with max 100 items, and items expire after 2 seconds
cache = ExpiringDict(max_len=100, max_age_seconds=2)

print("Adding 'data' to cache...")
cache['my_key'] = 'data_value'
print(f"Retrieved immediately: {cache.get('my_key', 'Not found')}")

print("Waiting 3 seconds for expiration...")
time.sleep(3)

print(f"Retrieved after expiration: {cache.get('my_key', 'Not found')}")
# Direct access would raise KeyError: print(cache['my_key'])

view raw JSON →