docs(contributors): update Python guide (#14)

Co-authored-by: Alex Kanitz <[email protected]>

docs/guides/guide-contributor/language-specific/python.md

@@ -1,49 +1,128 @@
 # Python guidelines
 
-For any [Python][py] code, please stick to the guidelines described in this
+For all [Python][py] code, please stick to the guidelines described in this
 section.
 
 ## Python version
 
-For any new projects, please use one of the two most recent [Python minor
-versions][py-downloads]. For existing projects, use the Python version used
-throughout the project.
+For any _new_ projects, please use one of the two most recent [Python minor
+versions][py-downloads], exclusing pre-releases. For existing projects, use the
+Python version used throughout the project (mentioned in `pyproject.toml`).
 
-## Code formatting
+## Packaging, build system & dependencies
 
-Please format the code using [`black`][py-black] and default parameters. Where
-[`black`][py-black] is not prescriptive, please use a consistent coding style.
-In particular, when contributing to an existing code base, please adhere to the
-coding style you find. In all cases, please adhere to [PEP 8][py-pep8].
+Please use [`pyproject.toml`][py-toml] to configure packaging, building, and
+dependency management. Please do not use `setup.py` and do no specify your
+dependencies in `requirements.txt`, except for legacy projects where they are
+still used.
 
-## Docstrings
+Preferably, segregate dependencies for different tasks. For example, use
+`[tool.poetry.test.dependencies]` for testing dependencies, and
+`[tool.poetry.dependencies]` for runtime dependencies.
 
-Please add [Google-style docstrings][py-doc-google] to _all_ modules, functions
-and methods. Follow [PEP 257][py-pep257]. Do not include types in the
-docstrings.
+Please sort entries (sections, dependencies) in `pyproject.toml` alphabetically
+to ease maintenance. If using Poetry (see below), you can use the
+[`poetry-sort`][py-poetry-sort] plugin to help with this. Otherwise any other
+TOML sorter should work as well.
+
+> **Note**: We strongly recommend using the [Poetry][py-poetry] package manager
+> instead of `pip`. In that case, use `poetry.lock` to lock the dependencies
+> (make > sure to commit the file to version control). To add a new dependency,
+> use the following command:
+>
+> ```python
+> poetry add <package> --group=<group>
+> ```
+>
+> To build the project, use:
+>
+> ```python
+> poetry build
+> ```
+
+### Console scripts
+
+If your project has one or more console script entry points, use
+`pyproject.toml` file to define them, e.g.:
+
+```toml
+[tool.poetry.scripts]
+my-script = "my_package.my_module.my_submodule:my_function"
+```
+
+## Code formatting and linting
+
+### Ruff
+
+In an effort to reduce dependencies, we recommend using [`ruff`][py-ruff] for
+new projects and configuring it in `pyproject.toml`. Configure strictness based
+on project requirements, but at least use the following:
+
+```toml
+[tool.ruff.lint]
+select = [
+  "B", # flake8-bugbear
+  "D", # pydocstyle
+  "E", # pycodestyle
+  "F", # Pyflakes
+  "I", # isort
+  "PL", # pylint
+  "SIM", # flake8-simplify
+  "UP", # pyupgrade
+]
+```
+
+> **Note**: You can fix lints by running `ruff check --fix <Path>` and `ruff
+> format <Path>` to format the code.
+
+### Docstrings
+
+Please use [Google-style docstrings][py-doc-google] for all packages, modules,
+classes, methods and functions. With `pydocstyle`, you can enforce this style
+with the following entry in the `pyproject.toml` file:
+
+```toml
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+```
+
+For **methods and functions**, please include at least the following sections,
+where applicable:
+
+- `Args`
+- `Returns` (or `Yields`, for generator functions)
+- `Raises`
+
+For **classes**, please include the `Attributes` section.
+
+Furthermore, in all cases, consider including `Examples` and `Note` sections.
 
 ## Type hints
 
 Add [type hints][py-typing] to _all_ function and method signatures, as well as
-any global variables. Adding type hints to local variables is recommended.
-Adding type hints to (unit) tests is not necessary.
+any global variables. Adding type hints to local variables is recommended if
+types aren't obvious from assignments.
 
-## Linters & static type checkers
+Adding type hints to (unit) tests is not necessary.
 
-Please make use of the following tools with default parameters to make sure
-your code is of good quality:
+> **Note**: You can try using [MonkeyType][py-monkey-type] to help with adding
+> type hints to your code.
 
-- [`flake8`][py-flake8]
-- [`flake8-docstring`][py-flake8-doc]
-- [`pylint`][py-pylint]
-- [`mypy`][py-mypy]
+### Static type checkers
 
-When disabling rules is required, it is preferable to do so in-line, rather
-than globally.
+Please use a type checker to check for type consistency across your project. We
+recommend using [`mypy`][py-mypy], but alternatives are acceptable.
 
 ## Testing
 
-Use [`pytest`][py-pytest] as a test runner for unit tests. You can determine
-the test coverage with the [`coverage`][py-cov] package. Strive for a test
-coverage of 100% for new projects. Proposed code changes should never reduce
-the previous test coverage.
+Please provide extensive tests (both unit and integration) for your code and
+determine the test coverage with the [`coverage`][py-cov] package. Strive
+for a test coverage of 100% for unit and 70% for integration tests, because:
+
+> Untested code is broken code.
+
+Please use [`pytest`][py-pytest] as a runner for your tests (it also comes with
+many useful features and extensions).
+
+Be aware that proposed code changes **must never** reduce the previous test
+coverage.

includes/references.md

@@ -103,17 +103,19 @@
 [openshift]: <https://www.redhat.com/en/technologies/cloud-computing/openshift>
 [osi]: <https://opensource.org/>
 [py]: <https://www.python.org/>
-[py-black]: <https://github.com/psf/black>
+[py-codecov]: <https://codecov.io/>
 [py-cov]: <https://github.com/nedbat/coveragepy>
 [py-doc-google]: <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>
 [py-downloads]: <https://www.python.org/downloads/>
-[py-flake8]: <https://github.com/PyCQA/flake8>
-[py-flake8-doc]: <https://github.com/PyCQA/flake8-docstrings>
-[py-pylint]: <https://github.com/PyCQA/pylint>
+[py-monkey-type]: <https://github.com/Instagram/MonkeyType>
 [py-mypy]: <https://github.com/python/mypy>
 [py-pep8]: <https://peps.python.org/pep-0008/>
 [py-pep257]: <https://peps.python.org/pep-0257/>
+[py-poetry]: <https://python-poetry.org/>
+[py-poetry-sort]: <https://pypi.org/project/poetry-sort/>
 [py-pytest]: <https://docs.pytest.org/en/latest/>
+[py-ruff]: <https://docs.astral.sh/ruff/>
+[py-toml]: <https://packaging.python.org/en/latest/guides/writing-pyproject-toml/>
 [py-typing]: <https://docs.python.org/3/library/typing.html>
 [sem-ver]: <https://semver.org/>
 [slurm]: <https://slurm.schedmd.com/>