From 352ed966a2459842ac4a6d7c659b7ec217f1c0e9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=B6rg=20Behrmann?= Date: Thu, 6 Feb 2025 16:06:23 +0100 Subject: [PATCH] docs: add CODING_STYLE.md --- docs/CODING_STYLE.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/CODING_STYLE.md diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md new file mode 100644 index 000000000..ea7b7f917 --- /dev/null +++ b/docs/CODING_STYLE.md @@ -0,0 +1,40 @@ +--- +title: Coding Style +category: Contributing +layout: default +SPDX-License-Identifier: LGPL-2.1-or-later +--- + +# Coding Style + +## Python Version + +- The lowest supported Python version is CPython 3.9. + +## Formatting + +- Use the accompanying `.editorconfig` or `.dir-locals.el`. +- For Python files we use the style from `ruff format` with a line length of 109 characters and four spaces + indentation. +- Indentation with tabs is not allowed. +- When it improves readability, judicious use of `# noqa: E501` comments is allowed. +- Long lists, including argument lists, should have a trailing comma to force ruff to split all elements on a + line of their own. +- List of commandline arguments should not split the argument of a commandline option and the option. This + needs to be enforced with `# fmt: skip` comments, e.g. do + ```python + cmd = [ + "--option", "foo", + ] # fmt: skip + ``` + and do NOT do + ```python + cmd = [ + "--option", + "foo", + ] + ``` +- When coercing Path-like objects to strings, use `os.fspath`, since this calls the `__fspath__` protocol + instead of `__str__`. It also ensures more type-safety, since every Python object supports `__str__`, but + not all support `__fspath__` and this gives the typechecker more information what is expected at this + point. It also signals the intent to the reader more than a blanket `str()`. -- 2.47.2