the style guide for Python code (PEP 8) doesn’t recommend single vs. double quotes but states that triple-quoted strings should use double quotes "to be consistent with the docstring convention in PEP 257".

for this reason, we use double quotes everywhere, unless the text contains itself a double quote, in which case single quotes are obviously preferred.

we call items any definition of class, function, member, variable, etc…​

private items are pre-fixed with an underscore

public items are to be defined before private ones. Pre-defined functions (generally pre- and post-fixed with two underscores, like init) are defined before all others.

the order should be logical (e.g. called functions after calling ones) rather than lexical.

in class definitions, variables are defined before class methods, before instance methods (each in the order defined above).

assert statements should be used only sparingly, and only for validating internal function calls. Code must continue to work with asserts disabled.

assert statements shall not be used to validate user inputs or system consistency (e.g. if a backup repository is corrupt or not).

all used assert statements must have an explanatory text. It should explain why it went wrong rather than the test result itself.

longer assert statements use parentheses and not backslashes to go over multiple lines, e.g. assert (condition), ("text {hold}".format(hold=var)).

assert messages should only appear during coding, assert messages visible to users are candidate for replacement through a proper fatal error handling.

assert messages might not need translation in the future, as they shouldn’t be seen by users, but still follow the "TEXT OUTPUT" conventions.

any text output starts with a capital letter and does not end with a dot.

text output with variables is formatted with named placeholders using the form "Some message regarding broken object '{bo}'".format(bo=actual_var). This simple example highlights a few important rules:

each text string is a one-liner not starting with the severity level (error, warning, etc), leaving the formatting to the log.Log class.

the explanation is meant first for the user, and explains ways to solve the potential issue, then for the developer to troubleshoot.

Paths and commands are expressed in bytes to avoid issues with cross-platform encoding conversion, any function manipulating such things must return bytes.

Only methods creating a Path/Command object (init and similar) might accept strings as input and convert them internally to bytes. Other functions must make sure that they don’t accept strings as input (this is one of the few reasons to use asserts).

Any conversion between strings and bytes happens with os.fsencode/fsdecode.

Messages are to be expressed in strings (log, errors, etc).

docstrings are quoted with three double quotes (see above).

each triple quotes are alone on their line (this is a deviation from some recommendations) so that it is readable.

each docstring starts with a single line summarizing the purpose of the object.

further descriptions are written after a blank line.

import in such a way that a single module name remains but not the packages from its hierarchy. This means to avoid using imported functions, classes and variables without module’s name in front. For example from package import module or import module, but neither import package.module nor from module import func_or_var_or_class.

acceptable exceptions are standard modules (e.g. os.path) or where the purpose of the import is to wrap the variable/function/class and do as if it would belong to the importing module.

don’t introduce imports only for typing purposes. Introduce such imports only depending on the statement if typing.TYPE_CHECKING:. Also double-quote type hints requiring such an additional import.