{"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":"python","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,"search_vec":"'2.4.3':91 'align':77 'api':43 'automat':23 'check':63 'checker':36 'codebas':64 'collect':97 'communiti':5 'community-maintain':4 'constructor':52 'contain':2 'correspond':80 'current':88 'data':20 'design':75 'detail':44 'dict':16 'easier':57 'element':29 'enabl':34 'enforc':42 'hint':95 'includ':45 'keys/values':49 'librari':13 'like':37 'list':19 'maintain':6,24 'major':66,81 'make':55 'minor':68,83 'mypi':38,98 'order':26 'provid':15 'pyright':40,99 'python':7 'requir':47 'return':53 'set':17 'sort':1 'sortedcontain':12,56,72,86,96 'sortedcontainers-stub':71 'special':51 'specif':46 'structur':21 'stub':3,9,33,73,93 'type':8,35,54,62,92,94 'type-check':61 'use':59 'valu':31 'version':69,84,89","created_at":"2026-04-16T17:03:20.745616+00:00","updated_at":"2026-04-16T17:03:20.745616+00:00","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]\")"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.4.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/h4l/sortedcontainers-stubs","docs":null,"changelog":"https://github.com/h4l/sortedcontainers-stubs/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/sortedcontainers-stubs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}