circular-dict
CircularDict is a high-performance Python data structure that blends the functionality of dictionaries and circular buffers. Inheriting the usage of traditional dictionaries, it allows you to define constraints on size and memory usage. This way, the CircularDict will be always up-to-date with the last N added elements, ensuring that neither the maximum length nor the memory usage limit is exceeded. It is ideal for caching large data structures while maintaining control over memory footprint.
Decision gist · record as of 2026-08-14
Yes, if you need a simple, zero-dependency bounded cache. The package is stable (Production/Stable classifier, no known vulnerabilities), installs cleanly, and solves a real problem. The dormant maintenance status is not a concern for a narrow, well-defined utility—there is little reason to change it. Use it when you want automatic FIFO eviction with either item-count or memory-size limits; avoid it if you need LRU semantics (evict least recently used, not oldest) or active development support.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.6 or later; no other system dependencies.
- No runtime dependencies and a pure-Python wheel distribution make installation straightforward.
- The package is dormant (last commit 2024-05-13, 824 days since first release), so expect no active maintenance, though the codebase appears stable.
License · maintenance · safety
MIT (permissive) — MIT license is permissive, allowing use in commercial and private projects with minimal restrictions—only requiring attribution and inclusion of the license text.
last release 2024-05-12 (824 days) · last repo commit 2024-05-13 · 9 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 2,073,794 downloads/mo, #3,320 on PyPI
Alternatives
Verify before relying
pip install circular-dict
from circular_dict import CircularDict
# Create a dict limited to 3 items
my_dict = CircularDict(maxlen=3)
my_dict['a'] = 1
my_dict['b'] = 2
my_dict['c'] = 3
my_dict['d'] = 4 # Oldest entry ('a') is removed automatically- Performance characteristics (insertion/deletion speed) compared to standard dict or other circular buffer implementations.
- Behavior and accuracy of memory size calculation when storing complex nested objects or numpy arrays.
- Thread safety guarantees, if any, for concurrent access patterns.
What it is and what it does
CircularDict wraps Python's OrderedDict to create a self-managing cache that enforces size limits. You can constrain it by maximum item count (maxlen), total memory footprint in bytes (maxsize_bytes), or both. When a new entry would exceed the limit, the oldest items are automatically removed to make room, keeping memory usage predictable.
It behaves like a standard Python dictionary in all other respects—you use it with normal dict syntax (subscript access, iteration, keys/values/items methods). The main use case is building bounded caches where you want the most recent items or a fixed memory budget without manually evicting old entries. If you try to add a single item larger than maxsize_bytes, it raises MemoryError rather than silently failing.
Use it for
- Build a time-series cache that keeps only recent measurements without manual cleanup.
- Implement a bounded cache for expensive computations with a fixed memory budget.
- Store recent log entries or events in memory while preventing unbounded growth.
- Cache numpy arrays or large objects with a strict byte-size limit to avoid memory leaks.
- Maintain a fixed-size buffer of recent API responses or database query results.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes, if you need a simple, zero-dependency bounded cache.
The package is stable (Production/Stable classifier, no known vulnerabilities), installs cleanly, and solves a real problem. The dormant maintenance status is not a concern for a narrow, well-defined utility—there is little reason to change it. Use it when you want automatic FIFO eviction with either item-count or memory-size limits; avoid it if you need LRU semantics (evict least recently used, not oldest) or active development support.
Install
circular-dict on PyPI
Before you install
No runtime dependencies and a pure-Python wheel distribution make installation straightforward. The package is dormant (last commit 2024-05-13, 824 days since first release), so expect no active maintenance, though the codebase appears stable.
Requires Python 3.6 or later; no other system dependencies.
License in practice
MIT license is permissive, allowing use in commercial and private projects with minimal restrictions—only requiring attribution and inclusion of the license text.
Quickstart
pip install circular-dict
from circular_dict import CircularDict
# Create a dict limited to 3 items
my_dict = CircularDict(maxlen=3)
my_dict['a'] = 1
my_dict['b'] = 2
my_dict['c'] = 3
my_dict['d'] = 4 # Oldest entry ('a') is removed automaticallyVerify before relying
- Performance characteristics (insertion/deletion speed) compared to standard dict or other circular buffer implementations.
- Behavior and accuracy of memory size calculation when storing complex nested objects or numpy arrays.
- Thread safety guarantees, if any, for concurrent access patterns.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.6 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | None |
| Maintenance | Dormant 824 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 2,073,794 / month, #3,320 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.6Programming Language :: Python :: 3.7Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Topic :: Software Development :: DebuggersTopic :: Software Development :: LibrariesTopic :: Software Development :: Libraries :: Python ModulesTopic :: Software Development :: TestingTopic :: System :: HardwareTopic :: Utilities |
Evidence: circular_dict-1.9-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “circular buffer dictionary”
- circular-dictCircularDict is a Python dictionary that automatically removes oldest…
- toposortImplements topological sorting of directed acyclic graphs, ordering…
- fcachefcache provides a dictionary-like file-based cache that persists data…
Give your agent the search over MCP, or paste the wish link into any chat.
More Libraries packages
urllib3 is an HTTP client library that provides thread-safe connection pooling, SSL/TLS verification, multipart file uploads, request retries, compression support, and proxy handling for Python applications.
Requests is a Python HTTP library that simplifies sending HTTP/1.1 requests with automatic handling of headers, authentication, cookies, and response parsing.
Pluggy provides a plugin system that lets you define hook specifications and register implementations to be called in sequence, enabling extensible Python applications without tight coupling.
Install it if you're building an extensible application or framework.
Provides parsing, arithmetic, and recurrence rule computation for dates and times, with timezone support and iCalendar RFC compliance.
Install it if you need to parse flexible date strings, compute relative dates, handle timezones, or work with recurrence rules—it's the de facto choice for these tasks.
Six provides utility functions to write Python code that runs on both Python 2.7 and Python 3.3+, smoothing over language differences between the two versions.
pytest is a testing framework that lets you write test functions using plain assert statements and automatically discovers and runs them, with detailed failure reporting.
See also expiringdict · lru-dict · persist-queue · atomic_dict · hurry.filesize · binpacking · lilcom · rison · cyclic · fcache