From ae2ac905dc047c2824d76410f9310e8210623781 Mon Sep 17 00:00:00 2001 From: Charlie Marsh Date: Sun, 27 Nov 2022 23:50:24 -0500 Subject: [PATCH] Document all top-level configuration options (#934) --- README.md | 315 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 301 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index f2c5d7259732d..6ae998b91b276 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,7 @@ of [Conda](https://docs.conda.io/en/latest/): 1. [Development](#development) 1. [Releases](#releases) 1. [Benchmarks](#benchmarks) +1. [Reference](#reference) 1. [License](#license) 1. [Contributing](#contributing) @@ -143,8 +144,10 @@ _Note: prior to `v0.0.86`, `ruff-pre-commit` used `lint` (rather than `ruff`) as ## Configuration -Ruff is configurable both via `pyproject.toml` and the command line. If left unspecified, the -default configuration is equivalent to: +Ruff is configurable both via `pyproject.toml` and the command line. For a full list of configurable +options, see the [API reference](#reference). + +If left unspecified, the default configuration is equivalent to: ```toml [tool.ruff] @@ -222,7 +225,9 @@ select = ["E", "F", "Q"] docstring-quotes = "double" ``` -Alternatively, common configuration settings can be provided via the command-line: +For a full list of configurable options, see the [API reference](#reference). + +Some common configuration settings can be provided via the command-line: ```shell ruff path/to/code/ --select F401 --select F403 @@ -299,17 +304,6 @@ Options: Print version information ``` -### Excluding files - -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`). - ### Ignoring errors To omit a lint check entirely, add it to the "ignore" list via `--ignore` or `--extend-ignore`, @@ -1192,6 +1186,299 @@ Summary 389.73 ± 9.92 times faster than 'flake8 resources/test/cpython' ``` +## Reference + +### Options + +#### [`dummy_variable_rgx`](#dummy_variable_rgx) + +A regular expression used to identify "dummy" variables, or those which should be ignored when evaluating +(e.g.) unused-variable checks. + +**Default value**: `"^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"` (matches `_`, `__`, and `_var`, but not `_var_`) + +**Type**: `Regex` + +**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`). + +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", ".ruff_cache", ".svn", ".tox", ".venv", "__pypackages__", "_build", "buck-out", "build", "dist", "node_modules", "venv"]` + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +exclude = [".venv"] +```` + +--- + +#### [`extend_exclude`](#extend_exclude) + +A list of file patterns to omit from linting, in addition to those specified by `exclude`. + +**Default value**: `[]` + +**Type**: `Vec` + +**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"] +```` + +--- + +#### [`ignore`](#ignore) + +A list of check code prefixes to ignore. Prefixes can specify exact checks (like `F841`), entire +categories (like `F`), or anything in between. + +When breaking ties between enabled and disabled checks (via `select` and `ignore`, respectively), +more specific prefixes override less specific prefixes. + +**Default value**: `[]` + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +# Skip unused variable checks (`F841`). +ignore = ["F841"] +``` + +--- + +#### [`extend_ignore`](#extend_ignore) + +A list of check code prefixes to ignore, in addition to those specified by `ignore`. + +**Default value**: `[]` + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +# Skip unused variable checks (`F841`). +extend-ignore = ["F841"] +``` + +--- + +#### [`select`](#select) + +A list of check code prefixes to enable. Prefixes can specify exact checks (like `F841`), entire +categories (like `F`), or anything in between. + +When breaking ties between enabled and disabled checks (via `select` and `ignore`, respectively), +more specific prefixes override less specific prefixes. + +**Default value**: `["E", "F"]` + +**Type**: `Vec` + +**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"] +``` + +--- + +#### [`extend_select`](#extend_select) + +A list of check code prefixes to enable, in addition to those specified by `select`. + +**Default value**: `[]` + +**Type**: `Vec` + +**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"] +``` + +--- + +#### [`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 +``` + +--- + +#### [`fixable`](#fixable) + +A list of check code prefixes to consider autofix-able. + +**Default value**: `["A", "ANN", "B", "BLE", "C", "D", "E", "F", "FBT", "I", "M", "N", "Q", "RUF", "S", "T", "U", "W", "YTT"]` + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +# Only allow autofix behavior for `E` and `F` checks. +fixable = ["E", "F"] +``` + +--- + +#### [`unfixable`](#unfixable) + +A list of check code prefixes to consider un-autofix-able. + +**Default value**: `[]` + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +# Disable autofix for unused imports (`F401`). +unfixable = ["F401"] +``` + +--- + +#### [`line_length`](#line_length) + +The line length to use when enforcing long-lines violations (like E501). + +**Default value**: `88` + +**Type**: `usize` + +**Example usage**: + +```toml +[tool.ruff] +# Allow lines to be as long as 120 characters. +line-length = 120 +``` + +--- + +#### [`per_file_ignores`](#per_file_ignores) + +Description. + +**Default value**: + +**Type**: `Vec` + +**Example usage**: + +```toml +[tool.ruff] +``` + +--- + +#### [`show_source`](#show_source) + +Whether to show source code snippets when reporting lint error 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. + +**Default value**: `["."]` + +**Type**: `Vec` + +**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**: `PythonVersion` + +**Example usage**: + +```toml +[tool.ruff] +# Always generate Python 3.7-compatible code. +target-version = "py37" +``` + ## License MIT