-
Notifications
You must be signed in to change notification settings - Fork 166
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
4 changed files
with
10 additions
and
86 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,65 +1,18 @@ | ||
## Linting your code | ||
|
||
For linting, we currently make use of [ruff](https://github.com/charliermarsh/ruff) to perform checks, and if desired, *some* fixes for your code. | ||
|
||
For a standard formatter, we use [black](https://github.com/psf/black) against the code base. | ||
|
||
These are used to ensure we produce readable, maintainable, and more consistent code. | ||
We use [ruff](https://github.com/charliermarsh/ruff) for linting and formatting. | ||
|
||
To quickly run both the linter and formatter, you can source the linting bash script (shown below). The *-f* flag can be called to run automatic fixes with ruff. | ||
If you simply wish for ruff to print the errors it finds to the console, remove this flag. | ||
|
||
```sh | ||
source scripts/lint_and_format.sh -f # with the fix flag | ||
``` | ||
```sh | ||
source scripts/lint_and_format.sh # without | ||
``` | ||
|
||
??? tip "You can also run ruff and black separately from a terminal instance." | ||
**Black** can be run using: `black .` | ||
or to direct it at specific folders: `black splink/` | ||
|
||
and **ruff** requires: | ||
`ruff --fix .` for automatic fixes and error printouts | ||
or `ruff --show-source .` for error checking. | ||
|
||
## Error Suppression | ||
|
||
Should the linter be screaming at you about an "error" that you do not wish to change within the code base, you can ignore a single instance of a violation by using the `# noqa [ERROR CODE]` | ||
flag at the end of a code line. | ||
|
||
For example, let's say we have a `print()` statement buried somewhere in our code that we wish to keep, as it's useful in detecting whether a function has worked as expected. | ||
|
||
We can remove the lint detection of this line by adding any of the following flags: | ||
```py | ||
# Ignore T201. | ||
print("Ignore me!") # noqa: T201 | ||
|
||
# Ignore T201 and T203. | ||
print("Ignoring multiple rules") # noqa: T201, T201 | ||
|
||
# Ignore _all_ violations. | ||
print("Is there any point in this linter?") # noqa | ||
poetry run ruff format | ||
poetry run ruff check . | ||
``` | ||
|
||
Another useful example of this can be found within our backend comparison scripts. As we are merely importing and not subsequently using a series of functions and classes, the linter throw an error - **F401**. | ||
|
||
To suppress this, we simply add the [`# noqa: F401`](https://github.com/moj-analytical-services/splink/blob/master/splink/duckdb/comparison_level_library.py) flag as a comment next to the code chunk or line we wish to suppress checks for. | ||
|
||
For a more detailed overview of error suppression, see the [ruff documentation](https://beta.ruff.rs/docs/configuration/#error-suppression). | ||
|
||
## Additional Rules | ||
|
||
**ruff** contains an extensive arsenal of [linting rules and techniques](https://beta.ruff.rs/docs/rules/) that can be applied. | ||
|
||
Should there be a formatting concern that you feel hasn't been taken into account, please do check the full set of rules to determine whether this is supported by ruff and subsequently raise a pull request | ||
featuring this new rule. | ||
|
||
!!! example "Adding Additional Rules" | ||
|
||
To add additional rules to the linter, you simply need to: | ||
`ruff` contains an extensive arsenal of [linting rules and techniques](https://beta.ruff.rs/docs/rules/) that can be applied. | ||
|
||
1. Open up [pyproject.toml](https://github.com/moj-analytical-services/splink/blob/master/pyproject.toml) and navigate to `[tool.ruff]`. | ||
2. In the `select` block where we currently have `# pyflakes`, `# Pycodestyle`, etc. simply add your additional argument code, using the [ruff rules page](https://beta.ruff.rs/docs/rules/) as a reference. | ||
3. Add in a linting violation and run the `lint_and_format.sh` script to test your change is working as expected. | ||
If you wish to add an addition rule, do so in the `pyproject.toml` file in the root of the project. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.