Merge pull request #175 from jakkdl/examples

Author: Zac-HD

README.md

@@ -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.  
@@ -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.
@@ -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.
 
@@ -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.