ruff.toml

# This file is part of the jebel-quant/rhiza repository
# (https://github.com/jebel-quant/rhiza).
#
# Maximum line length for the entire project
line-length = 120
# Target Python version is inferred from project.requires-python.

# Exclude directories with Jinja template variables in their names
exclude = ["**/[{][{]*/", "**/*[}][}]*/"]

[lint]
# Available rule sets in Ruff:
# A: flake8-builtins - Check for python builtins being used as variables or parameters
# B: flake8-bugbear - Find likely bugs and design problems
# C4: flake8-comprehensions - Helps write better list/set/dict comprehensions
# D: pydocstyle - Check docstring style
# E: pycodestyle errors - PEP 8 style guide
# ERA: eradicate - Find commented out code
# F: pyflakes - Detect logical errors
# I: isort - Sort imports
# N: pep8-naming - Check PEP 8 naming conventions
# PT: flake8-pytest-style - Check pytest best practices
# RUF: Ruff-specific rules
# S: flake8-bandit - Find security issues
# SIM: flake8-simplify - Simplify code
# T10: flake8-debugger - Check for debugger imports and calls
# UP: pyupgrade - Upgrade syntax for newer Python
# W: pycodestyle warnings - PEP 8 style guide warnings
# ANN: flake8-annotations - Type annotation checks
# ARG: flake8-unused-arguments - Unused arguments
# BLE: flake8-blind-except - Check for blind except statements
# COM: flake8-commas - Trailing comma enforcement
# DTZ: flake8-datetimez - Ensure timezone-aware datetime objects
# EM: flake8-errmsg - Check error message strings
# FBT: flake8-boolean-trap - Boolean argument checks
# ICN: flake8-import-conventions - Import convention enforcement
# ISC: flake8-implicit-str-concat - Implicit string concatenation
# NPY: NumPy-specific rules
# PD: pandas-specific rules
# PGH: pygrep-hooks - Grep-based checks
# PIE: flake8-pie - Miscellaneous rules
# PL: Pylint rules
# Q: flake8-quotes - Quotation style enforcement
# RSE: flake8-raise - Raise statement checks
# RET: flake8-return - Return statement checks
# SLF: flake8-self - Check for self references
# TCH: flake8-type-checking - Type checking imports
# TID: flake8-tidy-imports - Import tidying
# TRY: flake8-try-except-raise - Try/except/raise checks
# YTT: flake8-2020 - Python 2020+ compatibility

select = [
    "D",   # pydocstyle - Check docstring style
    "E",   # pycodestyle errors - PEP 8 style guide
    "F",   # pyflakes - Detect logical errors
    "I",   # isort - Sort imports
    "N",   # pep8-naming - Check PEP 8 naming conventions
    "W",   # pycodestyle warnings - PEP 8 style guide warnings
    "UP",  # pyupgrade - Upgrade syntax for newer Python
]

# Ensure docstrings are required for magic methods (e.g., __init__) and
# private/underscored modules by explicitly selecting the relevant pydocstyle
# rules in addition to the D set. This makes the intent clear and future-proof
# if the default pydocstyle selection changes.
extend-select = [
    "D105",  # pydocstyle - Require docstrings for magic methods
    "D107",  # pydocstyle - Require docstrings for __init__
    "A",     # flake8-builtins - Don't shadow Python builtins
    "ANN001", # flake8-annotations - Require function argument annotations
    "ANN2",   # flake8-annotations - Require function return annotations
    "ARG",   # flake8-unused-arguments - Unused arguments (tests exempt below: pytest fixtures)
    "B",     # flake8-bugbear - Find likely bugs and design problems
    "BLE",   # flake8-blind-except - No bare `except Exception` swallowing
    "C4",    # flake8-comprehensions - Better list/set/dict comprehensions
    "PIE",   # flake8-pie - Miscellaneous lints (duplicate class fields, useless spread, ...)
    "SIM",   # flake8-simplify - Simplify code
    "PT",    # flake8-pytest-style - Check pytest best practices
    "RUF",   # Ruff-specific rules
    "S",     # flake8-bandit - Find security issues
    "TRY",   # flake8-try-except-raise - Try/except/raise checks
    "ICN",   # flake8-import-conventions - Import convention enforcement
]

# Deliberately NOT enabled — exclusions are decisions, not omissions.
# One-line rationale per family; revisit when the rationale stops holding:
# ERA: templates, notebooks, and shipped configs legitimately carry commented-out example code
# T10: stray breakpoints/pdb imports would fail local pre-commit mid-debugging; review catches leftovers
# PL: Pylint family is large and opinionated (magic values, arg counts) — high noise for a template repo
# FBT: boolean positional flags (e.g. dry_run=True) are idiomatic in our test/make drivers
# COM: trailing-comma layout is owned by `ruff format`
# ISC: implicit string concatenation is handled/conflicted by `ruff format`
# Q: quote style is owned by `ruff format` (double quotes, configured below)
# RET: return-statement micro-style; SIM already covers the valuable simplifications
# EM: literal exception messages are fine at our scale; TRY covers exception-flow issues
# DTZ: no runtime code handling datetimes ships from this repo
# SLF: private-member access is needed in tests; too coarse to enable repo-wide
# TCH/TID: no typing-only import cycles or import-tidiness issues at this size
# RSE: raise micro-style; TRY covers the error-prone patterns
# NPY/PD: no NumPy/pandas runtime code in this repository
# YTT: Python 2020 sys.version checks are irrelevant on py311+
# PGH: its eval/blanket-ignore checks overlap with the S and RUF rules already enabled

# Resolve incompatible pydocstyle rules: prefer D211 and D212 over D203 and D213
ignore = [
    "ANN401",  # dynamically typed *args/**kwargs in framework hooks are intentional
    "D203",  # one-blank-line-before-class (conflicts with D211)
    "D213",  # multi-line-summary-second-line (conflicts with D212)
]

[lint.pydocstyle]
convention = "google"

# Formatting configuration
[format]
# Use double quotes for strings
quote-style = "double"
# Use spaces for indentation
indent-style = "space"
# Automatically detect and use the appropriate line ending
line-ending = "auto"

# File-specific rule exceptions
[lint.per-file-ignores]
# All test code, wherever it lives (the project suite under tests/, and the bundle
# copies under bundles/). This glob subsumes the project suite; tests/**/*.py below adds
# project-suite-only allowances on top. It used to cover a third tree, `.rhiza/tests/`,
# which the template synced; since #1540 the rhiza checks are an installed dependency and
# there is no template-owned Python in a consumer's tree to exempt.
"**/tests/**/*.py" = [
    "ANN",   # tests prioritize readability and fixtures over strict annotation coverage
    "S101",  # assert is the test idiom
    "S603",  # tests drive git/make/uv via subprocess with fixed argument lists
    "S607",  # partial executable paths (git, make) are intentional in test drivers
    "ARG",   # pytest fixtures are requested by name for their side effects, not always read
]
# Project test suite only — allowances the broader glob above should not hand to the
# bundle copies under bundles/
"tests/**/*.py" = [
    "RUF002",  # docstrings quote prose with typographic unicode (e.g. en dash)
    "RUF012",  # pytest class attributes are conventionally bare mutables, not ClassVar
]
# Marimo notebooks - allow flexible coding patterns for interactive exploration
"**/notebooks/*.py" = [
    "ANN",     # notebooks prioritize interactive readability over strict annotation coverage
    "D100",    # No module docstring - marimo requires `import marimo` as the first statement
    "N803",    # Allow non-lowercase variable names in notebooks
    "S101",    # Allow assert statements in notebooks
    "PLC0415", # Allow imports not at top-level in notebooks
    "B018",    # Allow useless expressions in notebooks
    "RUF001",  # Allow ambiguous unicode in notebooks
    "RUF002",  # Allow ambiguous unicode in notebooks
]