{"id":3304,"library":"types-toposort","title":"Typing Stubs for toposort","description":"types-toposort provides type hints (typing stubs) for the `toposort` Python library, which implements a topological sort algorithm for directed acyclic graphs (DAGs). This stub package, currently at version 1.10.0.20260408, is part of the `typeshed` project and is released automatically, often daily, reflecting updates to the underlying typeshed definitions for `toposort`.","status":"active","version":"1.10.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","type-hints","topological-sort","dag"],"install":[{"cmd":"pip install toposort types-toposort","lang":"bash","label":"Install both runtime and stubs"}],"dependencies":[{"reason":"Provides the runtime functionality that these stubs type-check. `types-toposort` is solely for type hinting.","package":"toposort","optional":false}],"imports":[{"symbol":"toposort","correct":"from toposort import toposort"},{"symbol":"toposort_flatten","correct":"from toposort import toposort_flatten"}],"quickstart":{"code":"from toposort import toposort, toposort_flatten\n\n# Example graph where keys depend on values\ndependencies = {\n    2: {11},\n    9: {11, 8, 10},\n    10: {11, 3},\n    11: {7, 5},\n    8: {7, 3},\n    3: set(), # 3 has no dependencies\n    5: set(), # 5 has no dependencies\n    7: set()  # 7 has no dependencies\n}\n\n# Perform a topological sort, returning sets of independent nodes at each level\nlayered_sort = toposort(dependencies)\nprint(f\"Layered topological sort: {list(layered_sort)}\")\n\n# Perform a topological sort, returning a single flattened list\nflattened_sort = toposort_flatten(dependencies)\nprint(f\"Flattened topological sort: {list(flattened_sort)}\")","lang":"python","description":"This quickstart demonstrates the basic usage of the `toposort` library for which `types-toposort` provides stubs. It shows how to define dependencies and then perform a layered or flattened topological sort. The input is a dictionary where keys represent dependent nodes, and values are sets of their direct dependencies."},"warnings":[{"fix":"Ensure both `toposort` and `types-toposort` are installed: `pip install toposort types-toposort`.","message":"`types-toposort` is a stub-only package. It provides type annotations but no runtime code. You must install the `toposort` package separately for the actual functionality.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ideally, pin `types-toposort` to the same major.minor version as your `toposort` dependency. Be prepared for potential, albeit rare, type-checking issues even with synced major.minor versions due to typeshed's continuous updates.","message":"The versioning of `types-toposort` (and other typeshed stubs) is tied to typeshed's release cycle, not directly to `toposort`'s patch version. The stub's major.minor version indicates the target `toposort` version, but subsequent numbers (`.YYYYMMDD`) are typeshed internal. This can lead to minor version mismatches or breaking type checks if `toposort` introduces changes within a minor release, or if the stubs are updated more frequently.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your dependency graph is acyclic. Implement cycle detection (e.g., during graph construction) if your input is untrusted or dynamic.","message":"Topological sort algorithms are designed for Directed Acyclic Graphs (DAGs). Providing a graph that contains cycles will result in a `CycleError` at runtime from the `toposort` library, as a valid topological ordering cannot be determined.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review `graphlib.TopologicalSorter` documentation in the Python standard library for an alternative to `toposort`.","message":"For Python 3.9 and newer, the standard library includes `graphlib.TopologicalSorter`, which provides similar functionality. Consider using the standard library implementation if you do not have specific needs met only by the `toposort` package.","severity":"gotcha","affected_versions":"Python <3.9"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}