Getting started with conventions in Python

References:

• Software Engineering for Data Scientists in Python (Datacamp)
• https://sphinx-rtd-tutorial.readthedocs.io/
• https://realpython.com/

PEP 8 Cheat sheet: https://cheatography.com/jmds/cheat-sheets/python-pep8-style-guide/

If you are a data scientist and would like to write a proper and high-quality script, I highly recommend that you should follow a strictly standard guideline for yourself in order to reduce complexity, become more readable, and make maintenance easier. Here are some tips commonly used for Python scripts:

1. First check PEP 8 by pycodestyle/flake8/black

The PEP 8 provides a standard style in Python. You can check whether your scripts follow the PEP 8 convention with multiple python files by pycodestyle:

import pycodestyle
style_checker = pycodestyle.StyleGuide()  # a StyleGuide instance
style_checker.check_files(['file1.py', 'file2.py'])  # PEP 8 check

Also, we have the Flake8 displaying all warnings in your files. Flake8 is a wrapper tool which combines a debugger, pyflakes, with pycodestyle. Make sure you have installed the Flake8 on your correct Python version. You can open an interactive shell and run:

$ flake8 file.py

What happens if your code violates the PEP 8? Are you going to fix all by hand? Don’t worry, Black is an autoformatter which allows you to identify PEP 8 errors and fix them automatically. Notice that Black sets the limit on the maximum characters to 88 by default, but we can change to 79 as per the PEP 8 guideline:

$ black --line-length=79 file.py

2. Naming

We are now familiar with common terms in Python such as variable, function, class, module, and package. You should follow the naming style as below:

Table 1: Naming conventions in Python

3. Blank lines

• top-level functions and classes with two blank lines

class FirstClass:
    pass

class SecondClass:
    pass

def function():
    return None

• method definitions inside classes or between two functions with a single blank line

class MyClass:
    def first_method(self):
        return None
    
    def second_method(self):
        return None

4. Refactoring code

You should refactor longer functions into smaller units, which improves both readability and modularity. For example, you can break down this code

def polygon_area(n_sides, side_len):
    """Find the area of a regular polygon

    :param n_sides: number of sides
    :param side_len: length of polygon sides
    :return: area of polygon

    >>> round(polygon_area(4, 5))
    25
    """
    perimeter = n_sides * side_len
    apothem_denominator = 2 * math.tan(math.pi / n_sides)
    apothem = side_len / apothem_denominator

    return perimeter * apothem / 2

into 3 smaller functions:

def polygon_perimeter(n_sides, side_len):
    return n_sides * side_len
def polygon_apothem(n_sides, side_len):
    denominator = 2 * math.tan(math.pi / n_sides)
    return side_len / denominator
def polygon_area(n_sides, side_len):
    perimeter = n_sides * side_len
    denominator = 2 * math.tan(math.pi / n_sides)
    apothem = side_len / denominator
    return perimeter * apothem / 2

5. Comments (only displayed for yourself and collaborators):

• Use complete sentences with a capital letter
• 72 maximum characters
• Start each line with a # followed by a single space
• Separate inline comments by two or more spaces from the statement

6. Docstrings (for users)

"""[Summary]
:param [ParamName]: [ParamDescription]
:type [ParamName]: [ParamType](, optional) 
...
:raises [ErrorType]: [ErrorDescription] 
...
:return: [ReturnDescription]
:rtype: [ReturnType] 
:Example:
.. note:: can be useful to emphasize 
            important feature
.. seealso:: :class:`MainClass2` 
"""

7. Length

• 79 maximum characters
• Can use backslashes to break lines
• Break lines before the operator

from mypackage import module1, \
    module2, module3
def function(arg_one, arg_two,
             arg_three, arg_four):
    return arg_one

8. Whitespace around operators

• Assignment operators (=, +=, -=, and so forth)
• Comparisons (==, !=, >, <. >=, <=) and (is, is not, in, not in)
• Booleans (and, not, or)
• More than one operator in a statement: Adding a single space before and after each operator can look confusing. Instead, it is better to only add whitespace around the operators with the lowest priority. You can also apply this to if statements where there are multiple conditions

# Recommended
y = x**2 + 5
z = (x+y) * (x-y)
# Not Recommended
y = x ** 2 + 5
z = (x + y) * (x - y)
# Recommended
if x>5 and x%2==0:
    print(x)
    
# Not recommended
if x > 5 and x % 2 == 0:
    print(x)

9. Line up the closing brace/bracket with the first character of the line that starts the construct

list_of_numbers = [
    1, 2, 3,
    4, 5, 6
]