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