♻️ Auto-generate stub file

[denialhaag]

Description

After we have switched from pybind11 to nanobind in #766, we can now auto-generate the stub file. This PR defines a corresponding nox session and copies over all existing docstrings to the bindings code.

Checklist:

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Expanded simulator APIs with new getter methods across all simulators (e.g., get_number_of_qubits, get_name, statistics, tolerance management).
  • Enhanced PathSimulator configuration with additional properties and json() method support.
  • Introduced simulator mode enumerations for clearer mode selection.

• Documentation

  • Improved type hints and comprehensive docstrings across all Python bindings for better IDE support and API introspection.

• Chores

  • Updated CI pipeline configuration and build tooling for type stub generation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Walkthrough

Adds stub generation and checking: CI enables stub checks, a nox stubs session generates and lints .pyi files, C++ bindings updated for nanobind with richer docstrings and a JSON→dict wrapper, new patterns file added, and Python stubs expanded with fully-qualified types and accessors.

Changes

Cohort / File(s)	Summary
CI configuration \.github/workflows/ci.yml	python-linter job now passes check-stubs: true to the reusable python-linter workflow (keeps enable-ty: true, enable-mypy: false).
Stub generation tooling noxfile.py, pyproject.toml	Adds a stubs nox session that runs nanobind.stubgen, ensures tooling (prek), and runs ruff formatting/checks; updates Ruff per-file ignores to include E501 for *.pyi.
C++ bindings bindings/bindings.cpp	Adds #include <nanobind/stl/pair.h>; converts bindings to nanobind-style enums/classes with pbdoc docstrings; replaces JSON binding with wrapper returning a Python dict; removes module-level m.doc() assignment.
Generated patterns & config bindings/ddsim_patterns.txt, .license-tools-config.json	Adds bindings/ddsim_patterns.txt (empty sections) and includes it in license-tools exclude patterns (trailing-comma formatting adjusted).
Python stubs python/mqt/ddsim/pyddsim.pyi	Expands stubs heavily: switch to fully-qualified mqt.core.* types, add many accessors/utility methods, concrete enums, PathSimulatorConfiguration properties plus json() returning dict, and numerous constructor/return-type fixes.
Changelog CHANGELOG.md	Adds PR reference [#773] to the migration entry.

Sequence Diagram(s)

sequenceDiagram
    participant Dev as Developer (push/PR)
    participant GH as GitHub Actions
    participant Linter as Reusable python-linter
    participant Nox as nox ("stubs" session)
    participant Stubgen as nanobind.stubgen
    participant Ruff as ruff (format/check)

    Dev->>GH: push / open PR
    GH->>Linter: run `python-linter` job (check-stubs: true)
    Linter->>Nox: invoke `nox -s stubs` (repo)
    Nox->>Stubgen: run `nanobind.stubgen` -> generate `.pyi`
    Stubgen-->>Nox: `.pyi` artifacts
    Nox->>Ruff: run ruff-format / ruff-check on generated `.pyi`
    Ruff-->>Linter: pass/fail result
    Linter-->>GH: report job status

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• 📝 update upgrading guide for new stub generation flow workflows#289 — Implements the stub-generation workflow and nox invocation that this change integrates.
• 👷 Add step for checking if Python stub files are up to date workflows#286 — Introduces the check-stubs input and corresponding stub-check step in the reusable python-linter used here.
• ♻️ Replace pybind11 with nanobind #766 — Related C++ binding migration to nanobind touching similar bindings and stubs.

Suggested labels

documentation

Suggested reviewers

• burgholzer

Poem

🐰 I hop through bindings, neat and spry,
I stub the types beneath the sky.
Docstrings bloom; CI hums along,
Stubs in order — sing my song! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Auto-generate stub file' clearly summarizes the main change: enabling automatic generation of Python type stub files after the nanobind migration.
Description check	✅ Passed	The description adequately covers the PR's purpose, references the prior migration (PR #766), and documents the approach. Most checklist items are marked, though some non-critical sections are marked as skipped with appropriate justification.
Docstring Coverage	✅ Passed	Docstring coverage is 84.34% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@noxfile.py`:
- Around line 248-250: The session.run calls pass Path objects in pyi_files
which can cause issues for external commands; before calling session.run in the
block that invokes "prek" ("license-tools", "ruff-check", "ruff-format"), map
pyi_files to strings (e.g., [str(p) for p in pyi_files]) and use that list when
passing --files to session.run so all arguments are plain str values; update the
three session.run calls that reference pyi_files accordingly.

[burgholzer]

This looks great. Just some recommendations on adding a few missing docstrings.

[burgholzer]

Nice. Thanks!