Python guidelines

This article provides guidelines for Python code that is easy to understand and maintain.

The target audience are Python developers contributing to one of my projects, be it open source or commercial. It can also be of interest for people who are looking for a basis for their own guidelines.

This document is distributed under the CC BY 4.0 license.

Formatting

• Use a maximum line length of 120. Rationale: The standard 79 just result in a lot of unused space on a 27-inch monitor.
• Use a pre-commit hook that already takes care of most things formatting, typically by using tools like black, isort and others.

As a starting point for your own pre-commit hook, you can use pygount's .pre-commit-config.yaml.

Naming

• In general, use the PEP8 naming conventions. Concerning upper/lower/camel/snake case, they are a mess, but almost every Python projects conforms to them, therefor consistency trumps reason.

  • Exception: For package names consisting of multiple words, use an underscore (_) to separate them.

    Rationale: The pain of garbled, illegible packaged names is just too much.

• For acronyms treat only the first character as upper case.

  • DO: XmlParser
    DON'T: XMLParser
  • DO: parse_xml
    DON'T: parse_x_m_l