sortedcontainers
Sorted collection types for Python — provides SortedList, SortedDict, and SortedSet that maintain sorted order with O(log n) add/discard and O(1) min/max. sortedcontainers features: SortedList with bisect_left/bisect_right, add() O(log n), pop() O(log n), SortedDict with peekitem(), irange() for range queries, islice() for sorted slices, SortedSet with irange(), set operations preserving sort order, key= parameter for custom sort keys, and pure Python implementation beating C extensions. Used in Redis-py, SciPy, and other major projects.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Pure data structure library with no network calls and zero external dependencies. No security concerns. Sorting comparisons are done in Python — avoid using user-controlled objects as keys if custom __lt__ has side effects.
⚡ Reliability
Best When
Maintaining sorted collections with frequent insertions and range queries — sortedcontainers provides O(log n) operations without the complexity of balanced BST implementation, faster than alternatives including C extensions.
Avoid When
You don't need sorted order (use list/dict/set), need thread safety without locks, or have 100M+ elements (use database indexes).
Use Cases
- • Agent priority queue — from sortedcontainers import SortedList; queue = SortedList(key=lambda x: x.priority); queue.add(task); next_task = queue.pop(0) — O(log n) insert and O(1) min access; agent task scheduler maintains priority-ordered queue; SortedList beats heapq for random access and iteration needs
- • Agent time-ordered event log — from sortedcontainers import SortedList; events = SortedList(key=lambda e: e.timestamp); events.add(new_event); recent = events.irange_key(start_ts, end_ts) — irange_key for efficient range queries; agent event stream stores events sorted by time; range query without scanning all events
- • Agent sorted dict — from sortedcontainers import SortedDict; scores = SortedDict(); scores['agent_a'] = 0.95; scores['agent_b'] = 0.87; top_agent = scores.peekitem(-1) — SortedDict maintains key-sorted order; agent leaderboard with efficient min/max access; peekitem(0) for minimum, peekitem(-1) for maximum
- • Agent range queries — sorted_data = SortedList(timestamps); idx_start = sorted_data.bisect_left(start_time); idx_end = sorted_data.bisect_right(end_time); window = sorted_data[idx_start:idx_end] — bisect for binary search; agent time-window queries on sorted data; O(log n) search + O(k) slice for k results
- • Agent unique sorted collection — from sortedcontainers import SortedSet; seen = SortedSet(); seen.add(url); unseen = [u for u in candidate_urls if u not in seen] — SortedSet: O(log n) add and O(log n) membership; agent web crawler deduplication with sorted iteration; use irange() for alphabetical range of processed URLs
Not For
- • Standard dict/list replacements — sortedcontainers adds overhead over unsorted collections; only use when sorted order is needed
- • Concurrent modifications — sortedcontainers is not thread-safe; for concurrent sorted collections use threading.Lock() or database indexes
- • Massive datasets — sortedcontainers is pure Python; for 100M+ elements use database indexes or numpy sorted arrays
Interface
Authentication
No auth — pure Python data structure library.
Pricing
sortedcontainers is Apache 2.0 licensed. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ SortedList allows duplicates, SortedSet does not — sl = SortedList([1,1,2]); len(sl) == 3; ss = SortedSet([1,1,2]); len(ss) == 2; agent code using SortedList expecting unique elements gets duplicates; use SortedSet for unique constraint; SortedList with duplicates: sl.count(1) returns 2
- ⚠ key= function applied to stored values not indices — SortedList(key=lambda x: x.priority) sorts by .priority attribute; add() receives full object; bisect_key_left(5.0) searches by key value (priority=5.0); agent code using bisect_left() with element must use bisect_key_left() with key value when key function is set
- ⚠ Not thread-safe for concurrent modifications — multiple threads calling sl.add() concurrently corrupts internal structure; agent concurrent task scheduler must use threading.Lock(): with lock: queue.add(task); next = queue.pop(0); no built-in locking; concurrent reads are safe, concurrent writes are not
- ⚠ irange(minimum, maximum) is inclusive on both ends — SortedList.irange(start, end) includes both start and end values; agent code wanting exclusive range must use: sl.irange(start, end, inclusive=(True, False)); irange is different from Python slice which is exclusive on upper bound
- ⚠ Mutation during iteration raises RuntimeError — for item in sorted_list: sorted_list.add(new_item) raises RuntimeError: deque mutated during iteration; agent code adding items based on iteration must collect new items and add after: new_items = []; for item in sl: new_items.extend(generate(item)); sl.update(new_items)
- ⚠ SortedDict iteration order is key order not insertion — for k, v in sorted_dict.items() iterates in sorted key order; agent code expecting insertion order must use regular dict (Python 3.7+); SortedDict.keys() returns SortedKeysView in sorted order; combining with list comprehension: sorted order guaranteed
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for sortedcontainers.
Scores are editorial opinions as of 2026-03-06.