Python has its own style guide, called PEP 8, since 2001 [1]. It was written by Guido van Rossum (the creator of Python) and others and gives coding conventions for the Python code comprising the standard library in the main Python distribution [1]. Probably because it is used for the standard library and by the creator of Python, no alternative style guides were found. PEP 8 is the de facto code style guide for Python [2].
PEP stands for Python Enhancement Proposal. A PEP is a design document providing information to the Python community [3]. Other style related PEPs are:
- PEP 7 — Style Guide for C Code [4]
- PEP 20 — The Zen of Python [5]
- PEP 257 — Docstring Conventions [6]
PEP 8 and PEP 257 (Docstring Conventions) were adapted from Guido’s original Python Style Guide essay, with some additions from Barry’s style guide [1]. A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition. Such a docstring becomes the doc special attribute of that object [6].
Triple quotes are used for both One and Multi-line Docstrings. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description [6].
PEP 8 follows the guiding principles for Python’s design known as PEP 20 “The Zen of Pyhon” [5]. The guiding principles for Python’s design are channeld into 20 aphorisms, including:
- Explicit is better than implicit.
- Simple is better than complex.
- Readability counts.
- Special cases aren’t special enough to break the rules.
- Errors should never pass silently.
PEP 8 includes the following topics:
- Code Lay-out
- String Quotes
- Whitespace in Expressions and Statements
- When to Use Trailing Commas
- Comments
- Naming Conventions
- Programming Recommendations
Some of the rules are:
- Use 4 spaces per indentation level.
- Limit all lines to a maximum of 79 characters.
- Break a line before a binary operator.
- Avoid extraneous whitespace:
- Immediately inside parentheses, brackets or braces.
- Immediately before a comma, semicolon, or colon.
- Class names should normally use the CapWords convention.
- Function and variable names should be lowercase, with words separated by underscores.
- Constants are usually defined on a module level and written in all capital letters with underscores separating words.
When developing PyQt applications however, there is a slight conflict with the Qt style and Python style syntaxes. Python prefers to lowercase, underscored functions, while Qt prefers to camel hump functions [7]. The PEP 8 document says what to do in this case: “New modules and packages (including third party frameworks) should be written to these standards, but where an existing library has a different style, internal consistency is preferred.” So, while you may be programming in Python, you’re creating Qt classes – inheriting their conventions along the way [7].
Tools that can help to enforce PEP 8 compliance can be divided into two classes: linters and autoformatters [8]. Linters are programs that analyze code and flag errors. Examples are pycodestyle [9], flake8 [10], and Pylint [11]. Autoformatters are programs that refactor your code to conform with PEP 8 automatically. Examples are Black [12], autopep8 [13], and yapf [14].
There is also a static analysis tool for checking compliance with Python docstring conventions (PEP 257), called pydocstyle (formerly pep257) [15].
- PEP 8 — Style Guide for Python Code
- The Hitchhikers’s guide to Python
- PEP 1 — PEP Purpose and Guidelines
- PEP 7 — Style Guide for C Code
- PEP 20 — The Zen of Python
- PEP 257 — Docstring Conventions
- PyQt Coding Style Guidelines
- How to Write Beautiful Python Code With PEP 8
- pycodestyle
- flake8
- Pylint
- Black
- autopep8
- yapf
- pydocstyle