mirror of
https://github.com/astral-sh/ruff.git
synced 2026-10-28 10:45:37 +08:00
Clarify documentation and correct stale guidance (#29374)
The documentation has stale configuration guidance and a few examples that do not work as written. Clarify the prose and correct editor configuration precedence, user-level configuration discovery, rule descriptions, and the tutorial and configuration examples. --------- Co-authored-by: Zanie Blue <zanie@openai.com>
This commit is contained in:
zaniebotandZanie Blue authored and GitHub committed
1 parent
61888b1cc6
commit
c23d6967c9
15 files changed
+87
-83
No files matched your search
+7
-8
@@ -434,7 +434,7 @@ screenshots or recordings of your change in action.
|
||||
After opening the PR, an ecosystem report will be run as part of CI. This shows
|
||||
a diff of linter and formatter behavior before and after the changes in your PR.
|
||||
Going through these changes and reporting your findings in the PR summary or an
|
||||
additional comment help us to review your PR more efficiently. It's also a great
|
||||
additional comment helps us review your PR more efficiently. It's also a great
|
||||
way to find new test cases to incorporate into your PR if you identify any
|
||||
issues.
|
||||
|
||||
@@ -472,12 +472,11 @@ The documentation should then be available locally at
|
||||
|
||||
## Release Process
|
||||
|
||||
As of now, Ruff has an ad hoc release process: releases are cut with high frequency via GitHub
|
||||
As of now, Ruff has an ad hoc release process: releases are cut frequently via GitHub
|
||||
Actions, which automatically generates the appropriate wheels across architectures and publishes
|
||||
them to [PyPI](https://pypi.org/project/ruff/).
|
||||
|
||||
Ruff follows the [semver](https://semver.org/) versioning standard. However, as pre-1.0 software,
|
||||
even patch releases may contain [non-backwards-compatible changes](https://semver.org/#spec-item-4).
|
||||
See Ruff's [versioning policy](https://docs.astral.sh/ruff/versioning/).
|
||||
|
||||
### Installing tools
|
||||
|
||||
@@ -506,7 +505,7 @@ review and remaining preparation steps below. To prepare the release locally, st
|
||||
|
||||
1. The changelog should then be editorialized for consistency
|
||||
|
||||
- Often labels will be missing from pull requests they will need to be manually organized into the proper section
|
||||
- Pull requests often lack labels and will need to be manually organized into the proper section
|
||||
- Changes should be edited to be user-facing descriptions, avoiding internal details
|
||||
- Square brackets (eg, `[ruff]` project name) will be automatically escaped by `prek`
|
||||
|
||||
@@ -1110,8 +1109,8 @@ The project root does not have a significant impact beyond that all relative pat
|
||||
configuration file are resolved relative to the project root.
|
||||
|
||||
For example, to indicate that `bar` above is a namespace package (it isn't, but let's run with it),
|
||||
the `pyproject.toml` would list `namespace-packages = ["./src/bar"]`, which would resolve
|
||||
to `my_project/src/bar`.
|
||||
the `pyproject.toml` would list `namespace-packages = ["./src/foo/bar"]`, which would resolve
|
||||
to `my_project/src/foo/bar`.
|
||||
|
||||
The same logic applies when providing a configuration file via `--config`. In that case, the
|
||||
_current working directory_ is used as the project root, and so all paths in that configuration file
|
||||
@@ -1180,5 +1179,5 @@ There are three ways in which an import can be categorized as "first-party":
|
||||
the `src` setting and, for each directory, check for the existence of a subdirectory `foo` or a
|
||||
file `foo.py`.
|
||||
|
||||
By default, `src` is set to the project root, along with `"src"` subdirectory in the project root.
|
||||
By default, `src` is set to the project root, along with the `"src"` subdirectory in the project root.
|
||||
This ensures that Ruff supports both flat and "src" layouts out of the box.
|
||||
@@ -46,7 +46,7 @@ Ruff can be used to replace [Flake8](https://pypi.org/project/flake8/) (plus doz
|
||||
[autoflake](https://pypi.org/project/autoflake/), and more, all while executing tens or hundreds of
|
||||
times faster than any individual tool.
|
||||
|
||||
Ruff is extremely actively developed and used in major open-source projects like:
|
||||
Ruff is actively developed and used in major open-source projects like:
|
||||
|
||||
- [Apache Airflow](https://github.com/apache/airflow)
|
||||
- [Apache Superset](https://github.com/apache/superset)
|
||||
@@ -381,7 +381,7 @@ quality tools, including:
|
||||
- [tryceratops](https://pypi.org/project/tryceratops/)
|
||||
- [yesqa](https://pypi.org/project/yesqa/)
|
||||
|
||||
For a complete enumeration of the supported rules, see [_Rules_](https://docs.astral.sh/ruff/rules/).
|
||||
For the complete list of supported rules, see [_Rules_](https://docs.astral.sh/ruff/rules/).
|
||||
|
||||
## Contributing<a id="contributing"></a>
|
||||
|
||||
|
||||
+12
-10
@@ -251,10 +251,9 @@ For a complete enumeration of the available configuration options, see [_Setting
|
||||
## Config file discovery
|
||||
|
||||
Similar to [ESLint](https://eslint.org/docs/latest/use/configure/configuration-files#cascading-configuration-objects),
|
||||
Ruff supports hierarchical configuration, such that the "closest" config file in the
|
||||
directory hierarchy is used for every individual file, with all paths in the config file
|
||||
(e.g., `exclude` globs, `src` paths) being resolved relative to the directory containing that
|
||||
config file.
|
||||
Ruff supports hierarchical configuration. For each file, Ruff uses the "closest" config file in the
|
||||
directory hierarchy. Paths in that config file (e.g., `exclude` globs and `src` paths) are resolved
|
||||
relative to the directory containing it.
|
||||
|
||||
There are a few exceptions to these rules:
|
||||
|
||||
@@ -264,9 +263,11 @@ There are a few exceptions to these rules:
|
||||
analyzed files, and any relative paths in that configuration file (like `exclude` globs or
|
||||
`src` paths) are resolved relative to the _current_ working directory.
|
||||
1. If no config file is found in the filesystem hierarchy, Ruff will fall back to using
|
||||
a default configuration. If a user-specific configuration file exists
|
||||
at `${config_dir}/ruff/pyproject.toml`, that file will be used instead of the default
|
||||
configuration, with `${config_dir}` being determined via [`etcetera`'s base strategy](https://docs.rs/etcetera/latest/etcetera/#native-strategy),
|
||||
a default configuration. If a user-specific configuration file exists at
|
||||
`${config_dir}/ruff/.ruff.toml`, `${config_dir}/ruff/ruff.toml`, or
|
||||
`${config_dir}/ruff/pyproject.toml` (checked in that order), the first such file will be used
|
||||
instead of the default configuration, with `${config_dir}` being determined via
|
||||
[`etcetera`'s base strategy](https://docs.rs/etcetera/latest/etcetera/#native-strategy),
|
||||
and all relative paths being again resolved relative to the _current working directory_.
|
||||
1. Any config-file-supported settings that are provided on the command-line (e.g., via
|
||||
`--select`) will override the settings in _every_ resolved configuration file.
|
||||
@@ -347,7 +348,8 @@ For example, without `force-exclude` enabled, `ruff check /path/to/excluded/file
|
||||
|
||||
### Default inclusions
|
||||
|
||||
By default, Ruff will discover files matching `*.py`, `*.pyi`, `*.ipynb`, or `pyproject.toml`.
|
||||
By default, Ruff will discover files matching `*.py`, `*.pyi`, `*.ipynb`, `*.md`, `pyproject.toml`,
|
||||
`ruff.toml`, or `.ruff.toml`.
|
||||
In [preview](preview.md) mode, Ruff will also discover `*.pyw` by default.
|
||||
|
||||
To lint or format files with additional file extensions, use the [`extend-include`](settings.md#extend-include) setting.
|
||||
@@ -446,7 +448,7 @@ using the [`per-file-ignores`](settings.md#per-file-ignores) setting:
|
||||
Some rules have different behavior when applied to Jupyter Notebook files. For
|
||||
example, when applied to `.py` files the
|
||||
[`module-import-not-at-top-of-file` (`E402`)](rules/module-import-not-at-top-of-file.md)
|
||||
rule detect imports at the top of a file, but for notebooks it detects imports at the top of a
|
||||
rule detects imports that are not at the top of a file. In notebooks, it applies that check to each
|
||||
**cell**. For a given rule, the rule's documentation will always specify if it has different
|
||||
behavior when applied to Jupyter Notebook files.
|
||||
|
||||
@@ -520,7 +522,7 @@ Ruff supports reading command-line arguments from a file, which is especially us
|
||||
$ ruff check @path/to/args.txt
|
||||
```
|
||||
|
||||
The arguments in the file must all be written on their own line. For example, `args.txt` might contain:
|
||||
Each argument in the file must be written on its own line. For example, `args.txt` might contain:
|
||||
|
||||
```text
|
||||
--select
|
||||
|
||||
@@ -4,7 +4,7 @@ This section provides a detailed overview of the features provided by the Ruff L
|
||||
|
||||
## Diagnostic Highlighting
|
||||
|
||||
Provide diagnostics for your Python code in real-time.
|
||||
The server provides diagnostics for your Python code in real time.
|
||||
|
||||
<img
|
||||
src="https://astral.sh/static/GIF/v0.4.5/violation_hx.gif"
|
||||
@@ -27,8 +27,7 @@ alt="Editing a `pyproject.toml` configuration file in VS Code"
|
||||
|
||||
## Formatting
|
||||
|
||||
Provide code formatting for your Python code. The server can format an entire document or a specific
|
||||
range of lines.
|
||||
The server can format an entire Python document or a specific range of lines.
|
||||
|
||||
The VS Code extension provides the `Ruff: Format Document` command to format an entire document.
|
||||
In VS Code, the range formatting can be triggered by selecting a range of lines, right-clicking, and
|
||||
@@ -120,8 +119,8 @@ how fix safety works.
|
||||
|
||||
## Hover
|
||||
|
||||
The server can provide the rule documentation when focusing over a NoQA code in the comment.
|
||||
Focusing is usually hovering with a mouse, but can also be triggered with a shortcut.
|
||||
The server can provide rule documentation when you focus on a NoQA code in a comment. You can
|
||||
usually do this by hovering with a mouse or using a keyboard shortcut.
|
||||
|
||||
<img
|
||||
src="https://astral.sh/static/GIF/v0.4.5/hover_vscode.gif"
|
||||
|
||||
@@ -13,10 +13,9 @@ backend built directly into Ruff, and a direct replacement for [`ruff-lsp`](http
|
||||
our previous language server. You can read more about `ruff server` in the
|
||||
[`v0.4.5` blog post](https://astral.sh/blog/ruff-v0.4.5).
|
||||
|
||||
The server supports surfacing Ruff diagnostics, providing Code Actions to fix them, and
|
||||
formatting the code using Ruff's built-in formatter. Currently, the server is intended to be used
|
||||
alongside another Python Language Server in order to support features like navigation and
|
||||
autocompletion.
|
||||
The server provides Ruff diagnostics, Code Actions to fix them, and formatting using Ruff's built-in
|
||||
formatter. For features like navigation and autocompletion, we recommend using the
|
||||
[ty language server](https://docs.astral.sh/ty/features/language-server/) alongside Ruff.
|
||||
|
||||
The Ruff Language Server was available first in Ruff [v0.4.5](https://astral.sh/blog/ruff-v0.4.5)
|
||||
in beta and stabilized in Ruff [v0.5.3](https://github.com/astral-sh/ruff/releases/tag/0.5.3).
|
||||
@@ -1,10 +1,9 @@
|
||||
# Migrating from `ruff-lsp`
|
||||
|
||||
[`ruff-lsp`][ruff-lsp] is the [Language Server Protocol] implementation for Ruff to power the editor
|
||||
integrations. It is written in Python and is a separate package from Ruff itself. The **native
|
||||
server**, however, is the [Language Server Protocol] implementation which is **written in Rust** and
|
||||
is available under the `ruff server` command. This guide is intended to help users migrate from
|
||||
[`ruff-lsp`][ruff-lsp] to the native server.
|
||||
Ruff's previous [Language Server Protocol] implementation, [`ruff-lsp`][ruff-lsp], was written in
|
||||
Python and distributed separately from Ruff. It is no longer supported. This guide explains how to
|
||||
migrate to Ruff's **native server**, which is written in Rust and available through the
|
||||
`ruff server` command.
|
||||
|
||||
!!! note
|
||||
|
||||
@@ -76,8 +75,8 @@ If you've been providing a configuration file as shown below:
|
||||
}
|
||||
```
|
||||
|
||||
You can migrate to the new server by using the [`configuration`](settings.md#configuration) setting
|
||||
like below which will apply the configuration to both the linter and the formatter:
|
||||
To migrate to the new server, use the [`configuration`](settings.md#configuration) setting to apply
|
||||
the configuration to both the linter and the formatter:
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
+13
-15
@@ -1,11 +1,9 @@
|
||||
# Settings
|
||||
|
||||
The Ruff Language Server provides a set of configuration options to customize its behavior
|
||||
along with the ability to use an existing `pyproject.toml` or `ruff.toml` file to configure the
|
||||
linter and formatter. This is done by providing these settings while initializing the server.
|
||||
VS Code provides a UI to configure these settings, while other editors may require manual
|
||||
configuration. The [setup](./setup.md) section provides instructions on where to place these settings
|
||||
as per the editor.
|
||||
The Ruff Language Server accepts settings to customize its behavior and can use an existing
|
||||
`pyproject.toml` or `ruff.toml` file to configure the linter and formatter. Provide these settings
|
||||
when initializing the server. VS Code provides a UI for them, while other editors may require manual
|
||||
configuration. The [setup](./setup.md) section explains where to place the settings for each editor.
|
||||
|
||||
## Top-level
|
||||
|
||||
@@ -31,8 +29,8 @@ editor-provided configuration (`configuration`) and a project level configuratio
|
||||
|
||||
#### Resolution order {: #configuration_resolution_order }
|
||||
|
||||
In an editor, Ruff supports three sources of configuration, prioritized as follows (from highest to
|
||||
lowest):
|
||||
With the default `"editorFirst"` configuration preference, Ruff prioritizes the three sources of
|
||||
configuration as follows (from highest to lowest):
|
||||
|
||||
1. **Specific settings:** Individual settings like [`lineLength`](#linelength) or
|
||||
[`lint.select`](#select) defined in the editor
|
||||
@@ -47,7 +45,7 @@ For example, if the line length is specified in all three sources, Ruff will use
|
||||
|
||||
**Default value**: `null`
|
||||
|
||||
**Type**: `string`
|
||||
**Type**: `string` (path to a configuration file) or `object` (inline configuration)
|
||||
|
||||
**Example usage**:
|
||||
|
||||
@@ -102,7 +100,7 @@ _Using inline configuration:_
|
||||
"flake8-tidy-imports": {
|
||||
"banned-api": {
|
||||
"typing.TypedDict": {
|
||||
"msg": "Use `typing_extensions.TypedDict` instead",
|
||||
"msg": "Use `typing_extensions.TypedDict` instead"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -178,7 +176,7 @@ The strategy to use when resolving settings across VS Code and the filesystem. B
|
||||
configuration is prioritized over `ruff.toml` and `pyproject.toml` files.
|
||||
|
||||
- `"editorFirst"`: Editor settings take priority over configuration files present in the workspace.
|
||||
- `"filesystemFirst"`: Configuration files present in the workspace takes priority over editor
|
||||
- `"filesystemFirst"`: Configuration files present in the workspace take priority over editor
|
||||
settings.
|
||||
- `"editorOnly"`: Ignore configuration files entirely i.e., only use editor settings.
|
||||
|
||||
@@ -249,7 +247,7 @@ documentation](https://docs.astral.sh/ruff/settings/#exclude) for more details.
|
||||
vim.lsp.config('ruff', {
|
||||
init_options = {
|
||||
settings = {
|
||||
exclude = ["**/tests/**"]
|
||||
exclude = { "**/tests/**" }
|
||||
}
|
||||
}
|
||||
})
|
||||
@@ -973,7 +971,7 @@ Whether to enable Ruff's preview mode when formatting.
|
||||
|
||||
### `backend` {: #format_backend }
|
||||
|
||||
The backend to use for formatting files. Following options are available:
|
||||
The backend to use for formatting files. The following options are available:
|
||||
|
||||
- `"internal"`: Use the built-in Ruff formatter
|
||||
- `"uv"`: Use uv for formatting (requires uv >= 0.8.13)
|
||||
@@ -1114,9 +1112,9 @@ automatically decide between the two based on the Ruff version and extension set
|
||||
|
||||
### `path`
|
||||
|
||||
A list of path to `ruff` executables.
|
||||
A list of paths to `ruff` executables.
|
||||
|
||||
The first executable in the list which is exists is used. This setting takes precedence over the
|
||||
The first executable in the list that exists is used. This setting takes precedence over the
|
||||
[`ruff.importStrategy`](#importstrategy) setting.
|
||||
|
||||
**Default value**: `[]`
|
||||
|
||||
@@ -10,7 +10,7 @@ the [migration guide](./migration.md) for more.
|
||||
!!! note
|
||||
|
||||
The setup instructions provided below are on a best-effort basis. If you encounter any issues
|
||||
while setting up the Ruff in an editor, please [open an issue](https://github.com/astral-sh/ruff/issues/new)
|
||||
while setting up Ruff in an editor, please [open an issue](https://github.com/astral-sh/ruff/issues/new)
|
||||
for assistance and help in improving this documentation.
|
||||
|
||||
## VS Code
|
||||
@@ -25,11 +25,11 @@ For more documentation on the Ruff extension, refer to the
|
||||
|
||||
## Neovim
|
||||
|
||||
The Ruff language server can be setup in Neovim using the built-in LSP client either via
|
||||
The Ruff language server can be set up in Neovim using the built-in LSP client either via
|
||||
[`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>) (Neovim 0.11+) or the
|
||||
[`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig) plugin (Neovim 0.10 and earlier).
|
||||
|
||||
To setup using [`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>), you can
|
||||
To set up using [`vim.lsp.config`](<https://neovim.io/doc/user/lsp.html#vim.lsp.config()>), you can
|
||||
either use the [default configuration provided in
|
||||
`nvim-lspconfig`](https://github.com/neovim/nvim-lspconfig/blob/master/lsp/ruff.lua) or configure
|
||||
the server without any external dependencies.
|
||||
@@ -433,7 +433,7 @@ IntelliJ Marketplace (maintained by [@koxudaxi](https://github.com/koxudaxi)).
|
||||
|
||||
## Emacs
|
||||
|
||||
Ruff can be utilized as a language server via [`Eglot`](https://github.com/joaotavora/eglot), which is in Emacs's core.
|
||||
Ruff can be used as a language server via [`Eglot`](https://github.com/joaotavora/eglot), which is in Emacs's core.
|
||||
To enable Ruff with automatic formatting on save, use the following configuration:
|
||||
|
||||
```elisp
|
||||
|
||||
+13
-12
@@ -11,8 +11,10 @@ such, will defer implementing stylistic rules that are obviated by automated for
|
||||
Note that Ruff's linter and Black treat line-length enforcement a little differently. Black, like
|
||||
Ruff's formatter, makes a best-effort attempt to adhere to the
|
||||
[`line-length`](settings.md#line-length), but avoids automatic line-wrapping in some cases (e.g.,
|
||||
within comments). Ruff, on the other hand, will flag [`line-too-long`](rules/line-too-long.md)
|
||||
(`E501`) for any line that exceeds the [`line-length`](settings.md#line-length) setting. As such, if
|
||||
within comments). Ruff's [`line-too-long`](rules/line-too-long.md) (`E501`) rule checks lines against
|
||||
[`line-length`](settings.md#line-length), subject to the rule's documented exceptions. You can
|
||||
override this limit for the linter with
|
||||
[`lint.pycodestyle.max-line-length`](settings.md#lint_pycodestyle_max-line-length). As such, if
|
||||
[`line-too-long`](rules/line-too-long.md) (`E501`) is enabled, Ruff can still trigger line-length
|
||||
violations even when Black or `ruff format` is enabled.
|
||||
|
||||
@@ -65,7 +67,7 @@ natively, including:
|
||||
- [flake8-gettext](https://pypi.org/project/flake8-gettext/)
|
||||
- [flake8-implicit-str-concat](https://pypi.org/project/flake8-implicit-str-concat/)
|
||||
- [flake8-import-conventions](https://pypi.org/project/flake8-import-conventions/)
|
||||
- [flake8-logging](https://pypi.org/project/flake8-logging-format/)
|
||||
- [flake8-logging](https://pypi.org/project/flake8-logging/)
|
||||
- [flake8-logging-format](https://pypi.org/project/flake8-logging-format/)
|
||||
- [flake8-no-pep420](https://pypi.org/project/flake8-no-pep420)
|
||||
- [flake8-pie](https://pypi.org/project/flake8-pie/)
|
||||
@@ -290,9 +292,8 @@ Like isort, Ruff's import sorting is compatible with Black.
|
||||
|
||||
## How does Ruff determine which of my imports are first-party, third-party, etc.?
|
||||
|
||||
Ruff accepts a `src` option that in your `pyproject.toml`, `ruff.toml`, or `.ruff.toml` file,
|
||||
specifies the directories that Ruff should consider when determining whether an import is
|
||||
first-party.
|
||||
The `src` option in your `pyproject.toml`, `ruff.toml`, or `.ruff.toml` file specifies the
|
||||
directories Ruff considers when determining whether an import is first-party.
|
||||
|
||||
For example, if you have a project with the following structure:
|
||||
|
||||
@@ -362,7 +363,7 @@ explicit, exclusive first-party source like so:
|
||||
|
||||
If your `pyproject.toml`, `ruff.toml`, or `.ruff.toml` extends another configuration file, Ruff
|
||||
will still use the directory containing your `pyproject.toml`, `ruff.toml`, or `.ruff.toml` file as
|
||||
the project root (as opposed to the directory of the file pointed to via the `extends` option).
|
||||
the project root (as opposed to the directory of the file pointed to via the `extend` option).
|
||||
|
||||
For example, if you add a configuration file to the `tests` directory in the above example, you'll
|
||||
want to explicitly set the `src` option in the extended configuration file:
|
||||
@@ -460,8 +461,8 @@ Found 3 errors.
|
||||
|
||||
## Does Ruff support NumPy- or Google-style docstrings?
|
||||
|
||||
Yes! To enforce a docstring convention, add a [`convention`](settings.md#lint_pydocstyle_convention)
|
||||
setting following to your configuration file:
|
||||
Yes! To enforce a docstring convention, add the following [`convention`](settings.md#lint_pydocstyle_convention)
|
||||
setting to your configuration file:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
@@ -588,8 +589,8 @@ Ruff doesn't currently support INI files, like `setup.cfg` or `tox.ini`.
|
||||
|
||||
## How can I change Ruff's default configuration?
|
||||
|
||||
When no configuration file is found, Ruff will look for a user-specific `ruff.toml` file as a
|
||||
last resort. This behavior is similar to Flake8's `~/.config/flake8`.
|
||||
When no project configuration file is found, Ruff looks for a user-specific `.ruff.toml`,
|
||||
`ruff.toml`, or `pyproject.toml`, in that order. The examples below use `ruff.toml`.
|
||||
|
||||
On macOS and Linux, Ruff expects that file to be located at `~/.config/ruff/ruff.toml`,
|
||||
and respects the `XDG_CONFIG_HOME` specification.
|
||||
@@ -631,7 +632,7 @@ Ruff does not support `source.organizeImports` and `source.fixAll` code actions
|
||||
actions for the same such as `notebook.source.organizeImports` and `notebook.source.fixAll`
|
||||
respectively.
|
||||
|
||||
Ruff requires to have a full view of the notebook to provide accurate diagnostics and fixes. For
|
||||
Ruff requires a full view of the notebook to provide accurate diagnostics and fixes. For
|
||||
example, if you have a cell that imports a module and another cell that uses that module, Ruff
|
||||
needs to see both cells to mark the import as used. If Ruff were to only see one cell at a time,
|
||||
it would incorrectly mark the import as unused.
|
||||
|
||||
+3
-3
@@ -269,8 +269,8 @@ print( 'hello' )
|
||||
````
|
||||
|
||||
Any number of code blocks may be contained within a matching pair of `off` and
|
||||
`on` HTML comments, and any `off` comment *without* a matching `on` comment
|
||||
will implicitly cover the remaining portion of the document.
|
||||
`on` HTML comments. An `off` comment *without* a matching `on` comment covers
|
||||
the rest of the document.
|
||||
|
||||
The Ruff formatter will also recognize HTML comments from [blacken-docs][],
|
||||
`<!-- blacken-docs:off -->` and `<!-- blacken-docs:on -->`, which are equivalent
|
||||
@@ -661,7 +661,7 @@ while the stable formatting breaks _after_ the call or subscript.
|
||||
|
||||
## Sorting imports
|
||||
|
||||
Currently, the Ruff formatter does not sort imports. In order to both sort imports and format,
|
||||
Currently, the Ruff formatter does not sort imports. To sort imports and format,
|
||||
call the Ruff linter and then the formatter:
|
||||
|
||||
```shell
|
||||
|
||||
@@ -244,8 +244,8 @@ def test(max_history):
|
||||
|
||||
Black's unstable style applies the same formatting.
|
||||
|
||||
There are few rare cases where Ruff can't merge the implicitly concatenated strings automatically.
|
||||
In those cases, Ruff preserves if the implicit concatenated strings are formatted over multiple lines:
|
||||
In a few rare cases, Ruff can't merge implicitly concatenated strings automatically. In those
|
||||
cases, Ruff keeps the strings on multiple lines if they were written that way:
|
||||
|
||||
```python
|
||||
# Input
|
||||
@@ -346,7 +346,7 @@ Ruff will instead remove them:
|
||||
await [1, 2, 3]
|
||||
```
|
||||
|
||||
This is more consistent to the formatting of other awaited expressions: Ruff and Black both
|
||||
This is more consistent with the formatting of other awaited expressions: Ruff and Black both
|
||||
remove parentheses around, e.g., `await (1)`, only retaining them when syntactically required,
|
||||
as in, e.g., `await (x := 1)`.
|
||||
|
||||
|
||||
@@ -73,7 +73,8 @@ For example, to run `ruff check --select B ./src` using Ruff version `0.8.0`:
|
||||
|
||||
## GitLab CI/CD
|
||||
|
||||
You can add the following configuration to `.gitlab-ci.yml` to run a `ruff format` in parallel with a `ruff check` compatible with GitLab's codequality report.
|
||||
Add the following configuration to `.gitlab-ci.yml` to run `ruff format` in parallel with
|
||||
`ruff check`, which produces a report compatible with GitLab's code quality report.
|
||||
|
||||
```yaml
|
||||
.base_ruff:
|
||||
|
||||
+5
-5
@@ -26,8 +26,8 @@ For the full list of supported options, run `ruff check --help`.
|
||||
The set of enabled rules is controlled via the [`lint.select`](settings.md#lint_select),
|
||||
[`lint.extend-select`](settings.md#lint_extend-select), and [`lint.ignore`](settings.md#lint_ignore) settings.
|
||||
|
||||
Ruff's linter mirrors Flake8's rule code system, in which each rule code consists of a one-to-three
|
||||
letter prefix, followed by three digits (e.g., `F401`). The prefix indicates that "source" of the rule
|
||||
Ruff's linter uses Flake8-style rule codes: an alphabetic prefix followed by digits (e.g., `F401`).
|
||||
The prefix indicates the source of the rule
|
||||
(e.g., `F` for Pyflakes, `E` for pycodestyle, `ANN` for flake8-annotations).
|
||||
|
||||
Rule selectors like [`lint.select`](settings.md#lint_select) and [`lint.ignore`](settings.md#lint_ignore) accept either
|
||||
@@ -356,7 +356,7 @@ $ python -m timeit "head = next(iter(range(99999999)))"
|
||||
5000000 loops, best of 5: 70.8 nsec per loop
|
||||
```
|
||||
|
||||
However, when the collection is empty, this raised exception changes from an `IndexError` to `StopIteration`:
|
||||
However, when the collection is empty, the raised exception changes from an `IndexError` to `StopIteration`:
|
||||
|
||||
```console
|
||||
$ python -c 'list(range(0))[0]'
|
||||
@@ -620,7 +620,7 @@ def foo():
|
||||
foo()
|
||||
```
|
||||
|
||||
It is strongly suggested to use explicit range suppressions, in order to prevent
|
||||
We strongly suggest using explicit range suppressions to prevent
|
||||
accidental suppressions of violations, especially at global module scope.
|
||||
For this reason, a `RUF104` diagnostic will also be produced for any implicit range.
|
||||
If implicit range suppressions are desired, the `RUF104` rule can be disabled,
|
||||
@@ -679,7 +679,7 @@ line, at global module scope, and preferably near the top of the file:
|
||||
# ruff: file-ignore[F401, ARG001]
|
||||
```
|
||||
|
||||
The full-level suppression comment specification is as follows:
|
||||
The file-level suppression comment specification is as follows:
|
||||
|
||||
- An own-line comment starting with case sensitive `#ruff:`, with optional whitespace
|
||||
after the `#` symbol and `:` symbol, followed by `file-ignore[`, any rules to
|
||||
|
||||
@@ -132,9 +132,9 @@ suppression comments should essentially never be reasonable for a `correctness`
|
||||
for `suspicious` lints. The `suspicious` category also includes deprecations, which aren't incorrect
|
||||
today but will cause errors in the future.
|
||||
|
||||
The final branch of the flow chart deals with stylistic lints, which are again somewhat subjective
|
||||
to differentiate between changes that make code simpler often also make the code faster and
|
||||
more idiomatic. Thus, the question prompts you to consider the _primary_ improvement. Rules that
|
||||
The final branch of the flow chart deals with stylistic lints. These can be subjective to categorize:
|
||||
changes that make code simpler often also make it faster and more idiomatic. The question therefore
|
||||
prompts you to consider the _primary_ improvement. Rules that
|
||||
primarily make code simpler are `complexity` lints, those that primarily make code faster or use
|
||||
less memory are `performance` lints, and those that primarily make code more idiomatic are `style`.
|
||||
|
||||
|
||||
+7
-1
@@ -23,6 +23,12 @@ numbers
|
||||
└── py.typed
|
||||
```
|
||||
|
||||
Change into the project directory:
|
||||
|
||||
```console
|
||||
$ cd numbers
|
||||
```
|
||||
|
||||
We'll then clear out the auto-generated content in `src/numbers/__init__.py`
|
||||
and create `src/numbers/calculate.py` with the following code:
|
||||
|
||||
@@ -163,7 +169,7 @@ src/numbers/calculate.py:5:80: E501 Line too long (90 > 79)
|
||||
Found 1 error.
|
||||
```
|
||||
|
||||
For a full enumeration of the supported settings, see [_Settings_](settings.md). For our project
|
||||
For the full list of supported settings, see [_Settings_](settings.md). For our project
|
||||
specifically, we'll want to make note of the minimum supported Python version:
|
||||
|
||||
=== "pyproject.toml"
|
||||
|
||||
Reference in new issue
Block a user