We use ruff to enforce the coding style.
Its rules live in the pyproject.toml of the respective (sub-)project.
Repositories that ship a .pre-commit-config.yaml run ruff through
pre-commit.
Install the git hooks once:
python3 -m pip install pre-commit
pre-commit installAfter that you can check the whole repository with:
pre-commit run --all-filesRepositories without a .pre-commit-config.yaml run ruff directly:
uvx ruff check .The repository-specific part of this file names the exact command wherever it differs.
We use single quotes for strings in the code and double quotes for docstrings. Double quotes may also be used for strings if the string contains a single quote.
We use f-strings if possible (due to their readability).
Logs shall use the lazy formatting provided by logging (performance optimization).
When diverging from above rules, please provide a short comment with # NOTE: ... to explain the reason.
To break a long statement across multiple lines, we use a trailing backslash (\) to break between chained calls, rather than breaking inside a call's parentheses. This reads better for
fluent/builder chains such as NiceGUI element construction, where the leading . on each line clearly marks the continuation and each call keeps its arguments together.
# preferred
ui.button('Speichern', on_click=self.save)\
.props('no-caps')\
.classes('button-primary')
# avoid (using the open parenthesis of a call to wrap)
ui.button('Speichern', on_click=self.save).props(
'no-caps').classes(
'button-primary')We keep comments as few and as short as possible. A comment should only state what is needed to understand the code — not the motivation behind an implementation and not a restatement of what the code already says. If the code is clear on its own, it needs no comment.
We do not use return values to signal success or failure.
A function that returns True/False or None for this purpose forces every caller to remember the convention, and a forgotten check fails silently.
Instead we raise exceptions — custom exception classes where appropriate — and handle them where the caller can react.
# preferred
def parse_config(path: Path) -> Config:
if not path.exists():
raise ConfigNotFoundError(path)
...
# avoid (None as failure signal)
def parse_config(path: Path) -> Config | None:
if not path.exists():
return None
...We want to have main classes and functions at the top of the file, while helper functions and classes should be placed below. This allows to quickly understand the main purpose of the file without having to scroll through a lot of code.
The same rule applies within a class:
- The public interface comes first: the constructor, then the public methods and properties.
- Every private helper is placed below the methods that call it, so a reader always meets the caller before the callee.
- If a helper is called by several methods, it is placed below all of them.
class ReportGenerator:
def __init__(self, source: Path) -> None:
self.source = source
def generate_summary(self) -> str:
rows = self._load_rows()
...
def generate_details(self) -> str:
rows = self._load_rows()
...
def _load_rows(self) -> list[Row]:
"""Called by generate_summary and generate_details, so it comes after both."""
...We use the reStructuredText (reST) or Sphinx-style docstring format.
We don't declare types in the docstring but use type hints.
While type hints are mandatory, parameter descriptions and docstrings should only
be used if the function and parameter names are not self-explanatory.
We write them in the modern annotation style — list[x], not List[x] — and import from
collections.abc rather than typing wherever both offer the name (e.g. Sequence).
Examples are listed below:
def greet() -> None:
"""Print a friendly greeting."""
print('Hello!')def square(x: int | float) -> int | float:
"""Return the square of x.
:param x: Number to square.
:return: The squared value.
"""
return x * xdef get_timestamp() -> str:
"""
Return the current timestamp as a formatted string.
This function retrieves the current local time and formats it
as "YYYY-MM-DD HH:MM:SS". It can be useful for logging or
displaying time information in user interfaces.
"""
return datetime.now().strftime('%Y-%m-%d %H:%M:%S')def save_data(data: str | bytes, filename: str, overwrite: bool = False) -> None:
"""
Save data to a file.
This function writes the provided data to a file on disk.
If the file already exists and `overwrite` is False, an
exception is raised to prevent accidental data loss.
:param data: The content to be saved. Can be text or bytes.
:param filename: Path to the destination file.
:param overwrite: Whether to overwrite an existing file.
:raises FileExistsError: If the file exists and overwrite is False.
"""
if os.path.exists(filename) and not overwrite:
raise FileExistsError(f'{filename} already exists.')
mode = 'wb' if isinstance(data, bytes) else 'w'
with open(filename, mode) as f:
f.write(data)Inside a package we import other modules of the same package with relative imports, not with the package name.
This way the package can be renamed or moved without touching its imports.
We use the shortest path: siblings with a single dot, no going up and back down (from ..ui.numpad import ... in a module that lives in ui/ itself).
Code outside the package — scripts, tests — has no choice and uses absolute imports.
# preferred (in app/ui/scan_view.py)
from .. import config
from ..system import System
from .numpad import Numpad
# avoid
from app import config
from app.system import System
from app.ui.numpad import NumpadWe declare dataclasses with kw_only=True and slots=True, so every field is named at the call site
and typos become errors instead of new attributes.
# preferred
@dataclass(kw_only=True, slots=True)
class Detection:
category: str
confidence: float
# avoid
@dataclass
class Detection:
category: str
confidence: floatBe conservative with default __init__ parameters.
A parameter that no caller ever varies is a constant, not a parameter, and hiding it in the signature
suggests a flexibility that nobody uses.
We log through the module-level logger, never through the root logger, and with lazy formatting, so
the arguments are only rendered when the record is actually emitted.
For temporary debug output we use print with flush=True, so the line shows up in the log right
away instead of sitting in the buffer.
# preferred
logger = logging.getLogger('mypackage.mymodule')
logger.info('loaded %s images', count)
print(f'reached the empty-category branch with {count} images', flush=True)
# avoid
logging.info(f'loaded {count} images')
print(f'reached the empty-category branch with {count} images')