Typing Stubs for toposort

1.10.0.20260408 · active · verified Sat Apr 11

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`.

Warnings

gotcha `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.
Fix: Ensure both `toposort` and `types-toposort` are installed: `pip install toposort types-toposort`.
gotcha 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.
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.
gotcha 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.
Fix: Ensure your dependency graph is acyclic. Implement cycle detection (e.g., during graph construction) if your input is untrusted or dynamic.
gotcha 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.
Fix: Review `graphlib.TopologicalSorter` documentation in the Python standard library for an alternative to `toposort`.

Install

pip install toposort types-toposort Install both runtime and stubs

Imports

toposort
```
from toposort import toposort
```
toposort_flatten
```
from toposort import toposort_flatten
```

Quickstart

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.

from toposort import toposort, toposort_flatten

# Example graph where keys depend on values
dependencies = {
    2: {11},
    9: {11, 8, 10},
    10: {11, 3},
    11: {7, 5},
    8: {7, 3},
    3: set(), # 3 has no dependencies
    5: set(), # 5 has no dependencies
    7: set()  # 7 has no dependencies
}

# Perform a topological sort, returning sets of independent nodes at each level
layered_sort = toposort(dependencies)
print(f"Layered topological sort: {list(layered_sort)}")

# Perform a topological sort, returning a single flattened list
flattened_sort = toposort_flatten(dependencies)
print(f"Flattened topological sort: {list(flattened_sort)}")

view raw JSON →