Sorted Containers Stubs

2.4.3 · active · verified Thu Apr 16

Community-maintained Python type stubs for the `sortedcontainers` library, which provides `dict`, `set`, and `list` data structures that automatically maintain the order of their elements by value. These stubs enable type checkers (like Mypy or Pyright) to enforce API details, including specific requirements for keys/values and special constructor return types, making `sortedcontainers` easier to use in type-checked codebases. The major and minor versions of `sortedcontainers-stubs` are designed to align with the corresponding major and minor versions of `sortedcontainers` itself. Current version is 2.4.3.

Common errors

```
AttributeError: module 'sortedcontainers.sorteddict' has no attribute 'SortedKeyDict'
```
cause You are attempting to access `SortedKeyDict` (or `SortedKeySet`) at runtime. These are special stub-only classes used exclusively for type checking.

fix Remove the explicit reference to `SortedKeyDict` or `SortedKeySet`. When using `SortedDict` or `SortedSet` with a `key` argument, the type checker will correctly infer the specialized type; you should instantiate `SortedDict` or `SortedSet` directly.
```
error: Module 'sortedcontainers' has no attribute 'SortedList' (or 'SortedDict', 'SortedSet')
```
cause Your type checker (e.g., Mypy, Pyright) cannot find the type definitions for the `sortedcontainers` library. This usually means `sortedcontainers-stubs` is not installed or not discoverable.

fix Ensure `sortedcontainers-stubs` is installed in your environment: `pip install sortedcontainers-stubs`. Verify your type checker configuration points to the correct environment.
```
error: Incompatible types in assignment (expression has type "list[int]", variable has type "SortedList[int]")
```
cause You are assigning a standard Python collection (e.g., `list`, `dict`, `set`) to a variable explicitly type-hinted with a `sortedcontainers` type, or vice-versa. The stubs enforce the distinct types.

fix Ensure type consistency. If a variable is type-hinted as `SortedList[int]`, assign a `SortedList[int]` instance to it. Convert between types explicitly if necessary (e.g., `my_sorted_list = SortedList(my_regular_list)`).

Warnings

gotcha The `SortedKeyDict` and `SortedKeySet` classes are *stub-only* and do not exist at runtime. They are used by type checkers to represent the return types of `SortedDict` and `SortedSet` constructors when a `key` argument is provided. Attempting to import or instantiate them will result in a runtime error (e.g., `AttributeError`).
Fix: Do not explicitly import or instantiate `SortedKeyDict` or `SortedKeySet`. Use `SortedDict` or `SortedSet` directly, and let the type checker infer the specific type based on constructor arguments.
breaking The major and minor version numbers of `sortedcontainers-stubs` are designed to correspond to those of the `sortedcontainers` library. Using mismatched major/minor versions (e.g., `sortedcontainers-stubs==2.x.y` with `sortedcontainers==3.x.y`) may lead to incorrect type checking results or errors due to API differences.
Fix: Ensure that the major and minor versions of `sortedcontainers-stubs` match the major and minor versions of your installed `sortedcontainers` package. For example, if you use `sortedcontainers==2.4.x`, install the latest `sortedcontainers-stubs==2.4.x`.
gotcha Issues or bugs related to the type stubs themselves should be reported to the `sortedcontainers-stubs` GitHub repository, not the primary `sortedcontainers` repository.
Fix: When reporting type-checking specific problems with `sortedcontainers`, file an issue at `https://github.com/h4l/sortedcontainers-stubs/issues`.

Install

pip install sortedcontainers-stubs Install `sortedcontainers-stubs`

Imports

SortedList
```
from sortedcontainers import SortedList
```
These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.
SortedDict
```
from sortedcontainers import SortedDict
```
These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.
SortedSet
```
from sortedcontainers import SortedSet
```
These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.
SortedKeyDict
wrong:
```
from sortedcontainers.sorteddict import SortedKeyDict
```
correct:
```
from sortedcontainers import SortedDict
```
The `SortedKeyDict` and `SortedKeySet` types are stub-only subclasses used to describe specialized return types for `SortedDict` and `SortedSet` constructors when a key function is provided. They do not exist at runtime and should not be imported or instantiated directly.
SortedKeySet
wrong:
```
from sortedcontainers.sortedset import SortedKeySet
```
correct:
```
from sortedcontainers import SortedSet
```
The `SortedKeyDict` and `SortedKeySet` types are stub-only subclasses used to describe specialized return types for `SortedDict` and `SortedSet` constructors when a key function is provided. They do not exist at runtime and should not be imported or instantiated directly.

Quickstart

Install `sortedcontainers-stubs` and then use `sortedcontainers` as usual with type hints. Type checkers will automatically discover the stubs. This example demonstrates basic usage of `SortedList`, `SortedDict`, and `SortedSet` with explicit type annotations.

from typing import List, Tuple
from sortedcontainers import SortedList, SortedDict, SortedSet

# Example with SortedList
def process_sorted_list(data: List[int]) -> SortedList[int]:
    sl = SortedList(data)
    sl.add(0)
    return sl

my_list: SortedList[int] = process_sorted_list([3, 1, 4, 1, 5])
print(f"SortedList: {my_list}")

# Example with SortedDict
def process_sorted_dict(data: List[Tuple[str, int]]) -> SortedDict[str, int]:
    sd = SortedDict(data)
    sd['apple'] = 100
    return sd

my_dict: SortedDict[str, int] = process_sorted_dict([('banana', 2), ('orange', 1)])
print(f"SortedDict: {my_dict}")

# Example with SortedSet
def process_sorted_set(data: List[int]) -> SortedSet[int]:
    ss = SortedSet(data)
    ss.add(10)
    return ss

my_set: SortedSet[int] = process_sorted_set([3, 1, 4, 1, 5])
print(f"SortedSet: {my_set}")

# To verify type checking, run a type checker like Mypy: `mypy your_script.py`
# The sortedcontainers-stubs package provides the type information for these objects.

view raw JSON →