{"id":8662,"library":"sortedcontainers-stubs","title":"Sorted Containers Stubs","description":"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.","status":"active","version":"2.4.3","language":"en","source_language":"en","source_url":"https://github.com/h4l/sortedcontainers-stubs","tags":["typing","stubs","type hints","sortedcontainers","collections","mypy","pyright"],"install":[{"cmd":"pip install sortedcontainers-stubs","lang":"bash","label":"Install `sortedcontainers-stubs`"}],"dependencies":[{"reason":"These stubs provide type hints for the `sortedcontainers` library, which must be installed for runtime functionality. The major and minor versions of the stubs should ideally match the library's major and minor versions.","package":"sortedcontainers"}],"imports":[{"note":"These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.","symbol":"SortedList","correct":"from sortedcontainers import SortedList"},{"note":"These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.","symbol":"SortedDict","correct":"from sortedcontainers import SortedDict"},{"note":"These stubs integrate with the standard `sortedcontainers` imports to provide type checking. You do not import directly from `sortedcontainers-stubs`.","symbol":"SortedSet","correct":"from sortedcontainers import SortedSet"},{"note":"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.","wrong":"from sortedcontainers.sorteddict import SortedKeyDict","symbol":"SortedKeyDict","correct":"from sortedcontainers import SortedDict"},{"note":"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.","wrong":"from sortedcontainers.sortedset import SortedKeySet","symbol":"SortedKeySet","correct":"from sortedcontainers import SortedSet"}],"quickstart":{"code":"from typing import List, Tuple\nfrom sortedcontainers import SortedList, SortedDict, SortedSet\n\n# Example with SortedList\ndef process_sorted_list(data: List[int]) -> SortedList[int]:\n    sl = SortedList(data)\n    sl.add(0)\n    return sl\n\nmy_list: SortedList[int] = process_sorted_list([3, 1, 4, 1, 5])\nprint(f\"SortedList: {my_list}\")\n\n# Example with SortedDict\ndef process_sorted_dict(data: List[Tuple[str, int]]) -> SortedDict[str, int]:\n    sd = SortedDict(data)\n    sd['apple'] = 100\n    return sd\n\nmy_dict: SortedDict[str, int] = process_sorted_dict([('banana', 2), ('orange', 1)])\nprint(f\"SortedDict: {my_dict}\")\n\n# Example with SortedSet\ndef process_sorted_set(data: List[int]) -> SortedSet[int]:\n    ss = SortedSet(data)\n    ss.add(10)\n    return ss\n\nmy_set: SortedSet[int] = process_sorted_set([3, 1, 4, 1, 5])\nprint(f\"SortedSet: {my_set}\")\n\n# To verify type checking, run a type checker like Mypy: `mypy your_script.py`\n# The sortedcontainers-stubs package provides the type information for these objects.","lang":"python","description":"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."},"warnings":[{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"fix":"When reporting type-checking specific problems with `sortedcontainers`, file an issue at `https://github.com/h4l/sortedcontainers-stubs/issues`.","message":"Issues or bugs related to the type stubs themselves should be reported to the `sortedcontainers-stubs` GitHub repository, not the primary `sortedcontainers` repository.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"You are attempting to access `SortedKeyDict` (or `SortedKeySet`) at runtime. These are special stub-only classes used exclusively for type checking.","error":"AttributeError: module 'sortedcontainers.sorteddict' has no attribute 'SortedKeyDict'"},{"fix":"Ensure `sortedcontainers-stubs` is installed in your environment: `pip install sortedcontainers-stubs`. Verify your type checker configuration points to the correct environment.","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.","error":"error: Module 'sortedcontainers' has no attribute 'SortedList' (or 'SortedDict', 'SortedSet')"},{"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)`).","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.","error":"error: Incompatible types in assignment (expression has type \"list[int]\", variable has type \"SortedList[int]\")"}]}