Python Coding Style Conventions¶
1. Whitespace¶
1.1. Indentation¶
- Lines should be indented with a multiple of 4 spaces depending on indent level
- Hanging indents, code that is a continuation of the line above, should be indented to the next level
- Use spaces exclusively, no tabs!
1.2. Blank Lines¶
- Leave 2 blank lines between class definitions and module-level functions
- Leave 1 blank line between methods in a class
- Use blank lines as needed in functions, methods, and modules to visually split up logical blocks of code
1.3. Spaces In Code¶
- Surround binary operators with a space on each side
- Do not include spaces around ‘=’ when used to indicate a default argument or keyword argument
- In all other cases, extraneous spaces are frowned upon
2. Imports¶
- Imports should occur at the top of the module, after any module docstring
- Standard imports (those beginning with “import”) should each be on a separate line. Do not combine imports into one line.
- “From ... import ...”-style imports may be combined together on one line if possible
- Wildcard imports should only be used when absolutely necessary, otherwise only import the modules to be used
3. Code Blocks¶
- Do not use parenthesis in the condition for a code block header unless it would be otherwise appropriate to use parenthesis around that condition
- Do not use any single line code blocks. Even those with a single statement in the body should occupy multiple lines
4. Comments¶
- First and foremost, comments should be up to date and accurate. When updating code, always make sure to update any comments that refer to it
- Comments should be wrapped to 72 characters
- Use plain English sentences with proper spelling and grammar. Strongly prefer complete sentences.
- Single sentence comments need not end in a period
- Clever humor is acceptable on occasion
- Do not merely summarize the code that follows. State its overall purpose, justify its inclusion, or explain quirks that other programmers may need to know
4.1. Docstring Comments¶
- Docstring comments should consist of a short summary line, optionally (but usually) followed by a blank line, then additional paragraphs with further explanation
- All classes and methods should contain a docstring
- Modules should contain a docstring if they serve a purpose other than as a container for a class