CircularDict is a high-performance Python data structure (version 1.9) that combines the functionality of dictionaries and circular buffers. It allows defining constraints on size (number of items) and memory usage, automatically removing the oldest entries when limits are exceeded. This makes it ideal for caching large data structures while maintaining control over the memory footprint. The library appears to be actively maintained, with regular updates.
pip install circular-dictVerified import paths — ran on the pinned version, not inferred.
Demonstrates initializing CircularDict with `maxlen` to limit item count and `maxsize_bytes` to limit memory. Shows how older items are automatically removed when limits are exceeded. Note that `maxsize_bytes` behavior is sensitive to the actual memory footprint of keys and values.
Ensure that the `maxsize_bytes` parameter is large enough to accommodate the largest single item you intend to store. Consider using `sys.getsizeof()` to estimate object sizes, though actual dictionary overhead adds complexity.
Avoid iterating over a `CircularDict` simultaneously with operations that might trigger item removal (e.g., adding new items when at capacity). If iteration is necessary, consider iterating over a copy of the keys (`list(my_dict.keys())`) or values.
Perform careful testing with representative data to determine appropriate `maxsize_bytes` values. Consider adding a buffer to your calculated `maxsize_bytes` to account for potential overheads or variations in object sizing.
Install the package using pip: `pip install circular-dict`, and ensure the import statement is `from circular_dict import CircularDict`.
Increase the 'maxsize_bytes' parameter when initializing CircularDict or ensure that individual items being added do not exceed the set limit. Consider using `sys.getsizeof()` to estimate object sizes and add a buffer.
Avoid modifying the CircularDict (e.g., adding new items) during iteration. If iteration is necessary, iterate over a copy of its keys (`list(my_dict.keys())`) or values to prevent concurrent modification.
Access dictionary elements using square bracket notation: `my_dict['some_key']`. While CircularDict is a dict-like object, it does not support dot notation for key access.