diff --git a/docs/developer/style_guide.md b/docs/developer/style_guide.md index 51e4cfec734..93c25f8cc0a 100644 --- a/docs/developer/style_guide.md +++ b/docs/developer/style_guide.md @@ -1,15 +1,15 @@ --- id: dev_style_guide -title: Style Guide +title: Style Guide --- **TL;DR** - Install the provided pre-commits, follow their recommendations -# General Style -Rucio follows [flake8](https://flake8.pycqa.org/en/latest/user/index.html) style, ([with exclusions listed here](https://github.com/rucio/rucio/blob/master/.flake8)). -To use them to lint your code, run: +# General Style +Rucio follows [flake8](https://flake8.pycqa.org/en/latest/user/index.html) style, ([with exclusions listed here](https://github.com/rucio/rucio/blob/master/.flake8)). +To use them to lint your code, run: ``` -python{version} -m pip install flake8 +python{version} -m pip install flake8 flake8 --extend-ignore {codes to ignore} /your/code/path ``` @@ -17,50 +17,50 @@ flake8 --extend-ignore {codes to ignore} /your/code/path * Never import using `from x import *` * Order alphabetically, then seperated into sections for internal and external dependencies. Group internal imports at the end of the block, and group imports from the same external package. * Order modules such that `import {packageA}` is before `from {packageB} import {Module}` -* Do not import whole packages when single modules would suffice. -* Unused imports must be removed. -* When a large number of individual imports form a single package/module is required, group them together with `()` and separate them on their own lines. -* When importing a module specifically for type checking (e.g. a core module that may not be included in every distribution of rucio, a type from SQLAlchemy), contain them in a block using +* Do not import whole packages when single modules would suffice. +* Unused imports must be removed. +* When a large number of individual imports form a single package/module is required, group them together with `()` and separate them on their own lines. +* When importing a module specifically for type checking (e.g. a core module that may not be included in every distribution of rucio, a type from SQLAlchemy), contain them in a block using ```python from typing import TYPE_CHECKING -if TYPE_CHECKING: +if TYPE_CHECKING: from {package} import {module} ``` -[`ruff's isort` implementation](https://docs.astral.sh/ruff/faq/#how-does-ruffs-import-sorting-compare-to-isort) handles import sorting in the rucio `pre-commit`s. +[`ruff's isort` implementation](https://docs.astral.sh/ruff/faq/#how-does-ruffs-import-sorting-compare-to-isort) handles import sorting in the rucio `pre-commit`s. -#### Examples: -```python +#### Examples: +```python # Wrong -import rucio -from datetime import * -import os +import rucio +from datetime import * +import os # Right -import os +import os from datetime import datetime, timedelta from rucio.core.did import add_did ``` -```python +```python # Wrong from packageA import moduleA, moduleB, moduleC, moduleD, moduleE, moduleF, moduleG, ... # Right -from packageA import ( - moduleA, - moduleB, - moduleC, - moduleD, +from packageA import ( + moduleA, + moduleB, + moduleC, + moduleD, moduleE, - moduleF, - moduleG, + moduleF, + moduleG, ... ) ``` -# SQLAlchemy Query Guide +# SQLAlchemy Query Guide The Rucio project has adopted a particular coding style for its interaction with the database. It can be split into two parts: constructing the SQL statement, and executing it and handling its results. @@ -223,29 +223,29 @@ stmt = update( }) ``` -# Pre-commits -Rucio uses the [`flake8`](https://github.com/PyCQA/flake8) precommit as a linter, [`ruff`](https://github.com/astral-sh/ruff-pre-commit) as a formatter, -a custom whitespace remover, and a script to verify a uniform file-header format. -Please use these before submitting a pull request. +# Pre-commits +Rucio uses the [`flake8`](https://github.com/PyCQA/flake8) precommit as a linter, [`ruff`](https://github.com/astral-sh/ruff-pre-commit) as a formatter, +a custom whitespace remover, and a script to verify a uniform file-header format. +Please use these before submitting a pull request. -The Rucio repo provides a `pre-commit` that does this automatically. -Install it with the below commands. +The Rucio repo provides a `pre-commit` that does this automatically. +Install it with the below commands. ```shell pip install pre-commit pre-commit install ``` -# GitHub Actions -Code style is checked during a pull request with a GitHub action. -The action checks the header and type annotations (including a count and veracity). -More information about type annotations can be found [here](./type_annotation_guide.md). +# GitHub Actions +Code style is checked during a pull request with a GitHub action. +The action checks the header and type annotations (including a count and veracity). +More information about type annotations can be found [here](./type_annotation_guide.md). These checks can also be run locally using -```shell -tools/count_missing_type_annotations_utils.sh +```shell +tools/count_missing_type_annotations_utils.sh tools/run_pyright.sh generate {report_output_path.json} ``` -The first action will raise an error if your commits introduce more un-annotated types than it solves, -and the second ensures the added types are consistent with the rest of the codebase. +The first action will raise an error if your commits introduce more un-annotated types than it solves, +and the second ensures the added types are consistent with the rest of the codebase.