You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* update docs, name of binary, and in general all changes possible without renaming files
* rename error codes to ASYNCxxx, introducing temp functions to pretend test files are renamed.
* rename Flake8TrioVisitor to Flake8AsyncVisitor
[](https://microsoft.github.io/pyright/)
3
-
# flake8-trio
3
+
# flake8-async
4
4
5
-
A highly opinionated flake8 plugin for [Trio](https://github.com/python-trio/trio)-related problems.
5
+
A highly opinionated flake8 plugin for problems related to [Trio](https://github.com/python-trio/trio), [AnyIO](https://github.com/agronholm/anyio), or [asyncio](https://docs.python.org/3/library/asyncio.html).
6
6
7
7
This can include anything from outright bugs, to pointless/dead code,
8
8
to likely performance issues, to minor points of idiom that might signal
9
9
a misunderstanding.
10
10
11
11
It may well be too noisy for anyone with different opinions, that's OK.
12
12
13
-
It also supports the [anyio](https://github.com/agronholm/anyio) library.
14
-
15
13
Pairs well with flake8-bugbear.
16
14
15
+
Some checks are incorporated into [ruff](https://github.com/astral-sh/ruff).
16
+
17
+
This plugin was previously known as flake8-trio, and there was a separate small plugin known as flake8-async for asyncio. But this plugin was a superset of the checks in flake8-async, and support for anyio was added, so it's now named flake8-async to more properly convey its usage. At the same time all error codes were renamed from TRIOxxx to ASYNCxxx, as was previously used by the old flake8-async.
18
+
17
19
## Installation
18
20
19
21
```console
20
-
pip install flake8-trio
22
+
pip install flake8-async
21
23
```
22
24
23
25
## List of warnings
24
26
25
-
-**TRIO100**: A `with trio.fail_after(...):` or `with trio.move_on_after(...):`
27
+
-**ASYNC100**: A `with trio.fail_after(...):` or `with trio.move_on_after(...):`
26
28
context does not contain any `await` statements. This makes it pointless, as
27
29
the timeout can only be triggered by a checkpoint.
28
-
-**TRIO101**: `yield` inside a nursery or cancel scope is only safe when implementing a context manager - otherwise, it breaks exception handling.
29
-
-**TRIO102**: It's unsafe to await inside `finally:` or `except BaseException/trio.Cancelled` unless you use a shielded
30
+
-**ASYNC101**: `yield` inside a nursery or cancel scope is only safe when implementing a context manager - otherwise, it breaks exception handling.
31
+
-**ASYNC102**: It's unsafe to await inside `finally:` or `except BaseException/trio.Cancelled` unless you use a shielded
30
32
cancel scope with a timeout.
31
-
-**TRIO103**: `except BaseException`, `except trio.Cancelled` or a bare `except:` with a code path that doesn't re-raise. If you don't want to re-raise `BaseException`, add a separate handler for `trio.Cancelled` before.
32
-
-**TRIO104**: `Cancelled` and `BaseException` must be re-raised - when a user tries to `return` or `raise` a different exception.
33
-
-**TRIO105**: Calling a trio async function without immediately `await`ing it.
34
-
-**TRIO106**: `trio` must be imported with `import trio` for the linter to work.
35
-
-**TRIO109**: Async function definition with a `timeout` parameter - use `trio.[fail/move_on]_[after/at]` instead
36
-
-**TRIO110**: `while <condition>: await trio.sleep()` should be replaced by a `trio.Event`.
37
-
-**TRIO111**: Variable, from context manager opened inside nursery, passed to `start[_soon]` might be invalidly accessed while in use, due to context manager closing before the nursery. This is usually a bug, and nurseries should generally be the inner-most context manager.
38
-
-**TRIO112**: Nursery body with only a call to `nursery.start[_soon]` and not passing itself as a parameter can be replaced with a regular function call.
39
-
-**TRIO113**: Using `nursery.start_soon` in `__aenter__` doesn't wait for the task to begin. Consider replacing with `nursery.start`.
40
-
-**TRIO114**: Startable function (i.e. has a `task_status` keyword parameter) not in `--startable-in-context-manager` parameter list, please add it so TRIO113 can catch errors when using it.
41
-
-**TRIO115**: Replace `trio.sleep(0)` with the more suggestive `trio.lowlevel.checkpoint()`.
42
-
-**TRIO116**: `trio.sleep()` with >24 hour interval should usually be `trio.sleep_forever()`.
43
-
-**TRIO118**: Don't assign the value of `anyio.get_cancelled_exc_class()` to a variable, since that breaks linter checks and multi-backend programs.
33
+
-**ASYNC103**: `except BaseException`, `except trio.Cancelled` or a bare `except:` with a code path that doesn't re-raise. If you don't want to re-raise `BaseException`, add a separate handler for `trio.Cancelled` before.
34
+
-**ASYNC104**: `Cancelled` and `BaseException` must be re-raised - when a user tries to `return` or `raise` a different exception.
35
+
-**ASYNC105**: Calling a trio async function without immediately `await`ing it.
36
+
-**ASYNC106**: `trio`/`anyio` must be imported with `import trio`/`import anyio` for the linter to work.
37
+
-**ASYNC109**: Async function definition with a `timeout` parameter - use `trio.[fail/move_on]_[after/at]` instead
38
+
-**ASYNC110**: `while <condition>: await trio.sleep()` should be replaced by a `trio.Event`.
39
+
-**ASYNC111**: Variable, from context manager opened inside nursery, passed to `start[_soon]` might be invalidly accessed while in use, due to context manager closing before the nursery. This is usually a bug, and nurseries should generally be the inner-most context manager.
40
+
-**ASYNC112**: Nursery body with only a call to `nursery.start[_soon]` and not passing itself as a parameter can be replaced with a regular function call.
41
+
-**ASYNC113**: Using `nursery.start_soon` in `__aenter__` doesn't wait for the task to begin. Consider replacing with `nursery.start`.
42
+
-**ASYNC114**: Startable function (i.e. has a `task_status` keyword parameter) not in `--startable-in-context-manager` parameter list, please add it so ASYNC113 can catch errors when using it.
43
+
-**ASYNC115**: Replace `trio.sleep(0)` with the more suggestive `trio.lowlevel.checkpoint()`.
44
+
-**ASYNC116**: `trio.sleep()` with >24 hour interval should usually be `trio.sleep_forever()`.
45
+
-**ASYNC118**: Don't assign the value of `anyio.get_cancelled_exc_class()` to a variable, since that breaks linter checks and multi-backend programs.
44
46
45
47
### Warnings for blocking sync calls in async functions
46
-
-**TRIO200**: User-configured error for blocking sync calls in async functions. Does nothing by default, see [`trio200-blocking-calls`](#trio200-blocking-calls) for how to configure it.
47
-
-**TRIO210**: Sync HTTP call in async function, use `httpx.AsyncClient`.
48
-
-**TRIO211**: Likely sync HTTP call in async function, use `httpx.AsyncClient`. Looks for `urllib3` method calls on pool objects, but only matching on the method signature and not the object.
49
-
-**TRIO212**: Blocking sync HTTP call on httpx object, use httpx.AsyncClient.
50
-
-**TRIO220**: Sync process call in async function, use `await nursery.start(trio.run_process, ...)`.
51
-
-**TRIO221**: Sync process call in async function, use `await trio.run_process(...)`.
52
-
-**TRIO222**: Sync `os.*` call in async function, wrap in `await trio.to_thread.run_sync()`.
53
-
-**TRIO230**: Sync IO call in async function, use `trio.open_file(...)`.
54
-
-**TRIO231**: Sync IO call in async function, use `trio.wrap_file(...)`.
55
-
-**TRIO232**: Blocking sync call on file object, wrap the file object in `trio.wrap_file()` to get an async file object.
56
-
-**TRIO240**: Avoid using `os.path` in async functions, prefer using `trio.Path` objects.
48
+
-**ASYNC200**: User-configured error for blocking sync calls in async functions. Does nothing by default, see [`trio200-blocking-calls`](#trio200-blocking-calls) for how to configure it.
49
+
-**ASYNC210**: Sync HTTP call in async function, use `httpx.AsyncClient`.
50
+
-**ASYNC211**: Likely sync HTTP call in async function, use `httpx.AsyncClient`. Looks for `urllib3` method calls on pool objects, but only matching on the method signature and not the object.
51
+
-**ASYNC212**: Blocking sync HTTP call on httpx object, use httpx.AsyncClient.
52
+
-**ASYNC220**: Sync process call in async function, use `await nursery.start(trio.run_process, ...)`.
53
+
-**ASYNC221**: Sync process call in async function, use `await trio.run_process(...)`.
54
+
-**ASYNC222**: Sync `os.*` call in async function, wrap in `await trio.to_thread.run_sync()`.
55
+
-**ASYNC230**: Sync IO call in async function, use `trio.open_file(...)`.
56
+
-**ASYNC231**: Sync IO call in async function, use `trio.wrap_file(...)`.
57
+
-**ASYNC232**: Blocking sync call on file object, wrap the file object in `trio.wrap_file()` to get an async file object.
58
+
-**ASYNC240**: Avoid using `os.path` in async functions, prefer using `trio.Path` objects.
57
59
58
60
### Warnings disabled by default
59
-
-**TRIO900**: Async generator without `@asynccontextmanager` not allowed.
60
-
-**TRIO910**: Exit or `return` from async function with no guaranteed checkpoint or exception since function definition.
61
-
-**TRIO911**: Exit, `yield` or `return` from async iterable with no guaranteed checkpoint since possible function entry (yield or function definition)
61
+
-**ASYNC900**: Async generator without `@asynccontextmanager` not allowed.
62
+
-**ASYNC910**: Exit or `return` from async function with no guaranteed checkpoint or exception since function definition.
63
+
-**ASYNC911**: Exit, `yield` or `return` from async iterable with no guaranteed checkpoint since possible function entry (yield or function definition)
62
64
Checkpoints are `await`, `async for`, and `async with` (on one of enter/exit).
63
65
64
66
### Removed Warnings
@@ -69,55 +71,55 @@ pip install flake8-trio
69
71
## Examples
70
72
### install and run through flake8
71
73
```sh
72
-
pip install flake8 flake8-trio
74
+
pip install flake8 flake8-async
73
75
flake8 .
74
76
```
75
77
### install and run with pre-commit
76
-
If you use [pre-commit](https://pre-commit.com/), you can use it with flake8-trio by
78
+
If you use [pre-commit](https://pre-commit.com/), you can use it with flake8-async by
77
79
adding the following to your `.pre-commit-config.yaml`:
This is often considerably faster for large projects, because `pre-commit`
90
-
can avoid running `flake8-trio` on unchanged files.
92
+
can avoid running `flake8-async` on unchanged files.
91
93
92
94
93
95
Afterwards, run
94
96
```sh
95
-
pip install pre-commit flake8-trio
97
+
pip install pre-commit flake8-async
96
98
pre-commit run .
97
99
```
98
100
### install and run as standalone
99
101
If inside a git repository, running without arguments will run it against all `*.py` files in the repository.
100
102
```sh
101
-
pip install flake8-trio
102
-
flake8-trio
103
+
pip install flake8-async
104
+
flake8-async
103
105
```
104
106
#### with autofixes
105
107
```sh
106
-
flake8-trio --autofix=TRIO
108
+
flake8-async --autofix=ASYNC
107
109
```
108
110
#### specifying source files
109
111
```sh
110
-
flake8-trio my_python_file.py
112
+
flake8-async my_python_file.py
111
113
```
112
114
##### zsh-only
113
115
```zsh
114
-
flake8-trio**/*.py
116
+
flake8-async**/*.py
115
117
```
116
118
117
119
## Configuration
118
120
[You can configure `flake8` with command-line options](https://flake8.pycqa.org/en/latest/user/configuration.html),
119
121
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.
120
-
Note that it's not currently possible to use a configuration file when running `flake8-trio` standalone.
122
+
Note that it's not currently possible to use a configuration file when running `flake8-async` standalone.
121
123
122
124
### `--enable`
123
125
Comma-separated list of error codes to enable, similar to flake8 --select but is additionally more performant as it will disable non-enabled visitors from running instead of just silencing their errors.
@@ -126,7 +128,7 @@ Comma-separated list of error codes to enable, similar to flake8 --select but is
126
128
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.
127
129
128
130
### `--autofix`
129
-
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.
131
+
Comma-separated list of error-codes to enable autofixing for if implemented. Requires running as a standalone program. Pass `--autofix=ASYNC` to enable all autofixes.
130
132
131
133
### `--error-on-autofix`
132
134
Whether to also print an error message for autofixed errors.
@@ -135,7 +137,7 @@ Whether to also print an error message for autofixed errors.
135
137
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].
136
138
137
139
### `no-checkpoint-warning-decorators`
138
-
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`.
140
+
Comma-separated list of decorators to disable checkpointing checks for, turning off ASYNC910 and ASYNC911 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`.
139
141
140
142
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.
Comma-separated list of pairs of values separated by `->` (optional whitespace stripped), where the first is a pattern for a call that should raise an error if found inside an async function, and the second is what should be suggested to use instead. It uses fnmatch as per [`no-checkpoint-warning-decorators`](#no-checkpoint-warning-decorators) for matching. The part after `->` is not used by the checker other than when printing the error, so you could add extra info there if you want.
164
166
165
167
The format of the error message is `User-configured blocking sync call {0} in async function, consider replacing with {1}.`, where `{0}` is the pattern the call matches and `{1}` is the suggested replacement.
166
168
167
169
Example:
168
170
```ini
169
-
trio200-blocking-calls =
171
+
async200-blocking-calls =
170
172
my_blocking_call -> async.alternative,
171
173
module.block_call -> other_function_to_use,
172
174
common_error_call -> alternative(). But sometimes you should use other_function(). Ask joe if you're unsure which one,
0 commit comments