ruff.toml

# Define rules, plugins, and configurations for the ruff linter.
# For more details on rules see: https://docs.astral.sh/ruff/rules

target-version = "py310"
line-length = 120
# preview = true

[lint.pycodestyle]
max-doc-length = 120

[lint.pydocstyle]
convention = "google"

[lint.isort]
split-on-trailing-comma = true

[lint.flake8-tidy-imports]
ban-relative-imports = "all"

[lint.flake8-type-checking]
strict = true

[lint]
select = [
    "A",        # flake8-builtins
    "ANN",      # flake8-annotations
    "ARG",      # flake8-unused-arguments
    "ASYNC",    # flake8-async
    "B",        # flake8-bugbear
    "BLE",      # flake8-blind-except
    "C4",       # flake8-comprehensions
    "COM",      # flake8-commas
    # "CPY",      # flake8-copyright
    "D",        # flake8-docstrings
    "DTZ",      # flake8-datetimez
    "E",        # pycodestyle
    "EM",       # flake8-errmsg
    "EXE",      # flake8-executable
    "F",        # Pyflakes
    "FA",       # flake8-future-annotations
    "FBT",      # flake8-boolean-trap
    "FLY",      # flynt
    "G",        # flake8-logging-format
    "I",        # isort (imports)
    "ICN",      # flake8-import-conventions
    "INP",      # flake8-no-pep420 (namespace/no __init__.py)
    "LOG",      # flake8-logging
    "INT",      # flake8-gettext
    "ISC",      # flake9-implicit-str-concat
    "N",        # pep8-naming
    "PERF",     # Perflint
    "PIE",      # flake8-pie
    "PL",       # Pylint
    "PT",       # flake8-pytest-style
    "PTH",      # flake8-use-pathlib
    "PYI",      # flake8-pyi
    "Q",        # flake8-quotes (prefer double quotes over single)
    "RET",      # flake8-return
    "RSE",      # flake8-raise
    "RUF",      # Ruff-specific rules
    "S",        # flake8-bandit
    "SIM",      # flake8-simplify
    "SLF",      # flake8-self
    "SLOT",     # flake8-slots
    "T10",      # flake8-debugger
    "TCH",      # flake8-type-checking
    "TD",       # flake8-todos
    "TID",      # flake8-tidy-imports
    "TRY",      # tryceratops
    "UP",       # pyupgrade (upgrade syntax from old to new)
    "W",        # pycodestyle
    "YTT",      # flake8-2020

    # TODO: uncomment to erase commented code
    # "ERA",      # eradicate
    # TODO: uncomment to alert about TODOs to fix
    # "FIX",      # flak8-fixme
    # TODO: uncomment to highlight print statements
    # "T20",      # flake8-print (any print statement)
]

ignore = [
    "A005", # Module `types` shadows a Python standard-library module

    # pylint refactor rules - too strict for scientific/research code
    "PLR",

    "S403", # `pickle`, `cPickle`, `dill`, and `shelve` modules are possibly insecure
    "S404", # `subprocess` module is possibly insecure

    # flake8-boolean-trap
    "FBT001", # Boolean-typed positional argument in function definition

    # flake8-todos
    "TD002", # Missing author in TODO
    "TD003", # Missing issue link on the line following this TODO

    # tryceratops
    "TRY002", # Custom exceptions
]

[lint.per-file-ignores]
"**/__init__.py" = ["F401"]  # imported but unused - Expected for __init__.py re-exports

# Main pecos __init__.py - special case for module initialization
"python/quantum-pecos/src/pecos/__init__.py" = [
    "A004",     # Import shadows builtin - intentional numpy-like API (abs, all, any, max, min, sum, round)
    "E402",     # Module level import not at top - intentional for module setup
    "SLF001",   # Private member access - accessing _to_program() on program wrappers
    "ANN",      # Missing annotations - legacy code with duck typing for program wrappers
    "PLC0415",  # Import inside function - optional guppylang check
]
# Deprecated API wrappers - preserve old names and forward *args/**kwargs
"python/quantum-pecos/src/pecos/_deprecated.py" = [
    "N802",     # Function name BinArray preserves old API name
    "ANN401",   # Any for *args/**kwargs - deprecated wrapper forwards all arguments
]
# Engine builders - access _to_program() on program wrappers
"python/quantum-pecos/src/pecos/_engine_builders.py" = [
    "SLF001",   # Private member access - accessing _to_program() on program wrappers
]
# Sim entry point - lazy import of optional guppylang
"python/quantum-pecos/src/pecos/_sim.py" = [
    "PLC0415",  # Import inside function - optional guppylang check
    "SLF001",   # Private member access - accessing _to_program() on program wrappers
]
# HUGR to DAG converter - lazy hugr imports, hugr private API access
"python/quantum-pecos/src/pecos/circuit_converters/hugr_to_dag.py" = [
    "PLC0415",  # Import inside function - hugr not always available
    "SLF001",   # Private member access - hugr._extension is the only way to get extension name
]
# QuantumCircuit - internal API access for tick/gate management
"python/quantum-pecos/src/pecos/circuits/quantum_circuit.py" = [
    "SLF001",   # Private member access - accessing internal _inner, _iter_tick, _add_gate_to_tick
    "PERF203",  # try-except in loop - needed for idempotent prep/measure (no API to query tick state)
]
# Graph module - __all__ grouped by type (undirected, directed, DAG)
"python/quantum-pecos/src/pecos/graph.py" = [
    "RUF022",   # __all__ not sorted - intentionally grouped by graph type
]
# Guppy code generation - lazy imports for optional deps, __all__ grouped by code type
"python/quantum-pecos/src/pecos/guppy/__init__.py" = [
    "RUF022",   # __all__ not sorted - grouped by code type (surface, color, transversal)
]
"python/quantum-pecos/src/pecos/guppy/color.py" = [
    "PLC0415",  # Import inside function - lazy loading of qec.color
]
"python/quantum-pecos/src/pecos/guppy/surface.py" = [
    "PLC0415",  # Import inside function - lazy loading of qec.surface
]
"python/quantum-pecos/src/pecos/guppy/transversal.py" = [
    "PLC0415",  # Import inside function - lazy loading of qec modules
]
# QEC modules - __all__ grouped by category, lazy imports
"python/quantum-pecos/src/pecos/qec/__init__.py" = [
    "RUF022",   # __all__ not sorted - grouped by category (submodules, DEM, protocols)
]
"python/quantum-pecos/src/pecos/qec/surface/__init__.py" = [
    "RUF022",   # __all__ not sorted - grouped by category
]
"python/quantum-pecos/src/pecos/qec/surface/layouts/__init__.py" = [
    "RUF022",   # __all__ not sorted - grouped by lattice type
]
"python/quantum-pecos/src/pecos/qec/surface/decode.py" = [
    "PLC0415",  # Import inside function - lazy loading of optional dependencies
    "N803",     # H parameter name - standard parity check matrix notation
    "N806",     # H variable name - standard parity check matrix notation
    "SLF001",   # Private member access - accessing internal decoder APIs
    "ANN401",   # Any types - required for optional dependency types (pymatching, stim)
]
"python/quantum-pecos/src/pecos/qec/surface/plot.py" = [
    "PLC0415",  # Import inside function - lazy loading of qec.surface
]
"python/quantum-pecos/src/pecos/qec/surface/circuit_gen.py" = [
    "PLC0415",  # Import inside function - lazy loading of stim, pecos_rslib
    "SLF001",   # Private member access - accessing patch internal data structures
]
"python/quantum-pecos/src/pecos/qec/surface/circuit_builder.py" = [
    "PLC0415",  # Import inside function - lazy loading of guppy, stim, json
    "SLF001",   # Private member access - accessing patch and circuit internals
]
# QEC analysis modules
"python/quantum-pecos/src/pecos/qec/analysis/dem_builder.py" = [
    "SLF001",   # Private member access - accessing internal circuit/tick data
]
"python/quantum-pecos/src/pecos/qec/analysis/influence.py" = [
    "SLF001",   # Private member access - accessing internal circuit/tick data
    "PLW0127",  # Self-assignment - intentional pattern for influence propagation
]
# SLR qeclib visualization - matplotlib lazy imports
"python/quantum-pecos/src/pecos/slr/qeclib/color488/plot_layout.py" = [
    "PLC0415",  # Import inside function - matplotlib optional
]
"python/quantum-pecos/src/pecos/slr/qeclib/surface/visualization/lattice_2d.py" = [
    "PLC0415",  # Import inside function - matplotlib optional
]

# Test files
"python/*/tests/**/*.py" = [
    "F401",     # Imported but unused - OK in tests for import availability checks
    "INP001",   # File is part of an implicit namespace package - OK for test directories
    "S101",     # Use of `assert` detected - Assert is standard practice in test files
    "N802",     # Function name should be lowercase - Test functions often match gate names
    "PLC0415",  # Import inside try/except for optional dependencies - OK in tests
    "S311",     # Standard pseudo-random generators - OK for tests
    "S301",     # Pickle - OK for test data
    "S603",     # Subprocess calls - OK in tests for running build tools (cargo, llvm-as)
    "S607",     # Starting process with partial path - OK for testing common tools
    "BLE001",   # Blind except - OK in tests for checking error conditions
    "PT017",    # Assertions in except blocks - testing error conditions
    "FBT003",   # Boolean positional values - OK in tests for explicit boolean testing
    "TRY300",   # Try-except patterns in test code
]
"python/selene-plugins/*/tests/**/*.py" = [
    "F401",     # Imported but unused - OK in tests
    "INP001",   # File is part of an implicit namespace package - OK for test directories
    "S101",     # Use of `assert` detected - standard in tests
    "BLE001",   # Blind except - OK in tests for checking error conditions
]
"python/slr-tests/**/*.py" = [
    "INP001",   # File is part of an implicit namespace package - OK for test directories
    "S101",     # Use of `assert` detected - Assert is standard practice in test files
    "N802",     # Function name should be lowercase - Test functions often match gate names
    "PLC0415",  # Import inside try/except for optional dependencies - OK in tests
    "S311",     # Standard pseudo-random generators - OK for tests
    "S301",     # Pickle - OK for test data
]
"python/pecos-rslib/tests/*.py" = [
    "INP001",   # Test files don't need __init__.py
]
# Gate matrix definitions use standard quantum notation (I, X, Y, Z for Pauli matrices)
"python/quantum-pecos/tests/pecos/integration/state_sim_tests/gate_matrix_def.py" = [
    "E741",     # Ambiguous variable name - I, X, Y, Z are standard Pauli matrix names
    "N806",     # Variable in function should be lowercase - quantum gate naming conventions
]
# Linear algebra tests use standard quantum/math notation (I, X, Z for matrices)
"python/quantum-pecos/tests/pecos/test_array_linalg.py" = [
    "E741",     # Ambiguous variable name - I, X, Z are standard matrix names
    "N806",     # Variable in function should be lowercase - quantum gate naming conventions
]

# Scripts and examples - not packages
"scripts/**/*.py" = ["INP001", "S603", "PLC0415", "S301", "BLE001"]  # Script files: no __init__.py, subprocess calls, lazy imports, pickle, broad except
"examples/**/*.py" = ["INP001", "BLE001"]  # Example files don't need __init__.py and can use broad exception handling


# Jupyter notebooks - exploratory code, less strict than library code
"**/*.ipynb" = [
    "S101",     # Use of `assert` - appropriate for demonstrations
    "E402",     # Import not at top of cell - common notebook pattern
    "E501",     # Line too long - titles and display strings in notebooks
    "FBT003",   # Boolean positional - standard matplotlib API (grid(True), show(True))
    "ARG001",   # Unused argument - prototype/placeholder functions in notebooks
    "PERF401",  # List append in loop - step-by-step code aids notebook readability
    "ANN",      # Type annotations - not required in notebooks
]

# Simulator files
"python/quantum-pecos/src/pecos/simulators/*.py" = [
    "N802",  # Quantum gate functions use uppercase names (H, X, Y, Z, CX, CZ, etc.)
]

# SLR (Simple Logical Representation) DSL
"python/quantum-pecos/src/pecos/slr/*.py" = [
    "ANN",
    "D",
    "N802",  # DSL methods use capitalized names (Then, Else, Do) for readability
    "PLW1641",  # __hash__ not needed for DSL classes
]
# Specific SLR files with DSL methods
"python/quantum-pecos/src/pecos/slr/__init__.py" = ["N814"]  # Main as SLR
# SLR code generation files - complex legacy code with many style issues
"python/quantum-pecos/src/pecos/slr/gen_codes/*.py" = [
    "PLC0415",  # Function-level imports for optional dependencies
    "B905",  # zip without strict - legacy code
    "B007",  # Loop variables not used - legacy patterns
    "PLW2901",  # Variable overwrite in loops - legacy patterns
]
"python/quantum-pecos/src/pecos/slr/gen_codes/guppy/*.py" = [
    "PLC0415",  # Function-level imports
    "B905",  # zip without strict
    "B007",  # Unused loop variables
    "B009",  # getattr with constant - used for private API access
    "B028",  # stacklevel in warnings - not critical
    "B904",  # raise from - exception handling patterns
]
"python/quantum-pecos/src/pecos/slr/slr_converter.py" = ["PLC0415"]  # Optional guppy import

# Private member access for simulator internal APIs
"python/quantum-pecos/src/pecos/simulators/statevec/bindings.py" = ["SLF001"]  # private _sim access
"python/pecos-rslib/src/pecos_rslib/*.py" = ["SLF001"]  # private _sim access

# Documentation
"python/quantum-pecos/docs/conf.py" = ["A001", "INP001"]  # Sphinx expects 'copyright' variable

# Re-export modules
"python/quantum-pecos/src/pecos/rslib.py" = ["F403"]  # Re-exporting all symbols from pecos_rslib

# Hatch build hooks - standalone build scripts, not packages
"python/selene-plugins/*/hatch_build.py" = ["ARG002", "INP001", "PLC0415", "S603", "S607"]  # Build scripts call cargo, version arg required by interface, conditional imports for macOS

# Subprocess calls (S603, S607) - These call trusted build tools and compilers
"python/pecos-rslib/src/pecos_rslib/selene_compilation.py" = ["S603", "S607", "TRY301"]  # llc, gcc compilation
"python/pecos-rslib/src/pecos_rslib/selene_simple_runtime.py" = ["S603", "S607"]  # Build tools
"python/quantum-pecos/src/pecos/frontends/hugr_llvm_compiler.py" = ["S603", "S607"]  # cargo build
"python/quantum-pecos/src/pecos/engines/selene_engine_builder.py" = ["S603", "S607", "TRY301"]  # file command
"python/quantum-pecos/src/pecos/selene_subprocess_engine.py" = ["S603", "S607"]  # Selene subprocess
"python/quantum-pecos/src/pecos/_compilation/guppy.py" = ["S603", "S607", "PLC0415", "TRY301"]  # HUGR/LLVM compilation tools
"python/quantum-pecos/src/pecos/_compilation/hugr_llvm.py" = ["S603", "S607"]  # cargo build, hugr-to-llvm binary


# Stub files (.pyi) - type stubs need flexibility
"**/*.pyi" = ["ANN401", "PYI021", "PYI048"]  # Any types and stub-specific issues allowed

# Optional dependency imports (PLC0415) - These files load dependencies lazily for performance
# and to handle optional features gracefully
"python/pecos-rslib/src/pecos_rslib/bridge_*.py" = ["PLC0415", "ANN401", "SLF001"]  # Bridge: lazy loading, Any types, monkey-patching
"python/pecos-rslib/src/pecos_rslib/selene_*.py" = ["PLC0415"]  # Selene: optional dependency
"python/pecos-rslib/src/pecos_rslib/guppy_conversion.py" = ["PLC0415"]  # Guppy: optional dependency
"python/quantum-pecos/src/pecos/compilation_pipeline.py" = ["PLC0415"]  # Multiple optional backends
"python/quantum-pecos/src/pecos/execute_llvm.py" = ["PLC0415"]  # Optional LLVM backends
"python/quantum-pecos/src/pecos/frontends/*.py" = ["PLC0415"]  # All frontends have optional dependencies
"python/quantum-pecos/src/pecos/frontends/guppy_frontend.py" = ["PLC0415", "S603", "S607"]  # Also uses subprocess for external tools
"python/quantum-pecos/src/pecos/frontends/selene_native_backend.py" = ["S311"]  # Uses random for test placeholders
"python/quantum-pecos/src/pecos/qeccs/plot.py" = ["PLC0415"]  # matplotlib: optional visualization dependency
"python/quantum-pecos/src/pecos/qeclib/color488/plot_layout.py" = ["PLC0415"]  # matplotlib: optional visualization dependency
"python/quantum-pecos/src/pecos/qeclib/surface/visualization/lattice_2d.py" = ["PLC0415"]  # matplotlib: optional visualization dependency
"python/quantum-pecos/src/pecos/tools/pseudo_threshold_tools.py" = ["PLC0415"]  # matplotlib: optional visualization dependency

# Examples - relaxed rules for demonstration code
"python/pecos-rslib/examples/*.py" = ["PLC0415", "INP001"]  # Lazy imports, no __init__.py needed
"examples/*.py" = ["PLC0415", "INP001", "BLE001"]  # Lazy imports, no __init__.py, broad exception handling OK

# Placeholder/stub functions
"python/pecos-rslib/src/pecos_rslib/__init__.py" = ["N802"]  # Stub functions matching class names

# Files with specific security patterns
"python/quantum-pecos/src/pecos/engines/cvm/wasm.py" = ["S301"]  # Pickle for trusted circuit metadata
"python/quantum-pecos/tests/pecos/unit/test_rng.py" = ["S311"]  # Testing RNG bounds

# Multiprocessing worker - must catch all exceptions
"python/quantum-pecos/src/pecos/engines/hybrid_engine_multiprocessing.py" = ["BLE001"]  # Must catch all in worker

# QEC conventions - specific files with special naming
"python/quantum-pecos/src/pecos/qeclib/steane/meas/destructive_meas.py" = ["N802"]  # MeasDecode follows QEC naming conventions

# Files with private member access for internal APIs
"python/quantum-pecos/src/pecos/simulators/mps_pytket/state.py" = ["SLF001"]  # MPS internal APIs
"python/quantum-pecos/tests/guppy/test_helpers.py" = ["SLF001"]  # Test metadata marking
"python/quantum-pecos/tests/guppy/test_selene_library_integration.py" = ["SLF001"]  # Testing internal builder methods
"python/quantum-pecos/tests/pecos/unit/test_surface_sweep_math.py" = ["SLF001"]  # Testing internal fit helpers in sweep example script

# Try-except patterns (TRY300) - Complex error handling in integration code
"python/pecos-rslib/src/pecos_rslib/sim_wrapper.py" = ["TRY300"]  # Wrapper patterns