sphinx/.ruff.toml

target-version = "py313"  # Pin Ruff to Python 3.13
line-length = 88
output-format = "full"

extend-exclude = [
    "build/*",
    "doc/_build/*",
    "tests/roots/test-directive-code/target.py",  # Tests break if formatted
    "tests/roots/test-pycode/cp_1251_coded.py",  # Not UTF-8
]

[format]
preview = true
quote-style = "single"

[lint]
preview = true
ignore = [
    # flake8-builtins
    "builtin-variable-shadowing",  # Variable `{name}` is shadowing a Python builtin
    "builtin-argument-shadowing",  # Function argument `{name}` is shadowing a Python builtin
    "stdlib-module-shadowing",  # Module `{name}` is shadowing a Python builtin module
    # flake8-annotations
    "any-type",  # Dynamically typed expressions (typing.Any) are disallowed in `{name}`
    # flake8-unused-arguments ('ARG')
    "unused-function-argument",  # Unused function argument: `{name}`
    "unused-method-argument",  # Unused method argument: `{name}`
    "unused-class-method-argument",  # Unused class method argument: `{name}`
    "unused-lambda-argument",  # Unused lambda argument: `{name}`
    # flake8-blind-except
    "blind-except",  # Do not catch blind exception: `{name}`
    # flake8-commas
    "missing-trailing-comma",  # Trailing comma missing
    # flake8-copyright
    "missing-copyright-notice",  # Missing copyright notice at top of file
    # pydocstyle ('D')
    "undocumented-public-module",  # Missing docstring in public module
    "undocumented-public-class",  # Missing docstring in public class
    "undocumented-public-method",  # Missing docstring in public method
    "undocumented-public-function",  # Missing docstring in public function
    "undocumented-public-package",  # Missing docstring in public package
    "undocumented-magic-method",  # Missing docstring in magic method
    "undocumented-public-init",  # Missing docstring in `__init__`
    "unnecessary-multiline-docstring",  # One-line docstring should fit on one line
    "missing-blank-line-after-summary",  # 1 blank line required between summary line and description
    "missing-trailing-period",  # First line should end with a period
    "non-imperative-mood",  # First line of docstring should be in imperative mood: "{first_line}"
    # pydoclint
    "docstring-missing-returns",  # `return` is not documented in docstring
    "docstring-missing-yields",  # `yield` is not documented in docstring
    "docstring-missing-exception",  # Raised exception `{id}` missing from docstring
    # pycodestyle
    "ambiguous-variable-name",  # Ambiguous variable name: `{name}`
    # eradicate
    "commented-out-code",  # Found commented-out code
    # pyflakes
    "unused-variable",  # Local variable `{name}` is assigned to but never used
    # flake8-boolean-trap
    "boolean-type-hint-positional-argument",  # Boolean-typed positional argument in function definition
    "boolean-default-value-positional-argument",  # Boolean default positional argument in function definition
    "boolean-positional-value-in-call",  # Boolean positional value in function call
    # flake8-fixme
    "line-contains-fixme",  # Line contains FIXME, consider resolving the issue
    "line-contains-todo",  # Line contains TODO, consider resolving the issue
    "line-contains-xxx",  # Line contains XXX, consider resolving the issue
    "line-contains-hack",  # Line contains HACK, consider resolving the issue
    # refurb
    "read-whole-file",  # `open` and `read` should be replaced by `Path(...).read_text(...)`
    "write-whole-file",  # `open` and `write` should be replaced by `Path(...).write_text(...)`
    # flake8-implicit-str-concat
    # pep8-naming
    "invalid-class-name",  # Class name `{name}` should use CapWords convention
    "invalid-function-name",  # Function name `{name}` should be lowercase
    "invalid-argument-name",  # Argument name `{name}` should be lowercase
    "non-lowercase-variable-in-function",  # Variable `{name}` in function should be lowercase
    "error-suffix-on-exception-name",  # Exception name `{name}` should be named with an Error suffix
    # perflint
    "try-except-in-loop",  # `try`-`except` within a loop incurs performance overhead
    # flake8-pie
    "unnecessary-placeholder",  # Unnecessary `pass` statement
    # pylint
    "import-outside-top-level",  # `import` should be at the top-level of a file
    "import-private-name",  # Private name import `{name}` from external module `{module}`
    "too-many-public-methods",  # Too many public methods ({methods} > {max_methods})
    "too-many-return-statements",  # Too many return statements ({returns} > {max_returns})
    "too-many-branches",  # Too many branches ({branches} > {max_branches})
    "too-many-arguments",  # Too many arguments in function definition ({c_args} > {max_args})
    "too-many-locals",  # Too many local variables ({current_amount}/{max_amount})
    "too-many-statements",  # Too many statements ({statements} > {max_statements})
    "too-many-boolean-expressions",  # Too many Boolean expressions ({expressions} > {max_expressions})
    "too-many-positional-arguments",  # Too many positional arguments ({c_pos}/{max_pos})
    "too-many-nested-blocks",  # Too many nested blocks ({nested_blocks} > {max_nested_blocks})
    "magic-value-comparison",  # Magic value used in comparison, consider replacing `{value}` with a constant variable
    "collapsible-else-if",  # Use `elif` instead of `else` then `if`, to reduce indentation
    "non-augmented-assignment",  # Use `{operator}` to perform an augmented assignment directly
    "no-self-use",  # Method `{method_name}` could be a function, class method, or static method
    "too-many-statements-in-try-clause",  # Try clause contains too many statements ({} > 5)
    "redefined-loop-name",  # Outer {outer_kind} variable `{name}` overwritten by inner {inner_kind} target
    # flake8-use-pathlib
    "os-path-abspath",  # `os.path.abspath()` should be replaced by `Path.resolve()`
    "os-path-exists",  # `os.path.exists()` should be replaced by `Path.exists()`
    "os-path-isfile",  # `os.path.isfile()` should be replaced by `Path.is_file()`
    "os-path-join",  # `os.{module}.join()` should be replaced by `Path` with `/` operator
    "os-path-basename",  # `os.path.basename()` should be replaced by `Path.name`
    "os-path-dirname",  # `os.path.dirname()` should be replaced by `Path.parent`
    "os-path-splitext",  # `os.path.splitext()` should be replaced by `Path.suffix`, `Path.stem`, and `Path.parent`
    "builtin-open",  # `open()` should be replaced by `Path.open()`
    # flake8-pyi ('PYI')
    "unaliased-collections-abc-set-import",  # Use `from collections.abc import Set as AbstractSet` to avoid confusion with the `set` builtin
    # flake8-return
    "unnecessary-assign",  # Unnecessary assignment to `{name}` before `return` statement
    "superfluous-else-return",  # Unnecessary `{branch}` after `return` statement
    "superfluous-else-raise",  # Unnecessary `{branch}` after `raise` statement
    # flake8-bandit ('S')
    "assert",  # Use of `assert` detected
    "try-except-pass",  # `try`-`except`-`pass` detected, consider logging the exception
    "suspicious-subprocess-import",  # `subprocess` module is possibly insecure
    "suspicious-xml-etree-import",  # `xml.etree` methods are vulnerable to XML attacks
    "subprocess-without-shell-equals-true",  # `subprocess` call: check for execution of untrusted input
    # flake8-simplify
    "collapsible-if",  # Use a single `if` statement instead of nested `if` statements
    "if-else-block-instead-of-if-exp",  # Use ternary operator `{contents}` instead of `if`-`else`-block
    # flake8-self
    "private-member-access",  # Private member accessed: `{access}`
    # flake8-todos ('TD')
    "invalid-todo-tag",  # Invalid TODO tag: `{tag}`
    "missing-todo-author",  # Missing author in TODO; try: `# TODO(<author_name>): ...` or `# TODO @<author_name>: ...`
    "missing-todo-link",  # Missing issue link on the line following this TODO
    "missing-todo-colon",  # Missing colon in TODO
    # tryceratops
    "raise-vanilla-class",  # Create your own exception
    "try-consider-else",  # Consider moving this statement to an `else` block
    # pyupgrade
    "printf-string-formatting",   # Use format specifiers instead of percent format
    "f-string",   # Use f-string instead of `format` call
    # Ruff-specific rules ('RUF')
    "mutable-class-default",  # Mutable class attributes should be annotated with `typing.ClassVar`
    "parenthesize-chained-operators",  # Parenthesize `a and b` expressions when chaining `and` and `or` together, to make the precedence clear
    "unsorted-dunder-all",  # `__all__` is not sorted
    "unsorted-dunder-slots",  # `{}.__slots__` is not sorted
    "missing-f-string-syntax",  # Possible f-string without an `f` prefix
    "unraw-re-pattern",  # First argument to {call} is not raw string
    "used-dummy-variable",  # Local dummy variable `{}` is accessed
    "non-empty-init-module",  # `__init__` module should only contain docstrings and re-exports
    "float-equality-comparison",  # Unreliable floating point equality comparison `{}`
]
external = [  # Whitelist for RUF100 unknown code warnings
    "SIM113",
]
select = [
    # flake8-builtins ('A')
    "A",
    # airflow ('AIR')
      # Airflow is not used in Sphinx
    # flake8-annotations ('ANN')
    "ANN",
    # flake8-unused-arguments ('ARG')
    "ARG",
    # flake8-async ('ASYNC')
    "ASYNC",
    # flake8-bugbear ('B')
    "B",
    # flake8-blind-except ('BLE')
    "BLE",
    # flake8-comprehensions ('C4')
    "C4",
    # mccabe ('C90')
#    "C901",  # `{name}` is too complex ({complexity} > {max_complexity})
    # flake8-commas ('COM')
    "COM",  # Trailing comma prohibited
    # flake8-copyright ('CPY')
    "CPY",
    # pydocstyle ('D')
    "D",
    "multi-line-summary-first-line",  # Multi-line docstring summary should start at the first line
    # "D404",  # First word of the docstring should not be "This"
    # "D415",  # First line should end with a period, question mark, or exclamation point
    "undocumented-param",  # Missing argument description in the docstring for `{definition}`: `{name}`
    # pydoclint ('DOC')
    "DOC",
    # flake8-django ('DJ')
      # Django is not used in Sphinx
    # flake8-datetimez ('DTZ')
    "DTZ",
    # pycodestyle ('E')
    "E",
    # flake8-errmsg ('EM')
    "EM",
    # eradicate ('ERA')
    "ERA",
    # flake8-executable ('EXE')
    "EXE",
    # pyflakes ('F')
    "F",
    # flake8-future-annotations ('FA')
    "FA",
    # flake8-fastapi ('FAST')
      # FastAPI is not used in Sphinx
    # flake8-boolean-trap ('FBT')
    "FBT",
    # flake8-fixme ('FIX')
    "FIX",
    # flynt ('FLY')
    "FLY",
    # refurb ('FURB')
    "FURB",
    # flake8-logging-format ('G')
    "G",
    # isort ('I')
    "I",
    # flake8-import-conventions ('ICN')
    "ICN",
    # flake8-no-pep420 ('INP')
    "INP",
    # flake8-gettext ('INT')
    "INT",
    # flake8-implicit-str-concat ('ISC')
    "ISC",
    # flake8-logging ('LOG')
    "LOG",
    # pep8-naming ('N')
    "N",
    # numpy-specific rules ('NPY')
      # Numpy is not used in Sphinx
    # pandas-vet ('PD')
      # Pandas is not used in Sphinx
    # perflint ('PERF')
    "PERF",
    # pygrep-hooks ('PGH')
    "PGH",
    # flake8-pie ('PIE')
    "PIE",
    # pylint ('PL', 'PLC', 'PLE', 'PLR', 'PLW')
    "PL",
    # flake8-pytest-style ('PT')
    "PT",
    # flake8-use-pathlib ('PTH')
    "PTH",
    # flake8-pyi ('PYI')
    "PYI",
    # flake8-quotes ('Q')
    "Q",
    # flake8-return ('RET')
    "RET",
    # flake8-raise ('RSE')
    "RSE",
    # Ruff-specific rules ('RUF')
    "RUF",
    # flake8-bandit ('S')
    "S",
    # flake8-simplify ('SIM')
    "SIM",  # flake8-simplify
    # flake8-self ('SLF')
    "SLF",
    # flake8-slots ('SLOT')
    "SLOT",
    # flake8-debugger ('T10')
    "T10",
    # flake8-print ('T20')
    "T20",
    # flake8-type-checking ('TC')
    "TC",
    # flake8-todos ('TD')
    "TD",
    # flake8-tidy-imports ('TID')
    "TID",
    # flake8-trio ('TRIO')
      # Trio is not used in Sphinx
    # tryceratops ('TRY')
    "TRY",
    # pyupgrade ('UP')
    "UP",
    # pycodestyle ('W')
    "W",
    # flake8-2020 ('YTT')
    "YTT",
]

logger-objects = [
    "sphinx.ext.apidoc._shared.LOGGER",
    "sphinx.ext.autodoc._shared.LOGGER",
    "sphinx.ext.intersphinx._shared.LOGGER",
]

[lint.per-file-ignores]
"doc/*" = [
    "ANN",  # documentation doesn't need annotations
    "typing-only-first-party-import",  # documentation doesn't need type-checking blocks
]
"doc/conf.py" = [
    "implicit-namespace-package",  # doc/ is not a namespace package
]
"doc/development/tutorials/examples/*" = [
    "missing-required-import",  # we don't need the annotations future
    "implicit-namespace-package",  # examples/ is not a namespace package
]
"doc/development/tutorials/examples/recipe.py" = [
    "reimplemented-operator",  # keep the tutorial simple: no itemgetter
    "print"  # allow print() in the tutorial
]
"doc/usage/extensions/example_{google,numpy}.py" = [
    "missing-section-name-colon",  # Section name should end with a colon ("{name}")
    "docstring-extraneous-exception",  # Raised exception is not explicitly raised: `{id}`
    "missing-required-import",  # Missing required import: {name}
    "implicit-namespace-package",  # File {filename} is part of an implicit namespace package. Add an __init__.py.
    "bad-dunder-method-name",  # Dunder method {name} has no special meaning in Python 3
]

# whitelist ``print`` for stdout messages
"sphinx/_cli/__init__.py" = ["print"]

# allow use of ``pickle``
"sphinx/{application,builders/__init__,environment/__init__,ext/coverage,search/__init__,versioning}.py" = [
    "suspicious-pickle-usage",
    "suspicious-pickle-import",
]

# whitelist ``print`` for stdout messages
"sphinx/cmd/build.py" = ["print"]
"sphinx/cmd/make_mode.py" = ["print"]
"sphinx/cmd/quickstart.py" = [
    "PTH",
    "print",
]

"sphinx/environment/collectors/toctree.py" = ["star-arg-unpacking-after-keyword-arg"]
"sphinx/environment/adapters/toctree.py" = ["star-arg-unpacking-after-keyword-arg"]

# whitelist ``print`` for stdout messages
"sphinx/ext/intersphinx/_cli.py" = ["print"]

# whitelist ``token`` in docstring parsing
"sphinx/ext/napoleon/docstring.py" = ["hardcoded-password-string"]

"sphinx/search/*" = ["ambiguous-unicode-character-string"]

# whitelist ``print`` for stdout messages
"sphinx/testing/fixtures.py" = ["print"]

# whitelist ``os.path`` for deprecated ``sphinx.testing.path``
"sphinx/testing/path.py" = ["PTH"]

# whitelist ``token`` in date format parsing
"sphinx/util/i18n.py" = ["hardcoded-password-string"]

# whitelist ``os.path`` for ``sphinx.util.osutil``
"sphinx/util/osutil.py" = ["PTH"]

# whitelist ``token`` in literal parsing
"sphinx/writers/html5.py" = ["hardcoded-password-string"]

"tests/*" = [
    "line-too-long",
    "ANN",  # tests don't need annotations
    "signature-in-docstring",
    "compare-to-empty-string",  # whitelist comparisons to the empty string ('')
    "ambiguous-unicode-character-string",  # ambiguous unicode character
    "suspicious-pickle-usage",  # allow use of ``pickle``
    "suspicious-pickle-import",  # allow use of ``pickle``
    "print",  # whitelist ``print`` for tests
]

# test roots are not packages
"tests/js/roots/*" = ["missing-required-import", "implicit-namespace-package"]
"tests/roots/*" = [
    "first-word-uncapitalized",  # permit uncapitalised docstrings
    "unused-import",  # names may be unused in test roots
    "missing-required-import",  # we don't need the annotations future
    "implicit-namespace-package",  # test roots are not packages
]

# these tests need old ``typing`` generic aliases
"tests/roots/test-ext-autodoc/target/genericalias.py" = ["non-pep585-annotation", "non-pep604-annotation-union", "deprecated-import", "non-pep604-annotation-optional"]
"tests/test_util/test_util_typing.py" = ["none-not-at-end-of-union", "non-pep585-annotation", "non-pep604-annotation-union", "deprecated-import", "non-pep604-annotation-optional"]
"tests/test_util/typing_test_data.py" = ["future-rewritable-type-annotation", "missing-required-import", "unnecessary-literal-union", "non-pep585-annotation", "non-pep604-annotation-union", "deprecated-import", "non-pep604-annotation-optional"]

# these tests need old-style type comments
"tests/roots/test-ext-autodoc/target/autodoc_type_aliases.py" = ["legacy-type-comment"]
"tests/roots/test-ext-autodoc/target/cached_property.py" = ["legacy-type-comment"]
"tests/roots/test-ext-autodoc/target/properties.py" = ["legacy-type-comment"]
"tests/roots/test-ext-autodoc/target/typed_vars.py" = ["legacy-type-comment"]
"tests/roots/test-ext-autodoc/target/typehints.py" = ["legacy-type-comment"]

"utils/*" = [
    "print",  # whitelist ``print`` for stdout messages
    "ANN",  # utilities don't need annotations
]

[lint.pycodestyle]
max-line-length = 95

[lint.flake8-quotes]
inline-quotes = "single"

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

[lint.isort]
forced-separate = [
    "tests",
]
required-imports = [
    "from __future__ import annotations",
]

[lint.pydocstyle]
convention = "pep257"
ignore-decorators = ["typing.overload"]
ignore-var-parameters = true