Skip to content

Commit

Permalink
DOC: recommend ruff format instead of black
Browse files Browse the repository at this point in the history
Signed-off-by: Simon Brugman <[email protected]>
  • Loading branch information
sbrugman committed Dec 18, 2023
1 parent 52d5189 commit d9c5514
Showing 1 changed file with 33 additions and 22 deletions.
55 changes: 33 additions & 22 deletions docs/source/development/linting.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,34 +9,36 @@ Linting tools check your code for errors such as a missing bracket or line inden
As a project grows and goes through various stages of development it becomes important to maintain code quality. Using a consistent format and linting your code ensures that it is consistent, readable, and easy to debug and maintain.

## Set up Python tools
There are a variety of Python tools available to use with your Kedro projects. This guide shows you how to use [`black`](https://github.com/psf/black) and [`ruff`](https://beta.ruff.rs).
- **`black`** is a [PEP 8](https://peps.python.org/pep-0008/) compliant opinionated Python code formatter. `black` can
check for styling inconsistencies and reformat your files in place.
[You can read more in the `black` documentation](https://black.readthedocs.io/en/stable/).
- **`ruff`** is a fast linter that replaces `flake8`, `pylint`, `pyupgrade`, `isort` and [more](https://beta.ruff.rs/docs/rules/).
- It helps to make your code compliant to [`pep8`](https://pypi.org/project/pep8/).
- It reformats code by sorting imports alphabetically and automatically separating them into sections by
type. [You can read more in the `isort` documentation](https://pycqa.github.io/isort/).

There are a variety of Python tools available to use with your Kedro projects. This guide shows you how to use [`ruff`](https://beta.ruff.rs).

**`ruff`** is a fast linter and formatter that replaces `flake8`, `pylint`, `pyupgrade`, `isort`, `black` and [more](https://beta.ruff.rs/docs/rules/).
- It helps to make your code compliant to [PEP 8](https://peps.python.org/pep-0008/).
- It reformats code and sorts imports alphabetically and automatically separating them into sections by

Check warning on line 17 in docs/source/development/linting.md

View workflow job for this annotation

GitHub Actions / runner / vale

[vale] reported by reviewdog 🐶 [Kedro.Spellings] Did you really mean 'reformats'? Raw Output: {"message": "[Kedro.Spellings] Did you really mean 'reformats'?", "location": {"path": "docs/source/development/linting.md", "range": {"start": {"line": 17, "column": 8}}}, "severity": "WARNING"}
type.

### Install the tools
Install `black` and `ruff` by adding the following lines to your project's `requirements.txt`
Install `ruff` by adding the following lines to your project's `requirements.txt`
file:
```text
black # Used for formatting code
ruff # Used for linting, formatting and sorting module imports
```

To install all the project-specific dependencies, including the linting tools, navigate to the root directory of the
project and run:

```bash
pip install -r requirements.txt
```

Alternatively, you can individually install the linting tools using the following shell commands:

```bash
pip install black ruff
pip install ruff
```

#### Configure `ruff`

`ruff` read configurations from `pyproject.toml` within your project root. You can enable different rule sets within the `[tool.ruff]` section. For example, the rule set `F` is equivalent to `Pyflakes`.

To start with `ruff`, we recommend adding this section to enable a few basic rules sets.
Expand All @@ -58,12 +60,13 @@ It is a good practice to [split your line when it is too long](https://beta.ruff
```

### Run the tools

Use the following commands to run lint checks:
```bash
black --check <project_root>
ruff format --check <project_root>
ruff check <project_root>
```
You can also have `black` automatically format your code by omitting the `--check` flag.
You can also have `ruff format` automatically format your code by omitting the `--check` flag.

## Automated formatting and linting with `pre-commit` hooks

Expand All @@ -72,36 +75,44 @@ These hooks are run before committing your code to your repositories to automati
making code reviews easier and less time-consuming.

### Install `pre-commit`

You can install `pre-commit` along with other dependencies by including it in the `requirements.txt` file of your
Kedro project by adding the following line:

```text
pre-commit
```
You can also install `pre-commit` using the following command:

```bash
pip install pre-commit
```

### Add `pre-commit` configuration file

Create a file named `.pre-commit-config.yaml` in your Kedro project root directory. You can add entries for the hooks
you want to run before each `commit`.
Below is a sample `YAML` file with entries for `ruff` and black`:
Below is a sample `YAML` file with entries for `ruff`:

```yaml
repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
# Ruff version.
rev: v0.0.270
rev: '' # Replace with latest version, for example 'v0.1.8'
hooks:
- id: ruff

- repo: https://github.com/psf/black
rev: 22.8.0
hooks:
- id: black
language_version: python3.9
args: [--fix]
- id: ruff-format
```
See GitHub for [the latest configuration for ruff's pre-commit](https://github.com/astral-sh/ruff-pre-commit).
### Install git hook scripts
Run the following command to complete installation:
```bash
pre-commit install
```

This enables `pre-commit` hooks to run automatically every time you execute `git commit`.

0 comments on commit d9c5514

Please sign in to comment.