Python Sorted Collections

2.1.0 · active · verified Wed Apr 15

Sorted Collections provides CPython-optimized mutable sorted collections (SortedList, SortedDict, SortedSet) that maintain their order automatically. As of version 2.1.0, it targets Python 3.7+ and is actively maintained, with releases typically following bug fixes or minor enhancements to ensure stability and performance.

Warnings

breaking Direct access to internal, non-public attributes like `_list` on `SortedList` or `SortedSet` was removed in version 2.0.0. Code that relied on these internal implementations will break.
Fix: Migrate to using the public API methods (e.g., `__getitem__`, `__len__`, `islice`, `irange`, `item_at`) instead of accessing internal attributes.
gotcha Modifying mutable elements *in-place* within a `SortedList` or `SortedSet` can corrupt the collection's sort order if the modification changes the element's comparison value. The collection will not automatically re-sort.
Fix: If an element's sort-defining properties change, remove the element and then re-add it to the collection to ensure it is correctly positioned. For immutable elements, this is not an issue.
gotcha While highly optimized, many operations (e.g., insertion, deletion, lookup by value) on `SortedList`, `SortedSet`, and `SortedDict` have logarithmic time complexity (O(log N)) due to the necessity of maintaining sorted order. This differs from O(1) for some operations in standard, unsorted `list` or `dict`.
Fix: Be mindful of these performance characteristics, especially in performance-critical loops or with very large datasets. Profile your application to ensure sorted collections meet your performance needs.

Install

pip install sortedcollections Install stable version

Imports

SortedList

from sortedcollections import SortedList

SortedDict

from sortedcollections import SortedDict

SortedSet
```
from sortedcollections import SortedSet
```

Quickstart

Demonstrates the creation and basic usage of SortedDict and SortedList, showing how elements are automatically kept in sorted order upon insertion.

from sortedcollections import SortedDict

sd = SortedDict()
sd[5] = 'apple'
sd[1] = 'banana'
sd[3] = 'cherry'

print(f"SortedDict items: {list(sd.items())}")
# Expected output: SortedDict items: [(1, 'banana'), (3, 'cherry'), (5, 'apple')]

# Example with SortedList
from sortedcollections import SortedList

sl = SortedList([5, 1, 3, 2, 4])
sl.add(0)
print(f"SortedList: {list(sl)}")
# Expected output: SortedList: [0, 1, 2, 3, 4, 5]

view raw JSON →