Registry / database / circular-dict

circular-dict

JSON →
library1.9pypypi✓ verified 28d ago

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-dict
INSTALL
IMPORT
SIG · CIRCULAR-DICT
C
circular-dict
databasepythonv1.9
Install
1.5s 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.9 · 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.5s · import 0.012s · 18MB
16MB installed
● package 16MB
Code
Verified usage

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

CircularDict
✓ from circular_dict import CircularDict

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.

import os from circular_dict import CircularDict # Initialize a CircularDict with a maximum length of 3 items my_dict_maxlen = CircularDict(maxlen=3) my_dict_maxlen['key1'] = 'value1' my_dict_maxlen['key2'] = 'value2' my_dict_maxlen['key3'] = 'value3' print(f"Initial maxlen dict: {list(my_dict_maxlen.keys())}") my_dict_maxlen['key4'] = 'value4' # 'key1' is automatically removed print(f"After adding key4 (key1 removed): {list(my_dict_maxlen.keys())}") # Initialize a CircularDict with a maximum memory usage of 4MB # Note: actual memory usage depends on content; this is an example. # For demonstration, we'll use a smaller, illustrative byte size. # Real-world usage requires careful calculation of object sizes. # Using a small maxsize_bytes for demonstration of its behavior. my_dict_maxsize = CircularDict(maxsize_bytes=100) # 100 bytes approx my_dict_maxsize['a'] = '1234567890' # ~10 bytes for value + key overhead my_dict_maxsize['b'] = 'abcdefghij' # ~10 bytes for value + key overhead # Adding more items will cause older ones to be removed to stay under 100 bytes. # This is illustrative; actual byte size calculations are complex. print(f"\nInitial maxsize dict: {list(my_dict_maxsize.keys())}") my_dict_maxsize['c'] = 'klmnopqrst' * 5 # A larger string print(f"After adding larger key 'c': {list(my_dict_maxsize.keys())}") # Depending on exact memory model, 'a' and 'b' might be removed.
Debug
Known issues
gotchaIf you attempt to add a single item (key-value pair) whose memory footprint alone exceeds the `maxsize_bytes` limit, a `MemoryError` will be raised. This means `maxsize_bytes` applies to individual items as well as the total.
fix
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.
affects: All versions
gotchaWhile CircularDict inherits from Python's OrderedDict and maintains insertion order, its core functionality involves automatically removing the 'oldest' items when size or memory limits are hit. This modification can lead to a `RuntimeError` if you iterate over the dictionary while it is being modified by this automatic removal process.
fix
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.
affects: All versions
gotchaThe `maxsize_bytes` parameter accounts for the total memory footprint, including both keys and values, and the internal overhead of the dictionary structure itself. Predicting exact memory usage can be challenging due to Python's object model and varying overheads, which might lead to unexpected removals if not carefully estimated.
fix
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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'circular_dict'
The 'circular-dict' package is not installed in the Python environment, or the import statement uses an incorrect module name.
fix
Install the package using pip: `pip install circular-dict`, and ensure the import statement is `from circular_dict import CircularDict`.
MemoryError
An attempt was made to add an item to a CircularDict whose memory footprint alone, or the total memory usage of the dictionary with the new item, exceeds the configured 'maxsize_bytes' limit.
fix
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.
RuntimeError: dictionary changed size during iteration
This error occurs when you are iterating over a CircularDict while simultaneously modifying it, such as by adding new items that trigger the automatic removal of older entries due to size or memory limits.
fix
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.
AttributeError: 'CircularDict' object has no attribute 'some_key'
You are attempting to access a key in the CircularDict using dot notation (e.g., `my_dict.some_key`) instead of the standard Python dictionary square bracket notation.
fix
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.
Upgrade
Version history
1.9latest on PyPI · released May 12, 2024
Audit
Dependencies
pythonrequiredRequired Python version
Agent activity
23 hits · last 30 days
node
18
OpenAI (training)
1
Resources
circular-dict — pip install circular-dict · libregistry