pre-commit and pre-commit-ci

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+---
+ci:
+  # https://pre-commit.ci/#configuration
+  autoupdate_schedule: weekly
+  autofix_prs: false
+
+repos:
+  - repo: https://github.com/psf/black
+    # WARNING: rev should be the same as in `black.toml`.
+    rev: 21.9b0
+    hooks:
+      - id: black

docs/developers.rst

@@ -108,6 +108,46 @@ Check types with `mypy <http://mypy-lang.org/>`_:
 
     python -m mypy --show-error-context --show-error-codes rdflib
 
+pre-commit and pre-commit ci
+----------------------------
+
+We have `pre-commit <https://pre-commit.com/>`_ configured with `black
+<https://github.com/psf/black>`_ for formatting code.
+
+Some useful commands for using pre-commit:
+
+.. code-block:: bash
+
+    # Install pre-commit.
+    pip install --user --upgrade pre-commit
+
+    # Install pre-commit hooks, this will run pre-commit
+    # every time you make a git commit.
+    pre-commit install
+
+    # Run pre-commit on changed files.
+    pre-commit run
+
+    # Run pre-commit on all files.
+    pre-commit run --all-files
+
+There is also two tox environments for pre-commit:
+
+.. code-block:: bash
+
+    # run pre-commit on changed files.
+    tox -e precommit
+
+    # run pre-commit on all files.
+    tox -e precommitall
+
+
+There is no hard requirement for pull requests to be processed with pre-commit (or the underlying processors), however doing this makes for a less noisy codebase with cleaner history.
+
+We have enabled `https://pre-commit.ci/ <https://pre-commit.ci/>`_ and this can
+be used to automatically fix pull requests by commenting ``pre-commit.ci
+autofix`` on a pull request.
+
 Using tox
 ---------------------
 

pyproject.toml

@@ -1,4 +1,5 @@
 [tool.black]
+# WARNING: This should be the same as in `.pre-commit-config.yaml`.
 required-version = "21.9b0"
 line-length = "88"
 skip-string-normalization = true

setup.cfg

@@ -48,3 +48,6 @@ filterwarnings =
     ignore:Code. pytest_mock_example_attribute_that_shouldnt_exist is not defined in namespace .*:UserWarning
     # The below warning is a consequence of how pytest detects fixtures and how DefinedNamespace behaves when an undefined attribute is being accessed.
     ignore:Code. _pytestfixturefunction is not defined in namespace .*:UserWarning
+
+[isort]
+profile = black

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 envlist =
-    py37,py38,py39,py310
+    py37,py38,py39,py310,precommit
 
 [testenv]
 setenv =
@@ -46,6 +46,14 @@ setenv =
 commands =
     sphinx-build -n -T -b html -d {envtmpdir}/doctrees docs docs/_build/html
 
+[testenv:precommit{,all}]
+skip_install = true
+deps = pre-commit
+passenv = HOMEPATH  # needed on Windows
+commands =
+    precommit: pre-commit run
+    precommitall: pre-commit run --all-files
+
 [pytest]
 # log_cli = true
 # log_cli_level = DEBUG