From a923f496a086d87ea552a06258a3d6b6076d0a8e Mon Sep 17 00:00:00 2001 From: gwen Date: Sat, 6 Jun 2026 09:34:05 +0200 Subject: [PATCH] docs(devnotes): precommit --- docs/concepts.rst | 2 +- docs/developer.rst | 282 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+), 1 deletion(-) diff --git a/docs/concepts.rst b/docs/concepts.rst index 2898e1428..b9d5b699a 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -343,7 +343,7 @@ Access control is achieved through `properties`. The properties can be defined permanently or according to the result of a calculation. -There is two main properties. +There are two main properties. Hidden variable ~~~~~~~~~~~~~~~ diff --git a/docs/developer.rst b/docs/developer.rst index 8fafd92fb..225fd519a 100644 --- a/docs/developer.rst +++ b/docs/developer.rst @@ -58,3 +58,285 @@ We use black - id: black And some YAML and JSON validators. + + +---- + +The pre commit tool +---------------------- + +**pre-commit** is a fantastic tool for automating code quality checks +before you commit your changes. It’s especially useful in Python +projects for running linters, formatters, and other checks +automatically. + +Here’s a **practical, minimal example** to get you started with a small +Python project. + + +1. Install pre-commit +--------------------- + +First, install the ``pre-commit`` package: + +.. code:: bash + + pip install pre-commit + + +2. Create a ``.pre-commit-config.yaml`` File +-------------------------------------------- + +In the root of your Python project, create a file named +``.pre-commit-config.yaml`` with the following content: + +.. code:: yaml + + repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + + - repo: https://github.com/pycqa/flake8 + rev: 6.1.0 + hooks: + - id: flake8 + +This config: - Uses popular pre-commit hooks for basic checks - Adds +`Black `__ for code formatting - Adds +`Flake8 `__ for linting + + +3. Install the Git Hook +----------------------- + +Run this command in your project root: + +.. code:: bash + + pre-commit install + +This sets up a Git hook that runs the checks before each commit. + + +4. Try It Out +------------- + +Now, when you try to commit: + +.. code:: bash + + git add . + git commit -m "My commit message" + +pre-commit will run the hooks. If any check fails, you’ll see output +like this: + +:: + + Trim Trailing Whitespace............................................Passed + Fix End of Files....................................................Passed + Check Yaml..........................................................Passed + Check for added large files..........................................Passed + Black..............................................................Failed + - hook id: black + - exit code: 1 + + Reformatted /path/to/your/file.py + All done! ✨ 🍰 ✨ + 1 file reformatted. + +If any hook fails, fix the issues and try committing again. + + +5. (Optional) Run pre-commit Manually +------------------------------------- + +You can run all hooks against all files at any time: + +.. code:: bash + + pre-commit run --all-files + + +6. Update Hooks +--------------- + +To update your hooks to the latest versions: + +.. code:: bash + + pre-commit autoupdate + +**Summary Table** +~~~~~~~~~~~~~~~~~ + +==== ===================== ============================== +Step Action Command +==== ===================== ============================== +1 Install pre-commit ``pip install pre-commit`` +2 Create config file ``.pre-commit-config.yaml`` +3 Install Git hook ``pre-commit install`` +4 Commit and see checks ``git commit -m "..."`` +5 Run manually ``pre-commit run --all-files`` +6 Update hooks ``pre-commit autoupdate`` +==== ===================== ============================== + +more python linters +------------------- + +Customizing your ``.pre-commit-config.yaml`` to include **pylint**, +**ruff**, and additional hooks is a great way to maintain code quality. +Here’s how you can structure your config for a robust setup: + +**1. Basic Setup with pylint and ruff** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here’s a starting point for your ``.pre-commit-config.yaml``: + +.. code:: yaml + + repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.1.6 + hooks: + - id: ruff + args: [--fix, --exit-non-zero-on-fix] + + - repo: https://github.com/pycqa/pylint + rev: v3.0.3 + hooks: + - id: pylint + args: [--rcfile=.pylintrc] # Optional: specify a pylint config file + +**2. Adding More Hooks** +~~~~~~~~~~~~~~~~~~~~~~~~ + +Here are some popular hooks you might want to add: + +**a. Black (Code Formatter)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: yaml + + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + +**b. Mypy (Static Type Checker)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: yaml + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.8.0 + hooks: + - id: mypy + +**c. isort (Import Sorter)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: yaml + + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + +**d. Bandit (Security Linter)** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code:: yaml + + - repo: https://github.com/pycqa/bandit + rev: 1.7.7 + hooks: + - id: bandit + +**3. Full Example Config** +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here’s a full example with all the above hooks: + +.. code:: yaml + + repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.1.6 + hooks: + - id: ruff + args: [--fix, --exit-non-zero-on-fix] + + - repo: https://github.com/pycqa/pylint + rev: v3.0.3 + hooks: + - id: pylint + args: [--rcfile=.pylintrc] + + - repo: https://github.com/psf/black + rev: 23.12.1 + hooks: + - id: black + + - repo: https://github.com/pre-commit/mirrors-mypy + rev: v1.8.0 + hooks: + - id: mypy + + - repo: https://github.com/pycqa/isort + rev: 5.13.2 + hooks: + - id: isort + + - repo: https://github.com/pycqa/bandit + rev: 1.7.7 + hooks: + - id: bandit + +**4. Customizing Hooks** +~~~~~~~~~~~~~~~~~~~~~~~~ + +- **pylint**: You can specify a config file (``.pylintrc``) or pass + arguments directly. +- **ruff**: You can customize rules in ``pyproject.toml`` or + ``.ruff.toml``. +- **Black, isort, mypy**: Each can be configured via their respective + config files. + +**5. Installing and Running** +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Save the config to ``.pre-commit-config.yaml``. + +2. Run: + + .. code:: bash + + pre-commit install + pre-commit run --all-files