expiringdict

library1.2.2pypypi✓ verified 26d ago

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.

database

pip install expiringdict

package ↗homepage ↗

INSTALL

IMPORT

SIG · EXPIRINGDICT

expiringdict

databasepythonv1.2.2

Install

1.6s avg

Import

13ms

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.2.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.95 runs

installs and imports cleanly · install 0.0s · import 0.014s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.012s · 18MB

16MB installed

● package 16MB

Code

Verified usage

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

ExpiringDict

✓ from expiringdict import ExpiringDict

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'])

Debug

Known issues

gotchaexpiringdict 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.

affects: All versions

gotchaSetting `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`.

affects: All versions

gotchaIterating 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'expiringdict'

The Python interpreter cannot find the 'expiringdict' package, likely because it has not been installed or is installed in a different Python environment than the one being used.

fix

Ensure the library is installed in your active Python environment by running: `pip install expiringdict`

KeyError: 'foo' (when accessing an expired item from expiringdict)

When a key's value expires in ExpiringDict, accessing that key directly will raise a KeyError because the entry is removed from the dictionary upon access or when its `max_age_seconds` has passed, or if `max_len` is exceeded. Iterating over keys() or items() does not automatically remove expired values; expiration and removal happen on access or dictionary modification.

fix

Before accessing a key, check for its presence using `key in expiring_dict` or use the `.get()` method with a default value to avoid the error. Example: `value = cache.get('foo')` or `if 'foo' in cache: value = cache['foo']`

TypeError: __init__() missing 2 required positional arguments: 'max_len' and 'max_age_seconds' (during pickling/unpickling expiringdict)

ExpiringDict objects, due to their custom `__init__` signature, do not pickle/unpickle correctly by default using standard `pickle` or `dill` because the constructor expects `max_len` and `max_age_seconds` arguments which are not automatically supplied during deserialization.

fix

To make an ExpiringDict picklable, convert it to a standard `OrderedDict` or `dict` before pickling, and then reconstruct the `ExpiringDict` upon unpickling. Example: `import dill; from expiringdict import ExpiringDict; cache = ExpiringDict(max_len=10, max_age_seconds=60); cache['test'] = 1; picklable_cache = dict(cache); pickled_object = dill.dumps(picklable_cache); original_dict = dill.loads(pickled_object); new_cache = ExpiringDict(max_len=10, max_age_seconds=60, items=original_dict)`

Upgrade

Version history

1.2.2latest on PyPI · released Jun 21, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

5 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/expiringdict/ ↗

homepagehttps://www.mailgun.com/ ↗