diff --git a/README.md b/README.md index 990b8053c2..76b222254c 100644 --- a/README.md +++ b/README.md @@ -1267,1974 +1267,7 @@ You can also ask for help on [**Discord**](https://discord.gg/c9MhzV8aU5). ## Reference - - - - - -### Top-level - -#### [`allowed-confusables`](#allowed-confusables) - -A list of allowed "confusable" Unicode characters to ignore when -enforcing `RUF001`, `RUF002`, and `RUF003`. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -# Allow minus-sign (U+2212), greek-small-letter-rho (U+03C1), and the asterisk-operator (U+2217), -# which could be confused for "-", "p", and "*", respectively. -allowed-confusables = ["−", "ρ", "∗"] -``` - ---- - -#### [`builtins`](#builtins) - -A list of builtins to treat as defined references, in addition to the -system builtins. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -builtins = ["_"] -``` - ---- - -#### [`cache-dir`](#cache-dir) - -A path to the cache directory. - -By default, Ruff stores cache results in a `.ruff_cache` directory in -the current project root. - -However, Ruff will also respect the `RUFF_CACHE_DIR` environment -variable, which takes precedence over that default. - -This setting will override even the `RUFF_CACHE_DIR` environment -variable, if set. - -**Default value**: `.ruff_cache` - -**Type**: `str` - -**Example usage**: - -```toml -[tool.ruff] -cache-dir = "~/.cache/ruff" -``` - ---- - -#### [`dummy-variable-rgx`](#dummy-variable-rgx) - -A regular expression used to identify "dummy" variables, or those which -should be ignored when enforcing (e.g.) unused-variable rules. The -default expression matches `_`, `__`, and `_var`, but not `_var_`. - -**Default value**: `"^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"` - -**Type**: `re.Pattern` - -**Example usage**: - -```toml -[tool.ruff] -# Only ignore variables named "_". -dummy-variable-rgx = "^_$" -``` - ---- - -#### [`exclude`](#exclude) - -A list of file patterns to exclude from linting. - -Exclusions are based on globs, and can be either: - -* Single-path patterns, like `.mypy_cache` (to exclude any directory - named `.mypy_cache` in the tree), `foo.py` (to exclude any file named - `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ). -* Relative patterns, like `directory/foo.py` (to exclude that specific - file) or `directory/*.py` (to exclude any Python files in - `directory`). Note that these paths are relative to the project root - (e.g., the directory containing your `pyproject.toml`). - -For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax). - -Note that you'll typically want to use -[`extend-exclude`](#extend-exclude) to modify the excluded paths. - -**Default value**: `[".bzr", ".direnv", ".eggs", ".git", ".hg", ".mypy_cache", ".nox", ".pants.d", ".pytype", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "build", "dist", "node_modules", "venv"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -exclude = [".venv"] -``` - ---- - -#### [`extend`](#extend) - -A path to a local `pyproject.toml` file to merge into this -configuration. User home directory and environment variables will be -expanded. - -To resolve the current `pyproject.toml` file, Ruff will first resolve -this base configuration file, then merge in any properties defined -in the current configuration file. - -**Default value**: `None` - -**Type**: `str` - -**Example usage**: - -```toml -[tool.ruff] -# Extend the `pyproject.toml` file in the parent directory. -extend = "../pyproject.toml" -# But use a different line length. -line-length = 100 -``` - ---- - -#### [`extend-exclude`](#extend-exclude) - -A list of file patterns to omit from linting, in addition to those -specified by `exclude`. - -Exclusions are based on globs, and can be either: - -* Single-path patterns, like `.mypy_cache` (to exclude any directory - named `.mypy_cache` in the tree), `foo.py` (to exclude any file named - `foo.py`), or `foo_*.py` (to exclude any file matching `foo_*.py` ). -* Relative patterns, like `directory/foo.py` (to exclude that specific - file) or `directory/*.py` (to exclude any Python files in - `directory`). Note that these paths are relative to the project root - (e.g., the directory containing your `pyproject.toml`). - -For more information on the glob syntax, refer to the [`globset` documentation](https://docs.rs/globset/latest/globset/#syntax). - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -# In addition to the standard set of exclusions, omit all tests, plus a specific file. -extend-exclude = ["tests", "src/bad.py"] -``` - ---- - -#### [`extend-ignore`](#extend-ignore) - -A list of rule codes or prefixes to ignore, in addition to those -specified by `ignore`. - -This option has been **deprecated** in favor of `ignore` -since its usage is now interchangeable with `ignore`. - -**Default value**: `[]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# Skip unused variable rules (`F841`). -extend-ignore = ["F841"] -``` - ---- - -#### [`extend-select`](#extend-select) - -A list of rule codes or prefixes to enable, in addition to those -specified by `select`. - -**Default value**: `[]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# On top of the default `select` (`E`, `F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`). -extend-select = ["B", "Q"] -``` - ---- - -#### [`external`](#external) - -A list of rule codes that are unsupported by Ruff, but should be -preserved when (e.g.) validating `# noqa` directives. Useful for -retaining `# noqa` directives that cover plugins not yet implemented -by Ruff. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -# Avoiding flagging (and removing) `V101` from any `# noqa` -# directives, despite Ruff's lack of support for `vulture`. -external = ["V101"] -``` - ---- - -#### [`fix`](#fix) - -Enable autofix behavior by-default when running `ruff` (overridden -by the `--fix` and `--no-fix` command-line flags). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -fix = true -``` - ---- - -#### [`fix-only`](#fix-only) - -Like `fix`, but disables reporting on leftover violation. Implies `fix`. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -fix-only = true -``` - ---- - -#### [`fixable`](#fixable) - -A list of rule codes or prefixes to consider autofixable. By default, -all rules are considered autofixable. - -**Default value**: `["A", "ANN", "ARG", "B", "BLE", "C", "COM", "D", "DTZ", "E", "EM", "ERA", "EXE", "F", "FBT", "G", "I", "ICN", "INP", "ISC", "N", "PD", "PGH", "PIE", "PL", "PT", "PTH", "Q", "RET", "RUF", "S", "SIM", "T", "TCH", "TID", "TRY", "UP", "W", "YTT"]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# Only allow autofix behavior for `E` and `F` rules. -fixable = ["E", "F"] -``` - ---- - -#### [`force-exclude`](#force-exclude) - -Whether to enforce `exclude` and `extend-exclude` patterns, even for -paths that are passed to Ruff explicitly. Typically, Ruff will lint -any paths passed in directly, even if they would typically be -excluded. Setting `force-exclude = true` will cause Ruff to -respect these exclusions unequivocally. - -This is useful for [`pre-commit`](https://pre-commit.com/), which explicitly passes all -changed files to the [`ruff-pre-commit`](https://github.com/charliermarsh/ruff-pre-commit) -plugin, regardless of whether they're marked as excluded by Ruff's own -settings. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -force-exclude = true -``` - ---- - -#### [`format`](#format) - -The style in which violation messages should be formatted: `"text"` -(default), `"grouped"` (group messages by file), `"json"` -(machine-readable), `"junit"` (machine-readable XML), `"github"` (GitHub -Actions annotations), `"gitlab"` (GitLab CI code quality report), or -`"pylint"` (Pylint text format). - -**Default value**: `"text"` - -**Type**: `"text" | "json" | "junit" | "github" | "gitlab" | "pylint"` - -**Example usage**: - -```toml -[tool.ruff] -# Group violations by containing file. -format = "grouped" -``` - ---- - -#### [`ignore`](#ignore) - -A list of rule codes or prefixes to ignore. Prefixes can specify exact -rules (like `F841`), entire categories (like `F`), or anything in -between. - -When breaking ties between enabled and disabled rules (via `select` and -`ignore`, respectively), more specific prefixes override less -specific prefixes. - -**Default value**: `[]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# Skip unused variable rules (`F841`). -ignore = ["F841"] -``` - ---- - -#### [`ignore-init-module-imports`](#ignore-init-module-imports) - -Avoid automatically removing unused imports in `__init__.py` files. Such -imports will still be flagged, but with a dedicated message suggesting -that the import is either added to the module's `__all__` symbol, or -re-exported with a redundant alias (e.g., `import os as os`). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -ignore-init-module-imports = true -``` - ---- - -#### [`line-length`](#line-length) - -The line length to use when enforcing long-lines violations (like -`E501`). - -**Default value**: `88` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff] -# Allow lines to be as long as 120 characters. -line-length = 120 -``` - ---- - -#### [`namespace-packages`](#namespace-packages) - -Mark the specified directories as namespace packages. For the purpose of -module resolution, Ruff will treat those directories as if they -contained an `__init__.py` file. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -namespace-packages = ["airflow/providers"] -``` - ---- - -#### [`per-file-ignores`](#per-file-ignores) - -A list of mappings from file pattern to rule codes or prefixes to -exclude, when considering any matching files. - -**Default value**: `{}` - -**Type**: `dict[str, list[RuleSelector]]` - -**Example usage**: - -```toml -[tool.ruff] -# Ignore `E402` (import violations) in all `__init__.py` files, and in `path/to/file.py`. -[tool.ruff.per-file-ignores] -"__init__.py" = ["E402"] -"path/to/file.py" = ["E402"] -``` - ---- - -#### [`required-version`](#required-version) - -Require a specific version of Ruff to be running (useful for unifying -results across many environments, e.g., with a `pyproject.toml` -file). - -**Default value**: `None` - -**Type**: `str` - -**Example usage**: - -```toml -[tool.ruff] -required-version = "0.0.193" -``` - ---- - -#### [`respect-gitignore`](#respect-gitignore) - -Whether to automatically exclude files that are ignored by `.ignore`, -`.gitignore`, `.git/info/exclude`, and global `gitignore` files. -Enabled by default. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -respect-gitignore = false -``` - ---- - -#### [`select`](#select) - -A list of rule codes or prefixes to enable. Prefixes can specify exact -rules (like `F841`), entire categories (like `F`), or anything in -between. - -When breaking ties between enabled and disabled rules (via `select` and -`ignore`, respectively), more specific prefixes override less -specific prefixes. - -**Default value**: `["E", "F"]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# On top of the defaults (`E`, `F`), enable flake8-bugbear (`B`) and flake8-quotes (`Q`). -select = ["E", "F", "B", "Q"] -``` - ---- - -#### [`show-fixes`](#show-fixes) - -Whether to show an enumeration of all autofixed lint violations -(overridden by the `--show-fixes` command-line flag). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -# By default, always enumerate fixed violations. -show-fixes = true -``` - ---- - -#### [`show-source`](#show-source) - -Whether to show source code snippets when reporting lint violations -(overridden by the `--show-source` command-line flag). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -# By default, always show source code snippets. -show-source = true -``` - ---- - -#### [`src`](#src) - -The source code paths to consider, e.g., when resolving first- vs. -third-party imports. - -As an example: given a Python package structure like: - -```text -my_package/ - pyproject.toml - src/ - my_package/ - __init__.py - foo.py - bar.py -``` - -The `src` directory should be included in the `src` option (e.g., `src = -["src"]`), such that when resolving imports, `my_package.foo` is -considered a first-party import. - -This field supports globs. For example, if you have a series of Python -packages in a `python_modules` directory, `src = -["python_modules/*"]` would expand to incorporate all of the -packages in that directory. User home directory and environment -variables will also be expanded. - -**Default value**: `["."]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -# Allow imports relative to the "src" and "test" directories. -src = ["src", "test"] -``` - ---- - -#### [`target-version`](#target-version) - -The Python version to target, e.g., when considering automatic code -upgrades, like rewriting type annotations. Note that the target -version will _not_ be inferred from the _current_ Python version, -and instead must be specified explicitly (as seen below). - -**Default value**: `"py310"` - -**Type**: `"py37" | "py38" | "py39" | "py310" | "py311"` - -**Example usage**: - -```toml -[tool.ruff] -# Always generate Python 3.7-compatible code. -target-version = "py37" -``` - ---- - -#### [`task-tags`](#task-tags) - -A list of task tags to recognize (e.g., "TODO", "FIXME", "XXX"). - -Comments starting with these tags will be ignored by commented-out code -detection (`ERA`), and skipped by line-length rules (`E501`) if -`ignore-overlong-task-comments` is set to `true`. - -**Default value**: `["TODO", "FIXME", "XXX"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -task-tags = ["HACK"] -``` - ---- - -#### [`typing-modules`](#typing-modules) - -A list of modules whose imports should be treated equivalently to -members of the `typing` module. - -This is useful for ensuring proper type annotation inference for -projects that re-export `typing` and `typing_extensions` members -from a compatibility module. If omitted, any members imported from -modules apart from `typing` and `typing_extensions` will be treated -as ordinary Python objects. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff] -typing-modules = ["airflow.typing_compat"] -``` - ---- - -#### [`unfixable`](#unfixable) - -A list of rule codes or prefixes to consider non-autofix-able. - -**Default value**: `[]` - -**Type**: `list[RuleSelector]` - -**Example usage**: - -```toml -[tool.ruff] -# Disable autofix for unused imports (`F401`). -unfixable = ["F401"] -``` - ---- - -#### [`update-check`](#update-check) - -Enable or disable automatic update checks (overridden by the -`--update-check` and `--no-update-check` command-line flags). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff] -update-check = true -``` - ---- - -### `flake8-annotations` - -#### [`allow-star-arg-any`](#allow-star-arg-any) - -Whether to suppress `ANN401` for dynamically typed `*args` and -`**kwargs` arguments. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-annotations] -allow-star-arg-any = true -``` - ---- - -#### [`ignore-fully-untyped`](#ignore-fully-untyped) - -Whether to suppress `ANN*` rules for any declaration -that hasn't been typed at all. -This makes it easier to gradually add types to a codebase. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-annotations] -ignore-fully-untyped = true -``` - ---- - -#### [`mypy-init-return`](#mypy-init-return) - -Whether to allow the omission of a return type hint for `__init__` if at -least one argument is annotated. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-annotations] -mypy-init-return = true -``` - ---- - -#### [`suppress-dummy-args`](#suppress-dummy-args) - -Whether to suppress `ANN000`-level violations for arguments matching the -"dummy" variable regex (like `_`). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-annotations] -suppress-dummy-args = true -``` - ---- - -#### [`suppress-none-returning`](#suppress-none-returning) - -Whether to suppress `ANN200`-level violations for functions that meet -either of the following criteria: - -* Contain no `return` statement. -* Explicit `return` statement(s) all return `None` (explicitly or - implicitly). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-annotations] -suppress-none-returning = true -``` - ---- - -### `flake8-bandit` - -#### [`check-typed-exception`](#check-typed-exception) - -Whether to disallow `try`-`except`-`pass` (`S110`) for specific -exception types. By default, `try`-`except`-`pass` is only -disallowed for `Exception` and `BaseException`. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-bandit] -check-typed-exception = true -``` - ---- - -#### [`hardcoded-tmp-directory`](#hardcoded-tmp-directory) - -A list of directories to consider temporary. - -**Default value**: `["/tmp", "/var/tmp", "/dev/shm"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-bandit] -hardcoded-tmp-directory = ["/foo/bar"] -``` - ---- - -#### [`hardcoded-tmp-directory-extend`](#hardcoded-tmp-directory-extend) - -A list of directories to consider temporary, in addition to those -specified by `hardcoded-tmp-directory`. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-bandit] -extend-hardcoded-tmp-directory = ["/foo/bar"] -``` - ---- - -### `flake8-bugbear` - -#### [`extend-immutable-calls`](#extend-immutable-calls) - -Additional callable functions to consider "immutable" when evaluating, -e.g., the `no-mutable-default-argument` rule (`B006`). - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-bugbear] -# Allow default arguments like, e.g., `data: List[str] = fastapi.Query(None)`. -extend-immutable-calls = ["fastapi.Depends", "fastapi.Query"] -``` - ---- - -### `flake8-builtins` - -#### [`builtins-ignorelist`](#builtins-ignorelist) - -Ignore list of builtins. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-builtins] -builtins-ignorelist = ["id"] -``` - ---- - -### `flake8-errmsg` - -#### [`max-string-length`](#max-string-length) - -Maximum string length for string literals in exception messages. - -**Default value**: `0` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.flake8-errmsg] -max-string-length = 20 -``` - ---- - -### `flake8-implicit-str-concat` - -#### [`allow-multiline`](#allow-multiline) - -Whether to allow implicit string concatenations for multiline strings. -By default, implicit concatenations of multiline strings are -allowed (but continuation lines, delimited with a backslash, are -prohibited). - -Note that setting `allow-multiline = false` should typically be coupled -with disabling `explicit-string-concatenation` (`ISC003`). Otherwise, -both explicit and implicit multiline string concatenations will be seen -as violations. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-implicit-str-concat] -allow-multiline = false -``` - ---- - -### `flake8-import-conventions` - -#### [`aliases`](#aliases) - -The conventional aliases for imports. These aliases can be extended by -the `extend_aliases` option. - -**Default value**: `{"altair": "alt", "matplotlib": "mpl", "matplotlib.pyplot": "plt", "numpy": "np", "pandas": "pd", "seaborn": "sns", "tensorflow": "tf", "holoviews": "hv", "panel": "pn", "plotly.express": "px", "polars": "pl", "pyarrow": "pa"}` - -**Type**: `dict[str, str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-import-conventions] -[tool.ruff.flake8-import-conventions.aliases] -# Declare the default aliases. -altair = "alt" -"matplotlib.pyplot" = "plt" -numpy = "np" -pandas = "pd" -seaborn = "sns" -scipy = "sp" -``` - ---- - -#### [`extend-aliases`](#extend-aliases) - -A mapping of modules to their conventional import aliases. These aliases -will be added to the `aliases` mapping. - -**Default value**: `{}` - -**Type**: `dict[str, str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-import-conventions] -[tool.ruff.flake8-import-conventions.extend-aliases] -# Declare a custom alias for the `matplotlib` module. -"dask.dataframe" = "dd" -``` - ---- - -### `flake8-pytest-style` - -#### [`fixture-parentheses`](#fixture-parentheses) - -Boolean flag specifying whether `@pytest.fixture()` without parameters -should have parentheses. If the option is set to `true` (the -default), `@pytest.fixture()` is valid and `@pytest.fixture` is -invalid. If set to `false`, `@pytest.fixture` is valid and -`@pytest.fixture()` is invalid. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -fixture-parentheses = true -``` - ---- - -#### [`mark-parentheses`](#mark-parentheses) - -Boolean flag specifying whether `@pytest.mark.foo()` without parameters -should have parentheses. If the option is set to `true` (the -default), `@pytest.mark.foo()` is valid and `@pytest.mark.foo` is -invalid. If set to `false`, `@pytest.fixture` is valid and -`@pytest.mark.foo()` is invalid. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -mark-parentheses = true -``` - ---- - -#### [`parametrize-names-type`](#parametrize-names-type) - -Expected type for multiple argument names in `@pytest.mark.parametrize`. -The following values are supported: - -* `csv` — a comma-separated list, e.g. - `@pytest.mark.parametrize('name1,name2', ...)` -* `tuple` (default) — e.g. `@pytest.mark.parametrize(('name1', 'name2'), - ...)` -* `list` — e.g. `@pytest.mark.parametrize(['name1', 'name2'], ...)` - -**Default value**: `tuple` - -**Type**: `"csv" | "tuple" | "list"` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -parametrize-names-type = "list" -``` - ---- - -#### [`parametrize-values-row-type`](#parametrize-values-row-type) - -Expected type for each row of values in `@pytest.mark.parametrize` in -case of multiple parameters. The following values are supported: - -* `tuple` (default) — e.g. `@pytest.mark.parametrize(('name1', 'name2'), - [(1, 2), (3, 4)])` -* `list` — e.g. `@pytest.mark.parametrize(('name1', 'name2'), [[1, 2], - [3, 4]])` - -**Default value**: `tuple` - -**Type**: `"tuple" | "list"` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -parametrize-values-row-type = "list" -``` - ---- - -#### [`parametrize-values-type`](#parametrize-values-type) - -Expected type for the list of values rows in `@pytest.mark.parametrize`. -The following values are supported: - -* `tuple` — e.g. `@pytest.mark.parametrize('name', (1, 2, 3))` -* `list` (default) — e.g. `@pytest.mark.parametrize('name', [1, 2, 3])` - -**Default value**: `list` - -**Type**: `"tuple" | "list"` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -parametrize-values-type = "tuple" -``` - ---- - -#### [`raises-extend-require-match-for`](#raises-extend-require-match-for) - -List of additional exception names that require a match= parameter in a -`pytest.raises()` call. This extends the default list of exceptions -that require a match= parameter. -This option is useful if you want to extend the default list of -exceptions that require a match= parameter without having to specify -the entire list. -Note that this option does not remove any exceptions from the default -list. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -raises-extend-require-match-for = ["requests.RequestException"] -``` - ---- - -#### [`raises-require-match-for`](#raises-require-match-for) - -List of exception names that require a match= parameter in a -`pytest.raises()` call. - -**Default value**: `["BaseException", "Exception", "ValueError", "OSError", "IOError", "EnvironmentError", "socket.error"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-pytest-style] -raises-require-match-for = ["requests.RequestException"] -``` - ---- - -### `flake8-quotes` - -#### [`avoid-escape`](#avoid-escape) - -Whether to avoid using single quotes if a string contains single quotes, -or vice-versa with double quotes, as per [PEP 8](https://peps.python.org/pep-0008/#string-quotes). -This minimizes the need to escape quotation marks within strings. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-quotes] -# Don't bother trying to avoid escapes. -avoid-escape = false -``` - ---- - -#### [`docstring-quotes`](#docstring-quotes) - -Quote style to prefer for docstrings (either "single" or "double"). - -**Default value**: `"double"` - -**Type**: `"single" | "double"` - -**Example usage**: - -```toml -[tool.ruff.flake8-quotes] -docstring-quotes = "single" -``` - ---- - -#### [`inline-quotes`](#inline-quotes) - -Quote style to prefer for inline strings (either "single" or -"double"). - -**Default value**: `"double"` - -**Type**: `"single" | "double"` - -**Example usage**: - -```toml -[tool.ruff.flake8-quotes] -inline-quotes = "single" -``` - ---- - -#### [`multiline-quotes`](#multiline-quotes) - -Quote style to prefer for multiline strings (either "single" or -"double"). - -**Default value**: `"double"` - -**Type**: `"single" | "double"` - -**Example usage**: - -```toml -[tool.ruff.flake8-quotes] -multiline-quotes = "single" -``` - ---- - -### `flake8-tidy-imports` - -#### [`ban-relative-imports`](#ban-relative-imports) - -Whether to ban all relative imports (`"all"`), or only those imports -that extend into the parent module or beyond (`"parents"`). - -**Default value**: `"parents"` - -**Type**: `"parents" | "all"` - -**Example usage**: - -```toml -[tool.ruff.flake8-tidy-imports] -# Disallow all relative imports. -ban-relative-imports = "all" -``` - ---- - -#### [`banned-api`](#banned-api) - -Specific modules or module members that may not be imported or accessed. -Note that this rule is only meant to flag accidental uses, -and can be circumvented via `eval` or `importlib`. - -**Default value**: `{}` - -**Type**: `dict[str, { "msg": str }]` - -**Example usage**: - -```toml -[tool.ruff.flake8-tidy-imports] -[tool.ruff.flake8-tidy-imports.banned-api] -"cgi".msg = "The cgi module is deprecated, see https://peps.python.org/pep-0594/#cgi." -"typing.TypedDict".msg = "Use typing_extensions.TypedDict instead." -``` - ---- - -### `flake8-type-checking` - -#### [`exempt-modules`](#exempt-modules) - -Exempt certain modules from needing to be moved into type-checking -blocks. - -**Default value**: `["typing"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.flake8-type-checking] -exempt-modules = ["typing", "typing_extensions"] -``` - ---- - -#### [`strict`](#strict) - -Enforce TC001, TC002, and TC003 rules even when valid runtime imports -are present for the same module. -See flake8-type-checking's [strict](https://github.com/snok/flake8-type-checking#strict) option. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-type-checking] -strict = true -``` - ---- - -### `flake8-unused-arguments` - -#### [`ignore-variadic-names`](#ignore-variadic-names) - -Whether to allow unused variadic arguments, like `*args` and `**kwargs`. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.flake8-unused-arguments] -ignore-variadic-names = true -``` - ---- - -### `isort` - -#### [`classes`](#classes) - -An override list of tokens to always recognize as a Class for -`order-by-type` regardless of casing. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -classes = ["SVC"] -``` - ---- - -#### [`combine-as-imports`](#combine-as-imports) - -Combines as imports on the same line. See isort's [`combine-as-imports`](https://pycqa.github.io/isort/docs/configuration/options.html#combine-as-imports) -option. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -combine-as-imports = true -``` - ---- - -#### [`constants`](#constants) - -An override list of tokens to always recognize as a CONSTANT -for `order-by-type` regardless of casing. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -constants = ["constant"] -``` - ---- - -#### [`extra-standard-library`](#extra-standard-library) - -A list of modules to consider standard-library, in addition to those -known to Ruff in advance. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -extra-standard-library = ["path"] -``` - ---- - -#### [`force-single-line`](#force-single-line) - -Forces all from imports to appear on their own line. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -force-single-line = true -``` - ---- - -#### [`force-sort-within-sections`](#force-sort-within-sections) - -Don't sort straight-style imports (like `import sys`) before from-style -imports (like `from itertools import groupby`). Instead, sort the -imports by module, independent of import style. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -force-sort-within-sections = true -``` - ---- - -#### [`force-to-top`](#force-to-top) - -Force specific imports to the top of their appropriate section. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -force-to-top = ["src"] -``` - ---- - -#### [`force-wrap-aliases`](#force-wrap-aliases) - -Force `import from` statements with multiple members and at least one -alias (e.g., `import A as B`) to wrap such that every line contains -exactly one member. For example, this formatting would be retained, -rather than condensing to a single line: - -```python -from .utils import ( - test_directory as test_directory, - test_id as test_id -) -``` - -Note that this setting is only effective when combined with -`combine-as-imports = true`. When `combine-as-imports` isn't -enabled, every aliased `import from` will be given its own line, in -which case, wrapping is not necessary. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -force-wrap-aliases = true -combine-as-imports = true -``` - ---- - -#### [`forced-separate`](#forced-separate) - -A list of modules to separate into auxiliary block(s) of imports, -in the order specified. - -**Default value**: `[]` - -**Type**: `Vec` - -**Example usage**: - -```toml -[tool.ruff.isort] -forced-separate = ["tests"] -``` - ---- - -#### [`known-first-party`](#known-first-party) - -A list of modules to consider first-party, regardless of whether they -can be identified as such via introspection of the local filesystem. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -known-first-party = ["src"] -``` - ---- - -#### [`known-local-folder`](#known-local-folder) - -A list of modules to consider being a local folder. -Generally, this is reserved for relative imports (`from . import module`). - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -known-local-folder = ["src"] -``` - ---- - -#### [`known-third-party`](#known-third-party) - -A list of modules to consider third-party, regardless of whether they -can be identified as such via introspection of the local filesystem. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -known-third-party = ["src"] -``` - ---- - -#### [`lines-after-imports`](#lines-after-imports) - -The number of blank lines to place after imports. -Use `-1` for automatic determination. - -**Default value**: `-1` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.isort] -# Use a single line after each import block. -lines-after-imports = 1 -``` - ---- - -#### [`lines-between-types`](#lines-between-types) - -The number of lines to place between "direct" and `import from` imports. - -**Default value**: `0` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.isort] -# Use a single line between direct and from import -lines-between-types = 1 -``` - ---- - -#### [`no-lines-before`](#no-lines-before) - -A list of sections that should _not_ be delineated from the previous -section via empty lines. - -**Default value**: `[]` - -**Type**: `list["future" | "standard-library" | "third-party" | "first-party" | "local-folder"]` - -**Example usage**: - -```toml -[tool.ruff.isort] -no-lines-before = ["future", "standard-library"] -``` - ---- - -#### [`order-by-type`](#order-by-type) - -Order imports by type, which is determined by case, in addition to -alphabetically. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -order-by-type = true -``` - ---- - -#### [`relative-imports-order`](#relative-imports-order) - -Whether to place "closer" imports (fewer `.` characters, most local) -before "further" imports (more `.` characters, least local), or vice -versa. - -The default ("furthest-to-closest") is equivalent to isort's -`reverse-relative` default (`reverse-relative = false`); setting -this to "closest-to-furthest" is equivalent to isort's `reverse-relative -= true`. - -**Default value**: `furthest-to-closest` - -**Type**: `"furthest-to-closest" | "closest-to-furthest"` - -**Example usage**: - -```toml -[tool.ruff.isort] -relative-imports-order = "closest-to-furthest" -``` - ---- - -#### [`required-imports`](#required-imports) - -Add the specified import line to all files. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -required-imports = ["from __future__ import annotations"] -``` - ---- - -#### [`single-line-exclusions`](#single-line-exclusions) - -One or more modules to exclude from the single line rule. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -single-line-exclusions = ["os", "json"] -``` - ---- - -#### [`split-on-trailing-comma`](#split-on-trailing-comma) - -If a comma is placed after the last member in a multi-line import, then -the imports will never be folded into one line. - -See isort's [`split-on-trailing-comma`](https://pycqa.github.io/isort/docs/configuration/options.html#split-on-trailing-comma) option. - -**Default value**: `true` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.isort] -split-on-trailing-comma = false -``` - ---- - -#### [`variables`](#variables) - -An override list of tokens to always recognize as a var -for `order-by-type` regardless of casing. - -**Default value**: `[]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.isort] -variables = ["VAR"] -``` - ---- - -### `mccabe` - -#### [`max-complexity`](#max-complexity) - -The maximum McCabe complexity to allow before triggering `C901` errors. - -**Default value**: `10` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.mccabe] -# Flag errors (`C901`) whenever the complexity level exceeds 5. -max-complexity = 5 -``` - ---- - -### `pep8-naming` - -#### [`classmethod-decorators`](#classmethod-decorators) - -A list of decorators that, when applied to a method, indicate that the -method should be treated as a class method. For example, Ruff will -expect that any method decorated by a decorator in this list takes a -`cls` argument as its first argument. - -**Default value**: `["classmethod"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.pep8-naming] -# Allow Pydantic's `@validator` decorator to trigger class method treatment. -classmethod-decorators = ["classmethod", "pydantic.validator"] -``` - ---- - -#### [`ignore-names`](#ignore-names) - -A list of names to ignore when considering `pep8-naming` violations. - -**Default value**: `["setUp", "tearDown", "setUpClass", "tearDownClass", "setUpModule", "tearDownModule", "asyncSetUp", "asyncTearDown", "setUpTestData", "failureException", "longMessage", "maxDiff"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.pep8-naming] -ignore-names = ["callMethod"] -``` - ---- - -#### [`staticmethod-decorators`](#staticmethod-decorators) - -A list of decorators that, when applied to a method, indicate that the -method should be treated as a static method. For example, Ruff will -expect that any method decorated by a decorator in this list has no -`self` or `cls` argument. - -**Default value**: `["staticmethod"]` - -**Type**: `list[str]` - -**Example usage**: - -```toml -[tool.ruff.pep8-naming] -# Allow a shorthand alias, `@stcmthd`, to trigger static method treatment. -staticmethod-decorators = ["staticmethod", "stcmthd"] -``` - ---- - -### `pycodestyle` - -#### [`ignore-overlong-task-comments`](#ignore-overlong-task-comments) - -Whether line-length violations (`E501`) should be triggered for -comments starting with `task-tags` (by default: ["TODO", "FIXME", -and "XXX"]). - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.pycodestyle] -ignore-overlong-task-comments = true -``` - ---- - -#### [`max-doc-length`](#max-doc-length) - -The maximum line length to allow for line-length violations within -documentation (`W505`), including standalone comments. - -**Default value**: `None` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.pycodestyle] -max-doc-length = 88 -``` - ---- - -### `pydocstyle` - -#### [`convention`](#convention) - -Whether to use Google-style or NumPy-style conventions or the PEP257 -defaults when analyzing docstring sections. - -**Default value**: `None` - -**Type**: `"google" | "numpy" | "pep257"` - -**Example usage**: - -```toml -[tool.ruff.pydocstyle] -# Use Google-style docstrings. -convention = "google" -``` - ---- - -### `pylint` - -#### [`allow-magic-value-types`](#allow-magic-value-types) - -Constant types to ignore when used as "magic values" (see: `PLR2004`). - -**Default value**: `["str", "bytes"]` - -**Type**: `list["str" | "bytes" | "complex" | "float" | "int" | "tuple"]` - -**Example usage**: - -```toml -[tool.ruff.pylint] -allow-magic-value-types = ["int"] -``` - ---- - -#### [`max-args`](#max-args) - -Maximum number of arguments allowed for a function or method definition -(see: `PLR0913`). - -**Default value**: `5` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.pylint] -max-args = 5 -``` - ---- - -#### [`max-branches`](#max-branches) - -Maximum number of branches allowed for a function or method body (see: -`PLR0912`). - -**Default value**: `12` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.pylint] -max-branches = 12 -``` - ---- - -#### [`max-returns`](#max-returns) - -Maximum number of return statements allowed for a function or method -body (see `PLR0911`) - -**Default value**: `6` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.pylint] -max-returns = 6 -``` - ---- - -#### [`max-statements`](#max-statements) - -Maximum number of statements allowed for a function or method body (see: -`PLR0915`). - -**Default value**: `50` - -**Type**: `int` - -**Example usage**: - -```toml -[tool.ruff.pylint] -max-statements = 50 -``` - ---- - -### `pyupgrade` - -#### [`keep-runtime-typing`](#keep-runtime-typing) - -Whether to avoid PEP 585 (`List[int]` -> `list[int]`) and PEP 604 -(`Optional[str]` -> `str | None`) rewrites even if a file imports `from -__future__ import annotations`. Note that this setting is only -applicable when the target Python version is below 3.9 and 3.10 -respectively, and enabling it is equivalent to disabling -`use-pep585-annotation` (`UP006`) and `use-pep604-annotation` -(`UP007`) entirely. - -**Default value**: `false` - -**Type**: `bool` - -**Example usage**: - -```toml -[tool.ruff.pyupgrade] -# Preserve types, even if a file imports `from __future__ import annotations`. -keep-runtime-typing = true -``` - ---- - - - - +See the [list of all options](https://beta.ruff.rs/docs/settings/). diff --git a/crates/ruff_dev/src/generate_all.rs b/crates/ruff_dev/src/generate_all.rs index 40d93fd81a..25c779e7a0 100644 --- a/crates/ruff_dev/src/generate_all.rs +++ b/crates/ruff_dev/src/generate_all.rs @@ -2,7 +2,7 @@ use anyhow::Result; -use crate::{generate_cli_help, generate_docs, generate_json_schema, generate_options}; +use crate::{generate_cli_help, generate_docs, generate_json_schema}; #[derive(clap::Args)] pub struct Args { @@ -18,9 +18,6 @@ pub fn main(args: &Args) -> Result<()> { generate_json_schema::main(&generate_json_schema::Args { dry_run: args.dry_run, })?; - generate_options::main(&generate_options::Args { - dry_run: args.dry_run, - })?; generate_cli_help::main(&generate_cli_help::Args { dry_run: args.dry_run, })?; diff --git a/crates/ruff_dev/src/generate_options.rs b/crates/ruff_dev/src/generate_options.rs index 91a6553084..f4e285c8df 100644 --- a/crates/ruff_dev/src/generate_options.rs +++ b/crates/ruff_dev/src/generate_options.rs @@ -1,23 +1,8 @@ //! Generate a Markdown-compatible listing of configuration options. -#![allow(clippy::print_stdout, clippy::print_stderr)] - -use anyhow::Result; use itertools::Itertools; use ruff::settings::options::Options; use ruff::settings::options_base::{ConfigurationOptions, OptionEntry, OptionField}; -use crate::utils::replace_readme_section; - -const BEGIN_PRAGMA: &str = "\n"; -const END_PRAGMA: &str = ""; - -#[derive(clap::Args)] -pub struct Args { - /// Write the generated table to stdout (rather than to `README.md`). - #[arg(long)] - pub(crate) dry_run: bool, -} - fn emit_field(output: &mut String, name: &str, field: &OptionField, group_name: Option<&str>) { output.push_str(&format!("#### [`{0}`](#{0})\n", name)); output.push('\n'); @@ -39,7 +24,7 @@ fn emit_field(output: &mut String, name: &str, field: &OptionField, group_name: output.push('\n'); } -pub fn main(args: &Args) -> Result<()> { +pub fn generate() -> String { let mut output: String = "### Top-level\n\n".into(); let mut sorted_options = Options::get_available_options(); @@ -64,11 +49,5 @@ pub fn main(args: &Args) -> Result<()> { } } - if args.dry_run { - print!("{output}"); - } else { - replace_readme_section(&output, BEGIN_PRAGMA, END_PRAGMA)?; - } - - Ok(()) + output } diff --git a/crates/ruff_dev/src/main.rs b/crates/ruff_dev/src/main.rs index bd824b4e95..8fd7fb7ad6 100644 --- a/crates/ruff_dev/src/main.rs +++ b/crates/ruff_dev/src/main.rs @@ -36,7 +36,7 @@ enum Command { /// Generate a Markdown-compatible table of supported lint rules. GenerateRulesTable, /// Generate a Markdown-compatible listing of configuration options. - GenerateOptions(generate_options::Args), + GenerateOptions, /// Generate CLI help. GenerateCliHelp(generate_cli_help::Args), /// Generate Markdown docs. @@ -58,7 +58,7 @@ fn main() -> Result<()> { Command::GenerateAll(args) => generate_all::main(args)?, Command::GenerateJSONSchema(args) => generate_json_schema::main(args)?, Command::GenerateRulesTable => println!("{}", generate_rules_table::generate()), - Command::GenerateOptions(args) => generate_options::main(args)?, + Command::GenerateOptions => println!("{}", generate_options::generate()), Command::GenerateCliHelp(args) => generate_cli_help::main(args)?, Command::GenerateDocs(args) => generate_docs::main(args)?, Command::PrintAST(args) => print_ast::main(args)?, diff --git a/scripts/generate_mkdocs.py b/scripts/generate_mkdocs.py index 87ff807a18..3922a0b7d5 100644 --- a/scripts/generate_mkdocs.py +++ b/scripts/generate_mkdocs.py @@ -49,6 +49,10 @@ def main() -> None: # Split the README.md into sections. for title, filename in SECTIONS: with Path(f"docs/{filename}").open("w+") as f: + if filename == "settings.md": + f.write(subprocess.check_output(["cargo", "dev", "generate-options"], encoding="utf-8")) + continue + block = content.split(f"") if len(block) != 2: msg = f"Section {title} not found in README.md"