sphinx/.ruff.toml

target-version = "py39"  # Pin Ruff to Python 3.9
line-length = 95
output-format = "full"

extend-exclude = [
    "tests/roots/*",
    "tests/js/roots/*",
    "build/*",
    "doc/_build/*",
    "sphinx/search/*",
    "doc/usage/extensions/example*.py",
]

[lint]
preview = true
ignore = [
    # flake8-annotations
    "ANN401",  # Dynamically typed expressions (typing.Any) are disallowed in `{name}`
    # pycodestyle
    "E741",  # Ambiguous variable name: `{name}`
    # pyflakes
    "F841",  # Local variable `{name}` is assigned to but never used
    # refurb
    "FURB101",  # `open` and `read` should be replaced by `Path(...).read_text(...)`
    "FURB103",  # `open` and `write` should be replaced by `Path(...).write_text(...)`
    # pylint
    "PLC1901",  # simplify truthy/falsey string comparisons
    # flake8-simplify
    "SIM102",  # Use a single `if` statement instead of nested `if` statements
    "SIM108",  # Use ternary operator `{contents}` instead of `if`-`else`-block
    # pyupgrade
    "UP031",   # Use format specifiers instead of percent format
    "UP032",   # Use f-string instead of `format` call
]
external = [  # Whitelist for RUF100 unknown code warnings
    "E704",
    "SIM113",
]
select = [
    # flake8-builtins ('A')
      # NOT YET USED
    # airflow ('AIR')
      # Airflow is not used in Sphinx
    # flake8-annotations ('ANN')
    "ANN",
    # flake8-unused-arguments ('ARG')
    "ARG004",  # Unused static method argument: `{name}`
    # flake8-async ('ASYNC')
    "ASYNC",
    # flake8-bugbear ('B')
    "B",
    # flake8-blind-except ('BLE')
      # NOT YET USED
    # flake8-comprehensions ('C4')
    "C4",
    # mccabe ('C90')
#    "C901",  # `{name}` is too complex ({complexity} > {max_complexity})
    # flake8-commas ('COM')
    "COM818",  # Trailing comma on bare tuple prohibited
    "COM819",  # Trailing comma prohibited
    # flake8-copyright ('CPY')
      # NOT YET USED
    # pydocstyle ('D')
#    "D100",  # Missing docstring in public module
#    "D101",  # Missing docstring in public class
#    "D102",  # Missing docstring in public method
#    "D103",  # Missing docstring in public function
#    "D104",  # Missing docstring in public package
#    "D105",  # Missing docstring in magic method
    "D106",  # Missing docstring in public nested class
#    "D107",  # Missing docstring in `__init__`
#    "D200",  # One-line docstring should fit on one line
    "D201",  # No blank lines allowed before function docstring (found {num_lines})
    "D202",  # No blank lines allowed after function docstring (found {num_lines})
    "D204",  # 1 blank line required after class docstring
#    "D205",  # 1 blank line required between summary line and description
    "D206",  # Docstring should be indented with spaces, not tabs
    "D207",  # Docstring is under-indented
    "D208",  # Docstring is over-indented
    "D209",  # Multi-line docstring closing quotes should be on a separate line
    "D210",  # No whitespaces allowed surrounding docstring text
    "D211",  # No blank lines allowed before class docstring
#    "D212",  # Multi-line docstring summary should start at the first line
#    "D213",  # Multi-line docstring summary should start at the second line
#    "D214",  # Section is over-indented ("{name}")
#    "D215",  # Section underline is over-indented ("{name}")
    "D300",  # Use triple double quotes `"""`
    "D301",  # Use `r"""` if any backslashes in a docstring
#    "D400",  # First line should end with a period
#    "D401",  # First line of docstring should be in imperative mood: "{first_line}"
    "D402",  # First line should not be the function's signature
    "D403",  # First word of the first line should be capitalized: `{}` -> `{}`
#    "D404",  # First word of the docstring should not be "This"
    "D405",  # Section name should be properly capitalized ("{name}")
#    "D406",  # Section name should end with a newline ("{name}")
#    "D407",  # Missing dashed underline after section ("{name}")
    "D408",  # Section underline should be in the line following the section's name ("{name}")
    "D409",  # Section underline should match the length of its name ("{name}")
    "D410",  # Missing blank line after section ("{name}")
    "D411",  # Missing blank line before section ("{name}")
#    "D412",  # No blank lines allowed between a section header and its content ("{name}")
#    "D413",  # Missing blank line after last section ("{name}")
    "D414",  # Section has no content ("{name}")
#    "D415",  # First line should end with a period, question mark, or exclamation point
    "D416",  # Section name should end with a colon ("{name}")
    "D417",  # Missing argument description in the docstring for `{definition}`: `{name}`
    "D418",  # Function decorated with `@overload` shouldn't contain a docstring
    "D419",  # Docstring is empty
    # flake8-django ('DJ')
      # Django is not used in Sphinx
    # flake8-datetimez ('DTZ')
    "DTZ",
    # pycodestyle ('E')
    "E",
    # flake8-errmsg ('EM')
    "EM",
    # eradicate ('ERA')
      # NOT YET USED
    # flake8-executable ('EXE')
    "EXE",
    # pyflakes ('F')
    "F",
    # flake8-future-annotations ('FA')
    "FA",
    # flake8-boolean-trap ('FBT')
      # NOT YET USED
    # flake8-fixme ('FIX')
      # NOT YET USED
    # flynt ('FLY')
    "FLY",
    # refurb ('FURB')
    "FURB",
    # flake8-logging-format ('G')
    "G001",  # Logging statement uses `str.format`
    "G002",  # Logging statement uses `%`
#    "G003",  # Logging statement uses `+`
    "G004",  # Logging statement uses f-string
    "G010",  # Logging statement uses `warn` instead of `warning`
    "G101",  # Logging statement uses an `extra` field that clashes with a `LogRecord` field: `{key}`
    "G201",  # Logging `.exception(...)` should be used instead of `.error(..., exc_info=True)`
    "G202",  # Logging statement has redundant `exc_info`
    # isort ('I')
    "I",
    # flake8-import-conventions ('ICN')
    "ICN",  # flake8-import-conventions
    # flake8-no-pep420 ('INP')
    "INP",
    # flake8-gettext ('INT')
    "INT",
    # flake8-implicit-str-concat ('ISC')
      # NOT YET USED
    # flake8-logging ('LOG')
    "LOG",
    # pep8-naming ('N')
      # NOT YET USED
    # numpy-specific rules ('NPY')
      # Numpy is not used in Sphinx
    # pandas-vet ('PD')
      # Pandas is not used in Sphinx
    # perflint ('PERF')
    "PERF101",  # Do not cast an iterable to `list` before iterating over it
    "PERF102",  # When using only the {subset} of a dict use the `{subset}()` method
#    "PERF203",  # `try`-`except` within a loop incurs performance overhead
    "PERF401",  # Use a list comprehension to create a transformed list
    "PERF402",  # Use `list` or `list.copy` to create a copy of a list
    "PERF403",  # Use a dictionary comprehension instead of a for-loop
    # pygrep-hooks ('PGH')
    "PGH",
    # flake8-pie ('PIE')
#    "PIE790",  # Unnecessary `pass` statement
    "PIE794",  # Class field `{name}` is defined multiple times
    "PIE796",  # Enum contains duplicate value: `{value}`
    "PIE800",  # Unnecessary spread `**`
    "PIE804",  # Unnecessary `dict` kwargs
    "PIE807",  # Prefer `list` over useless lambda
    "PIE810",  # Call `{attr}` once with a `tuple`
    # pylint ('PLC')
    "PLC0105",  # `{kind}` name "{param_name}" does not reflect its {variance}; consider renaming it to "{replacement_name}"
    "PLC0131",  # `{kind}` cannot be both covariant and contravariant
    "PLC0132",  # `{kind}` name `{param_name}` does not match assigned variable name `{var_name}`
    "PLC0205",  # Class `__slots__` should be a non-string iterable
    "PLC0208",  # Use a sequence type instead of a `set` when iterating over values
    "PLC0414",  # Import alias does not rename original package
#    "PLC0415",  # `import` should be at the top-level of a file
    "PLC1901",  # `{existing}` can be simplified to `{replacement}` as an empty string is falsey
    "PLC2401",  # {kind} name `{name}` contains a non-ASCII character, consider renaming it
    "PLC2403",  # Module alias `{name}` contains a non-ASCII character, use an ASCII-only alias
#    "PLC2701",  # Private name import `{name}` from external module `{module}`
    "PLC2801",  # Unnecessary dunder call to `{method}`. {replacement}.
    "PLC3002",  # Lambda expression called directly. Execute the expression inline instead.
    # pylint ('PLE')
    "PLE0100",  # `__init__` method is a generator
    "PLE0101",  # Explicit return in `__init__`
    "PLE0116",  # `continue` not supported inside `finally` clause
    "PLE0117",  # Nonlocal name `{name}` found without binding
    "PLE0118",  # Name `{name}` is used prior to global declaration on line {line}
    "PLE0241",  # Duplicate base `{base}` for class `{class}`
    "PLE0302",  # The special method `{}` expects {}, {} {} given
    "PLE0307",  # `__str__` does not return `str`
    "PLE0604",  # Invalid object in `__all__`, must contain only strings
    "PLE0605",  # Invalid format for `__all__`, must be `tuple` or `list`
    "PLE1142",  # `await` should be used within an async function
    "PLE1205",  # Too many arguments for `logging` format string
    "PLE1206",  # Not enough arguments for `logging` format string
    "PLE1300",  # Unsupported format character '{}'
    "PLE1307",  # Format type does not match argument type
    "PLE1310",  # String `{strip}` call contains duplicate characters (did you mean `{removal}`?)
    "PLE1507",  # Invalid type for initial `os.getenv` argument; expected `str`
    "PLE1700",  # `yield from` statement in async function; use `async for` instead
    "PLE2502",  # Contains control characters that can permit obfuscated code
    "PLE2510",  # Invalid unescaped character backspace, use "\b" instead
    "PLE2512",  # Invalid unescaped character SUB, use "\x1A" instead
    "PLE2513",  # Invalid unescaped character ESC, use "\x1B" instead
    "PLE2514",  # Invalid unescaped character NUL, use "\0" instead
    "PLE2515",  # Invalid unescaped character zero-width-space, use "\u200B" instead
    # pylint ('PLR')
#    "PLR0124",  # Name compared with itself, consider replacing `{left} {} {right}`
    "PLR0133",  # Two constants compared in a comparison, consider replacing `{left_constant} {} {right_constant}`
    "PLR0206",  # Cannot have defined parameters for properties
    "PLR0402",  # Use `from {module} import {name}` in lieu of alias
#    "PLR0911",  # Too many return statements ({returns} > {max_returns})
#    "PLR0912",  # Too many branches ({branches} > {max_branches})
#    "PLR0913",  # Too many arguments to function call ({c_args} > {max_args})
#    "PLR0915",  # Too many statements ({statements} > {max_statements})
    "PLR1701",  # Merge `isinstance` calls: `{expr}`
    "PLR1711",  # Useless `return` statement at end of function
#    "PLR1714",  # Consider merging multiple comparisons: `{expr}`. Use a `set` if the elements are hashable.
    "PLR1722",  # Use `sys.exit()` instead of `{name}`
#    "PLR2004",  # Magic value used in comparison, consider replacing {value} with a constant variable
#    "PLR5501",  # Use `elif` instead of `else` then `if`, to reduce indentation
    # pylint ('PLW')
    "PLW0120",  # `else` clause on loop without a `break` statement; remove the `else` and de-indent all the code inside it
    "PLW0127",  # Self-assignment of variable `{name}`
    "PLW0129",  # Asserting on an empty string literal will never pass
    "PLW0131",  # Named expression used without context
    "PLW0406",  # Module `{name}` imports itself
    "PLW0602",  # Using global for `{name}` but no assignment is done
#    "PLW0603",  # Using the global statement to update `{name}` is discouraged
    "PLW0711",  # Exception to catch is the result of a binary `and` operation
    "PLW1508",  # Invalid type for environment variable default; expected `str` or `None`
    "PLW1509",  # `preexec_fn` argument is unsafe when using threads
#    "PLW2901",  # Outer {outer_kind} variable `{name}` overwritten by inner {inner_kind} target
    "PLW3301",  # Nested `{}` calls can be flattened
    # flake8-pytest-style ('PT')
    "PT",
    # flake8-use-pathlib ('PTH')
      # NOT YET USED
    # flake8-pyi ('PYI')
      # NOT YET USED
    # flake8-quotes ('Q')
#    "Q000",  # Double quotes found but single quotes preferred
#    "Q001",  # Single quote multiline found but double quotes preferred
    "Q002",  # Single quote docstring found but double quotes preferred
    "Q003",  # Change outer quotes to avoid escaping inner quotes
    "Q004",  # Unnecessary escape on inner quote character
    # flake8-return ('RET')
    "RET501",  # Do not explicitly `return None` in function if it is the only possible return value
    "RET502",  # Do not implicitly `return None` in function able to return non-`None` value
#    "RET503",  # Missing explicit `return` at the end of function able to return non-`None` value
#    "RET504",  # Unnecessary assignment to `{name}` before `return` statement
#    "RET505",  # Unnecessary `{branch}` after `return` statement
#    "RET506",  # Unnecessary `{branch}` after `raise` statement
    "RET507",  # Unnecessary `{branch}` after `continue` statement
    "RET508",  # Unnecessary `{branch}` after `break` statement
    # flake8-raise ('RSE')
    "RSE102",  # Unnecessary parentheses on raised exception
    # ruff-specific rules ('RUF')
#    "RUF001",  # String contains ambiguous {}. Did you mean {}?
    "RUF002",  # Docstring contains ambiguous {}. Did you mean {}?
#    "RUF003",  # Comment contains ambiguous {}. Did you mean {}?
    "RUF005",  # Consider `{expression}` instead of concatenation
    "RUF006",  # Store a reference to the return value of `asyncio.{method}`
    "RUF007",  # Prefer `itertools.pairwise()` over `zip()` when iterating over successive pairs
    "RUF008",  # Do not use mutable default values for dataclass attributes
    "RUF009",  # Do not perform function call `{name}` in dataclass defaults
    "RUF010",  # Use explicit conversion flag
#    "RUF012",  # Mutable class attributes should be annotated with `typing.ClassVar`
    "RUF013",  # PEP 484 prohibits implicit `Optional`
#    "RUF015",  # Prefer `next({iterable})` over single element slice
    "RUF016",  # Slice in indexed access to type `{value_type}` uses type `{index_type}` instead of an integer
    "RUF017",  # Avoid quadratic list summation
    "RUF018",  # Avoid assignment expressions in `assert` statements
    "RUF019",  # Unnecessary key check before dictionary access
    "RUF020",  # `{never_like} | T` is equivalent to `T`
#    "RUF100",  # Unused `noqa` directive
    "RUF200",  # Failed to parse pyproject.toml: {message}
    # flake8-bandit ('S')
#    "S101",  # Use of `assert` detected
    "S102",  # Use of `exec` detected
    "S103",  # `os.chmod` setting a permissive mask `{mask:#o}` on file or directory
    "S104",  # Possible binding to all interfaces
#    "S105",  # Possible hardcoded password assigned to: "{}"
    "S106",  # Possible hardcoded password assigned to argument: "{}"
    "S107",  # Possible hardcoded password assigned to function default: "{}"
    "S108",  # Probable insecure usage of temporary file or directory: "{}"
#    "S110",  # `try`-`except`-`pass` detected, consider logging the exception
    "S112",  # `try`-`except`-`continue` detected, consider logging the exception
#    "S113",  # Probable use of requests call without timeout
#    "S301",  # `pickle` and modules that wrap it can be unsafe when used to deserialize untrusted data, possible security issue
    "S302",  # Deserialization with the `marshal` module is possibly dangerous
    "S303",  # Use of insecure MD2, MD4, MD5, or SHA1 hash function
    "S304",  # Use of insecure cipher, replace with a known secure cipher such as AES
    "S305",  # Use of insecure cipher mode, replace with a known secure cipher such as AES
    "S306",  # Use of insecure and deprecated function (`mktemp`)
    "S307",  # Use of possibly insecure function; consider using `ast.literal_eval`
    "S308",  # Use of `mark_safe` may expose cross-site scripting vulnerabilities
    "S310",  # Audit URL open for permitted schemes. Allowing use of `file:` or custom schemes is often unexpected.
    "S311",  # Standard pseudo-random generators are not suitable for cryptographic purposes
    "S312",  # Telnet-related functions are being called. Telnet is considered insecure. Use SSH or some other encrypted protocol.
    "S313",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S314",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S315",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S316",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S317",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S318",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S319",  # Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents
    "S320",  # Using `lxml` to parse untrusted data is known to be vulnerable to XML attacks
    "S321",  # FTP-related functions are being called. FTP is considered insecure. Use SSH/SFTP/SCP or some other encrypted protocol.
    "S323",  # Python allows using an insecure context via the `_create_unverified_context` that reverts to the previous behavior that does not validate certificates or perform hostname checks.
#    "S324",  # Probable use of insecure hash functions in `hashlib`: `{string}`
    "S501",  # Probable use of `{string}` call with `verify=False` disabling SSL certificate checks
    "S506",  # Probable use of unsafe loader `{name}` with `yaml.load`. Allows instantiation of arbitrary objects. Consider `yaml.safe_load`.
    "S508",  # The use of SNMPv1 and SNMPv2 is insecure. Use SNMPv3 if able.
    "S509",  # You should not use SNMPv3 without encryption. `noAuthNoPriv` & `authNoPriv` is insecure.
    "S601",  # Possible shell injection via Paramiko call; check inputs are properly sanitized
    "S602",  # `subprocess` call with `shell=True` seems safe, but may be changed in the future; consider rewriting without `shell`
#    "S603",  # `subprocess` call: check for execution of untrusted input
    "S604",  # Function call with `shell=True` parameter identified, security issue
    "S605",  # Starting a process with a shell: seems safe, but may be changed in the future; consider rewriting without `shell`
    "S606",  # Starting a process without a shell
#    "S607",  # Starting a process with a partial executable path
    "S608",  # Possible SQL injection vector through string-based query construction
    "S609",  # Possible wildcard injection in call due to `*` usage
    "S612",  # Use of insecure `logging.config.listen` detected
#    "S701",  # Using jinja2 templates with `autoescape=False` is dangerous and can lead to XSS. Ensure `autoescape=True` or use the `select_autoescape` function.
#    "S702",  # Mako templates allow HTML and JavaScript rendering by default and are inherently open to XSS attacks
    # flake8-simplify ('SIM')
    "SIM",  # flake8-simplify
    # flake8-self ('SLF')
      # NOT YET USED
    # flake8-slots ('SLOT')
    "SLOT",
    # flake8-debugger ('T10')
    "T100",  # Trace found: `{name}` used
    # flake8-print ('T20')
    "T201",  # `print` found
    "T203",  # `pprint` found
    # flake8-type-checking ('TCH')
    "TCH",
    # flake8-todos ('TD')
#    "TD001",  # Invalid TODO tag: `{tag}`
#    "TD003",  # Missing issue link on the line following this TODO
#    "TD004",  # Missing colon in TODO
#    "TD005",  # Missing issue description after `TODO`
    "TD006",  # Invalid TODO capitalization: `{tag}` should be `TODO`
    "TD007",  # Missing space after colon in TODO
    # flake8-tidy-imports ('TID')
    "TID251",  # `{name}` is banned: {message}
    "TID252",  # Relative imports from parent modules are banned
    "TID253",  # `{name}` is banned at the module level
    # flake8-trio ('TRIO')
      # Trio is not used in Sphinx
    # tryceratops ('TRY')
      # NOT YET USED
    # pyupgrade ('UP')
    "UP",
    # pycodestyle ('W')
    "W",
    # flake8-2020 ('YTT')
    "YTT",
]

[lint.per-file-ignores]
"doc/*" = [
    "ANN",  # documentation doesn't need annotations
]
"doc/conf.py" = ["INP001", "W605"]
"doc/development/tutorials/examples/*" = ["INP001"]
# allow print() in the tutorial
"doc/development/tutorials/examples/recipe.py" = [
    "FURB118",
    "T201"
]
"sphinx/domains/**" = ["FURB113"]
"tests/test_domains/test_domain_cpp.py" = ["FURB113"]

# from .flake8
"sphinx/*" = ["E241"]

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

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

"sphinx/environment/collectors/toctree.py" = ["B026"]
"sphinx/environment/adapters/toctree.py" = ["B026"]

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

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

# Ruff bug: https://github.com/astral-sh/ruff/issues/6540
"sphinx/transforms/i18n.py" = ["PGH004"]

# Function wrappers
"sphinx/ext/autodoc/importer.py" = ["D402"]
"sphinx/util/requests.py" = ["D402"]

"tests/*" = [
    "E501",
    "ANN",  # tests don't need annotations
    "D402",
    "T201",  # whitelist ``print`` for tests
]

# these tests need old ``typing`` generic aliases
"tests/test_util/test_util_typing.py" = ["UP006", "UP035"]
"tests/test_util/typing_test_data.py" = ["FA100", "UP006", "UP035"]

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

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

[lint.isort]
forced-separate = [
    "tests",
]

[format]
preview = true
quote-style = "single"
exclude = [
    "sphinx/_cli/*",
    "sphinx/addnodes.py",
    "sphinx/application.py",
    "sphinx/builders/*",
    "sphinx/cmd/*",
    "sphinx/config.py",
    "sphinx/directives/*",
    "sphinx/domains/*",
    "sphinx/environment/*",
    "sphinx/ext/*",
    "sphinx/pycode/*",
    "sphinx/pygments_styles.py",
    "sphinx/registry.py",
    "sphinx/search/*",
    "sphinx/testing/*",
    "sphinx/transforms/*",
    "sphinx/util/*",
    "sphinx/writers/*",
    "tests/*",
    "tests/roots/*",
    "tests/test_builders/*",
    "tests/test_config/*",
    "tests/test_directives/*",
    "tests/test_domains/*",
    "tests/test_environment/*",
    "tests/test_extensions/*",
    "tests/test_intl/*",
    "tests/test_markup/*",
    "tests/test_pycode/*",
    "tests/test_transforms/*",
    "tests/test_util/*",
    "tests/test_writers/*",
]