{"library":"toposort","title":"toposort","description":"The `toposort` library provides a pure Python implementation of a topological sort algorithm, useful for ordering items based on their dependencies. As of its latest version `1.10`, released on February 25, 2023, it is a stable, production-ready tool. It accepts dependency graphs as dictionaries and efficiently computes a valid processing order. The release cadence appears to be moderate, with updates for compatibility and minor enhancements.","status":"active","version":"1.10","language":"en","source_language":"en","source_url":"https://github.com/ericvsmith/toposort","tags":["topological sort","graph","dependencies","dag","ordering"],"install":[{"cmd":"pip install toposort","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary function for performing a topological sort, returning an iterator of sets for parallel processing stages.","symbol":"toposort","correct":"from toposort import toposort"},{"note":"A convenience function that returns a single flattened list of topologically sorted items.","symbol":"toposort_flatten","correct":"from toposort import toposort_flatten"},{"note":"The exception raised when a cyclic dependency is detected in the input graph.","symbol":"CircularDependencyError","correct":"from toposort import CircularDependencyError"}],"quickstart":{"code":"from toposort import toposort, toposort_flatten\n\ndata = {\n    2: {11},\n    9: {11, 8, 10},\n    10: {11, 3},\n    11: {7, 5},\n    8: {7, 3},\n    # Nodes 3, 5, 7 have no dependencies, so they can be omitted\n    # or explicitly listed with empty sets if they have no outgoing edges\n    3: set(),\n    5: set(),\n    7: set()\n}\n\n# Get items in stages (sets of items that can be processed in parallel)\n# Example output: [{3, 5, 7}, {8, 11}, {2, 10}, {9}]\nfor step in toposort(data):\n    print(f\"Process in parallel: {step}\")\n\n# Get a flattened list of items in a valid order\n# Example output: [3, 5, 7, 8, 11, 2, 10, 9] (order within sets may vary)\nflattened_order = list(toposort_flatten(data))\nprint(f\"Flattened order: {flattened_order}\")\n\n# Example of circular dependency handling\ncyclic_data = {1: {2}, 2: {1}}\ntry:\n    list(toposort(cyclic_data))\nexcept toposort.CircularDependencyError as e:\n    print(f\"Caught expected error: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `toposort` with a sample dependency graph. The `data` dictionary maps each dependent node to a set of its direct dependencies. `toposort` yields sets of nodes that can be processed concurrently, while `toposort_flatten` provides a single linear sequence. It also shows how to catch `CircularDependencyError` for graphs containing cycles."},"warnings":[{"fix":"Ensure your dependency graph is a Directed Acyclic Graph (DAG). If cycles are expected or possible, implement logic to detect and handle `CircularDependencyError`.","message":"Circular dependencies will raise a `toposort.CircularDependencyError` (derived from `ValueError`). The algorithm cannot produce a valid topological sort if a cycle exists in the graph.","severity":"breaking","affected_versions":"All versions"},{"fix":"Always provide dependencies as `set`s (`{dependency1, dependency2}`) and ensure the mapping is `dependent_node: {its_dependencies}`.","message":"The input `data` dictionary expects keys to be dependent nodes and values to be `set`s of nodes that the key depends on. Using lists instead of sets for dependencies, or incorrectly defining the dependency direction (e.g., mapping a node to what it *is depended on by*), are common mistakes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Represent your graph nodes using hashable Python types. If you need to use complex objects, consider using a unique identifier (like an ID string or number) as the node in the topological sort, and map it back to your complex object.","message":"All nodes (keys and elements within the dependency sets) must be hashable types (e.g., numbers, strings, tuples). Unhashable types like lists or dictionaries cannot be used as nodes.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Evaluate `graphlib.TopologicalSorter` from the Python standard library as an alternative, especially for new projects or to reduce third-party dependencies. The API differs, so code migration would be required.","message":"For Python 3.9 and newer, the standard library includes `graphlib.TopologicalSorter` which offers similar topological sorting functionality. Users might consider this built-in alternative to avoid external dependencies.","severity":"gotcha","affected_versions":"Python 3.9+"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}