Fix class ordering to preserve inheritance hierarchy (pybind#231)

Classes in generated .pyi stubs were sorted alphabetically, causing
derived classes to appear before their base classes and breaking type
checkers.

Three changes fix this:

- Parser: use module.__dict__.items() instead of inspect.getmembers()
  to preserve the pybind11 registration order (definition order)
- Printer: replace alphabetical sort with a configurable _order_classes()
  dispatch supporting "definition" (default), "topological" (Kahn's
  algorithm ensuring bases precede derived classes), and "alphabetical"
- CLI: add --sort-by option to select the class ordering strategy

The topological sort ignores external bases (from other modules) and
breaks ties by input position for deterministic output. Cyclic cross-
references between classes (e.g. aliases, method signatures) are not
inheritance cycles and are already handled by `from __future__ import
annotations` in the generated stubs.

Closes pybind#231

Based on the approaches in PR pybind#275 by @juelg and PR pybind#294 by
@daltairwalter, informed by review feedback from @skarndev and
@sizmailov.

Co-Authored-By: juelg <[email protected]>
Co-Authored-By: daltairwalter <[email protected]>
Co-Authored-By: skarndev <[email protected]>
Co-Authored-By: sizmailov <[email protected]>
Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: 6 people

pybind11_stubgen/__init__.py

@@ -77,6 +77,7 @@ class CLIArgs(Namespace):
     exit_code: bool
     dry_run: bool
     stub_extension: str
+    sort_by: str
     module_names: list[str]
 
 
@@ -216,6 +217,16 @@ def regex_colon_path(regex_path: str) -> tuple[re.Pattern, str]:
         "Must be 'pyi' (default) or 'py'",
     )
 
+    parser.add_argument(
+        "--sort-by",
+        type=str,
+        default="definition",
+        choices=["definition", "topological"],
+        help="Order of classes in generated stubs. "
+        "'definition' (default) preserves the order from the module. "
+        "'topological' sorts by inheritance hierarchy.",
+    )
+
     parser.add_argument(
         "module_names",
         metavar="MODULE_NAMES",
@@ -310,7 +321,10 @@ def main(argv: Sequence[str] | None = None) -> None:
     args = arg_parser().parse_args(argv, namespace=CLIArgs())
 
     parser = stub_parser_from_args(args)
-    printer = Printer(invalid_expr_as_ellipses=not args.print_invalid_expressions_as_is)
+    printer = Printer(
+        invalid_expr_as_ellipses=not args.print_invalid_expressions_as_is,
+        sort_by=args.sort_by,
+    )
 
     run(
         parser,

pybind11_stubgen/parser/mixins/parse.py

@@ -89,7 +89,7 @@ def handle_module(
         self, path: QualifiedName, module: types.ModuleType
     ) -> Module | None:
         result = Module(name=path[-1])
-        for name, member in inspect.getmembers(module):
+        for name, member in module.__dict__.items():
             obj = self.handle_module_member(
                 QualifiedName([*path, Identifier(name)]), module, member
             )

pybind11_stubgen/printer.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import dataclasses
+import logging
 import sys
 
 from pybind11_stubgen.structs import (
@@ -25,13 +26,79 @@
 )
 
 
+log = logging.getLogger("pybind11_stubgen")
+
+
 def indent_lines(lines: list[str], by=4) -> list[str]:
     return [" " * by + line for line in lines]
 
 
+def _topological_sort_classes(classes: list[Class]) -> list[Class]:
+    """Sort classes so that base classes appear before derived classes.
+
+    Uses Kahn's algorithm. Ties are broken by input position for stability.
+    External bases (not in the current scope) are ignored.
+    """
+    if not classes:
+        return classes
+
+    name_to_index = {c.name: i for i, c in enumerate(classes)}
+    name_to_class = {c.name: c for c in classes}
+
+    # Build adjacency list: base -> [derived, ...]
+    # and in-degree count for each class
+    children: dict[str, list[str]] = {c.name: [] for c in classes}
+    in_degree: dict[str, int] = {c.name: 0 for c in classes}
+
+    for c in classes:
+        for base in c.bases:
+            base_name = str(base[-1])
+            if base_name in name_to_class:
+                children[base_name].append(c.name)
+                in_degree[c.name] += 1
+
+    # Initialize queue with zero in-degree classes, sorted by input position
+    queue = sorted(
+        [name for name, deg in in_degree.items() if deg == 0],
+        key=lambda n: name_to_index[n],
+    )
+
+    result = []
+    while queue:
+        name = queue.pop(0)
+        result.append(name_to_class[name])
+        # Sort children by input position for stable ordering
+        for child in sorted(children[name], key=lambda n: name_to_index[n]):
+            in_degree[child] -= 1
+            if in_degree[child] == 0:
+                queue.append(child)
+        # Re-sort queue to maintain input-position priority
+        queue.sort(key=lambda n: name_to_index[n])
+
+    if len(result) < len(classes):
+        remaining = [c for c in classes if c.name not in {r.name for r in result}]
+        log.warning(
+            "Cycle detected in class inheritance involving: %s. "
+            "Appending in original order.",
+            [c.name for c in remaining],
+        )
+        result.extend(remaining)
+
+    return result
+
+
 class Printer:
-    def __init__(self, invalid_expr_as_ellipses: bool):
+    def __init__(self, invalid_expr_as_ellipses: bool, sort_by: str = "definition"):
         self.invalid_expr_as_ellipses = invalid_expr_as_ellipses
+        self.sort_by = sort_by
+
+    def _order_classes(self, classes: list[Class]) -> list[Class]:
+        if self.sort_by == "alphabetical":
+            return sorted(classes, key=lambda c: c.name)
+        elif self.sort_by == "definition":
+            return classes
+        else:  # "topological"
+            return _topological_sort_classes(classes)
 
     def print_alias(self, alias: Alias) -> list[str]:
         return [f"{alias.name} = {alias.origin}"]
@@ -90,7 +157,7 @@ def print_class_body(self, class_: Class) -> list[str]:
         if class_.doc is not None:
             result.extend(self.print_docstring(class_.doc))
 
-        for sub_class in sorted(class_.classes, key=lambda c: c.name):
+        for sub_class in self._order_classes(class_.classes):
             result.extend(self.print_class(sub_class))
 
         modifier_order: dict[Modifier, int] = {
@@ -232,7 +299,7 @@ def print_module(self, module: Module) -> list[str]:
         for type_var in sorted(module.type_vars, key=lambda t: t.name):
             result.extend(self.print_type_var(type_var))
 
-        for class_ in sorted(module.classes, key=lambda c: c.name):
+        for class_ in self._order_classes(module.classes):
             result.extend(self.print_class(class_))
 
         for func in sorted(module.functions, key=lambda f: f.name):