Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 50 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,54 @@ pip install flake8-trio
- **TRIO911**: Exit, `yield` or `return` from async iterable with no guaranteed checkpoint since possible function entry (yield or function definition)
Checkpoints are `await`, `async for`, and `async with` (on one of enter/exit).

## Examples
### install and run through flake8
```sh
pip install flake8 flake8-trio
flake8 .
```
### install and run with pre-commit
If you use [pre-commit](https://pre-commit.com/), you can use it with flake8_trio by
adding the following to your `.pre-commit-config.yaml`:

```yaml
minimum_pre_commit_version: '2.9.0'
repos:
- repo: https://github.com/Zac-HD/flake8-trio
rev: 23.2.5
hooks:
- id: flake8-trio
# args: [--enable=TRIO, --disable=TRIO9, --autofix=TRIO]
```

This is often considerably faster for large projects, because `pre-commit`
can avoid running `flake8_trio` on unchanged files.


Afterwards, run
```sh
pip install pre-commit flake8-trio
pre-commit run .
```
### install and run as standalone
If inside a git repository, running without arguments will run it against all `*.py` files in the repository.
```sh
pip install flake8-trio
flake8_trio
```
#### with autofixes
```sh
flake8_trio --autofix=TRIO
```
#### specifying source files
```sh
flake8_trio my_python_file.py
```
##### zsh-only
```zsh
flake8_trio **/*.py
```

## Configuration
[You can configure `flake8` with command-line options](https://flake8.pycqa.org/en/latest/user/configuration.html),
but we prefer using a config file. The file needs to start with a section marker `[flake8]` and the following options are then parsed using flake8's config parser, and can be used just like any other flake8 options.
Expand All @@ -75,7 +123,7 @@ Comma-separated list of error codes to enable, similar to flake8 --select but is
Comma-separated list of error codes to disable, similar to flake8 --ignore but is additionally more performant as it will disable non-enabled visitors from running instead of just silencing their errors.

### `--autofix`
Comma-separated list of error-codes to enable autofixing for if implemented. Requires running as a standalone program.
Comma-separated list of error-codes to enable autofixing for if implemented. Requires running as a standalone program. Pass `--autofix=TRIO` to enable all autofixes.

### `--error-on-autofix`
Whether to also print an error message for autofixed errors.
Expand All @@ -84,7 +132,7 @@ Whether to also print an error message for autofixed errors.
Change the default library to be anyio instead of trio. If trio is imported it will assume both are available and print suggestions with [anyio|trio].

### `no-checkpoint-warning-decorators`
Specify a list of decorators to disable checkpointing checks for, turning off TRIO910 and TRIO911 warnings for functions decorated with any decorator matching any in the list. Matching is done with [fnmatch](https://docs.python.org/3/library/fnmatch.html). Defaults to disabling for `asynccontextmanager`.
Comma-separated list of decorators to disable checkpointing checks for, turning off TRIO910 and TRIO911 warnings for functions decorated with any decorator matching any in the list. Matching is done with [fnmatch](https://docs.python.org/3/library/fnmatch.html). Defaults to disabling for `asynccontextmanager`.

Decorators-to-match must be identifiers or dotted names only (not PEP-614 expressions), and will match against the name only - e.g. `foo.bar` matches `foo.bar`, `foo.bar()`, and `foo.bar(args, here)`, etc.

Expand Down Expand Up @@ -136,21 +184,3 @@ async def my_function():

arbitrary_other_function(my_blocking_call=None)
```


### Using flake8_trio with pre-commit
If you use [pre-commit](https://pre-commit.com/), you can use it with flake8_trio by
adding the following to your `.pre-commit-config.yaml`:

```yaml
minimum_pre_commit_version: '2.9.0'
repos:
- repo: https://github.com/Zac-HD/flake8-trio
rev: 23.2.5
hooks:
- id: flake8-trio
# args: [--enable=TRIO, --disable=TRIO9, --autofix=TRIO]
```

This is often considerably faster for large projects, because `pre-commit`
can avoid running `flake8_trio` on unchanged files.