2 Python

The below are the most immediate features that your code should have. The recommendations in Effective Python give a more in-depth idea of how to write good python code and align with our recommendations.

2.1 Style guide

The following sections outline conditions on python code produced for sharing.

Spacing

Tabs are illegal. All indentation should be in spaces and each level of indent should be either 2 or 4 spaces, but constant throughout the project at either 2 or 4.

import numpy as np


# Good
def main():
  """
    This is my docstring
    There are many others like it
    But this one is mine
  """
  def third_eye(n):
    return 3 * np.eye(n)


# Bad
def main():
  """
    This is my docstring
    There are many others like it
    But this one is mine
  """
  def third_eye(n):
      return 3 * np.eye(n)

Line length

No lines should exceed 80 characters. If you find yourself running out of room on a line then it might be a good sign that you need to write a function.

Blank lines

  • 1 line: There should be one line between blocks of code, the exceptions are where two lines are recommended.
  • 2 lines: Start and end of function definitions, import blocks, headers, and class definitions should have 2 lines clearning them.
# Good
import os


class Goober(object):
  """|
    docstrings are good
    docstrings are great
  """
  def __init__(self):
    pass


def main():
  pass


# Bad
import os
class Goober(object):
  """|
    docstrings are good
    docstrings are great
  """
  def __init__(self):
    pass

def main():
  pass

Data declarations

Elements must align, either in leading or following comma notation. Some examples:

list_1 = [
  elem_1,
  elem_2,
  elem_3
]


list_2 = [ elem_1
         , elem_2
         , elem_3
         ]

List comprehensions

There should be no more than 2 statements included in any list comprehension. If the comprehension is exceeding this length then break it out into a loop or multiple statements. It might make sense to you now but when somebody else comes to read it they will hate you if you don’t.

Exceptions

Do not raise base exceptions. Create your own classes which extend them and manage your errors in a meaningful way.

Imports

Imports should be grouped, at the top of your file and placed in the following order.

  1. standard library imports
  2. related third party imports
  3. local application/library specific imports

Put a blank line between each group of imports and include a comment to show the group. The imports in each group should be sorted alphabetically, by module name. Try to avoid from foo import * unless you can be absolutely certain that there are no clashes in the namespace. It may be more suitable to give your module a short alias, such as import pandas as pd.

It is suggested that the modules are either included in alphabetical order (preferred) or in the order that they appear in the code which follows it.

Type hinting

Where possible use type hinting as perPEP484. It will make your code more verbose as well as easier to debug and handle.

NOTES:

  • This applies to python version 3.5 and later. Type hinting is not available if you have a previous version
  • Type hinting does not enforce typing, it is a means by which you can make code more understandable and easier to debug

2.2 Package Management

Programs should be prepared as packages using one of two methods. First is the python solution virtualenv which allows you to create a ‘clean’ development environment to easier track and list your dependencies. Alternatively, the use of docker, which facilitates a wider use case and means you do not need to handle exceptions caused by windows and linux libraries and executables not being available on the system.

NOTE:

  • Do not place virtualenv content into any online repositories. They are to be used as development environments to handle a ‘clean’ python install allowing you to build a requirements.txt file to incorporate into your package.

2.2.1 Choosing a container

Does your program require applications and functionality outside of your programming language?

  • [ ] Yes Use docker
  • [ ] No Use virtualenv