Automatic Style Formatting

Photos/Images: Clement H
Photos/Images by #WOCinTech/#WOCinTech Chat.

We’ve talked a lot about how to make sure our code works and that it does what we want it to, but just because it works doesn’t mean it’s maintainable!

Code has two “users” - the computer (which turns it into machine instructions) and humans, who will likely read and/or modify the code in the future.

This is why it’s important to make your code suitable to that second audience, humans.

Writing readable and understandable code is important when sharing code to other users and reading back as your future self!

Remember: “Code is read much more often than it is written.”

PEP8

PEP8 is a style guide that recommends formatting such as:

• Indenting using 4 spaces
• Having whitespace around operators, e.g. x = 1 not x=1
• Avoiding extra whitespace such as f(1), not f (1)
• Single and double quotes for strings, but only using “””triple double quotes”””, not ’’’triple single quotes’’’
• Variable and function names using underscores_between_words

flake8

PEP8 is one of the many style guides used in programming.

PEP8 recommends formatting such as:

• Indenting using 4 spaces
• Having whitespace around operators, e.g. x = 1 not x=1
• But avoiding extra whitespace such as f(1), not f (1)
• Single and double quotes both fine for strings, but only using “””triple double quotes”””, not ’’’triple single quotes’’’
• Variable and function names use underscores_between_words

We can check our code to see if it complies with PEP8 formatting using a Python library called flake8.

Think of it as a grammar check but for your code.

flake8 will tell us how and where our code is formatted poorly, but it won’t make any changes to it. That is up to us.

We will show you shortly how to use flake8 in your Jupyter notebooks.

Black

Before black

def exponent_a_list(numerical_list   ,   exponent   =      2):

    if type(numerical_list         ) is    not list   :
                raise Exception(     "You are not using a list for the numerical_list input."   
                )

    new_exponent_list   = list()
    for   number_in_new_exponent_list in              numerical_list:
                new_exponent_list.append(                  number_in_new_exponent_list **  exponent  )
    return new_exponent_list

After black

def exponent_a_list(numerical_list, exponent=2):

    if type(numerical_list) is not list:
        raise Exception("You are not using a list for the numerical_list input.")

    new_exponent_list = list()
    for number_in_new_exponent_list in numerical_list:
        new_exponent_list.append(number_in_new_exponent_list ** exponent)
    return new_exponent_list

Unlike PEP8, which is a style guide, and flake8 which just tells you where your code needs changes, black is a tool that will format your code.

black will mostly follow the PEP8 style guide but with a few differences.

When you use black with your code, you are wiping it of bad formatting like trailing whitespace and poor indentation.

After black

def exponent_a_list(numerical_list, exponent=2):

    if type(numerical_list) is not list:
        raise Exception("You are not using a list for the numerical_list input.")

    new_exponent_list = list()
    for number_in_new_exponent_list in numerical_list:
        new_exponent_list.append(number_in_new_exponent_list ** exponent)
    return new_exponent_list

Checking with flake8 again

It’s important to know that flake8 and our formatter black are using slightly different rules. Even after black is run on our code, flake8 still may point out issues and complain that it isn’t stylized correctly.

We’re not going to worry about that for now. It can be fixed by customizing flake8, but that’s outside the scope of this course.

Now let’s see how we can use both of these in a Jupyter notebook.

Now that you know a little bit about what flake8 and black can do let’s see how we use them.

Here is a blank Jupyter notebook with the exponent_a_list Python script that you saw in the last section.

This time, our exponent_a_list() function is not as it was formatted before.

We’ve got space and indentation issues, and it looks like we are missing white space in areas as well.

First let’s see if the exponent_a_list() function works.

I’ve got this empty notebook that we need to add a new cell to.

We can do so by clicking the + button in the toolbar.

By default, it will add a code type cell to the notebook, but what if we want a text cell?

All we have to do is click on markdown in the toolbar, and it will change to a text cell.

Let’s import our function using the same code Tiffany showed us before.

We specify first from and then the name of the script - in this case, the file name is exponent_a_list, and we follow that with the name of the specific function so exponent_a_list again.

Next, we run it, and it looks like it’s imported into our notebook.

Let’s test out the function exponent_a_list() with a list containing the values 1, 3, and 7.

We are intentionally not adding spaces between the comma so that we can use it as a formatting example shortly.

The function works even with the bad formatting but let’s make our code more readable for our human user now.

Instead of doing everything ourselves and going line-by-line to check our code, we can use flake8 to tell us exactly what we need to fix.

By clicking on the addition sign on the top left of the toolbar, we can access the Launcher, where we can open our terminal.

To use flake8 in the terminal, all we have to do is type flake8 followed by the name of the file we want to check; in this case, exponent_a_list.py.

This produces an output of all the formatting issues we need to amend.

We can see that at line 1, column 45, we have multiple spaces before the operator, which means in our that’s where we will need to make changes in the file exponent_a_list.py.

We can then go through all of these suggestions and correct them so that our exponent_a_list.py is adhering to a cleaner style.

Not only can we check Python scripts but notebooks files as well!

In our terminal, we write something a little different.

We type flake8-nb followed by the name of the notebook:

flake8-nb example.ipynb

example is the name of the notebook, and Jupyter notebooks end with .ipynb.

We can see in this case that flake8-nb caught the missing white space after the commas in our code exponent_a_list([1,3,7) inside the notebook.

Not only can you check flake8 in a terminal, but you can check it in a Jupyter notebook as well.

This time I’m going to run flake8 but in a code cell in our example notebook.

We write almost the same thing we did in our terminal except for this time; we precede the code with an exclamation mark:

!flake8 exponent_a_list.py

Now we see all the formatting flags in our notebook instead of our terminal.

We could go through all the issues one by one and fix them individually, or we can use black which does this (well, most of it) for us.

Just like flake8, we can do this in the terminal or in our Jupyter notebook.

Let’s first try it in a Jupyter notebook.

We can use the exclamation mark followed by black and then the file name so in this case:

!black exponent_a_list.py

Before pressing enter and running this, let’s look at the file first.

We can see that the code in the exponent_a_list.py is still looking pretty messy.

Now we can run this cell, and we get the output:

reformatted are exponent_a_list.py. 
All done!  ✨ 🍰 ✨
1 file reformatted

When we open up the file exponent_a_list.py, we can see that a lot of the white space has been removed, and the indentations have been fixed!

Remember, it’s not perfect! We can still see blank lines here that probably shouldn’t be, but it does a pretty good job.

Now that we’ve done it in a Jupyter notebook, let’s try it in our terminal.

We do the same thing as in a Jupyter notebook, but this time without the exclamation point.

Black exponent_a_list.py

This time this file has also already been formatted, so the output now is

All done!  ✨ 🍰 ✨
1 file unchanged

One last quick tool that we want to show you is this black Jupyter notebook extension. This lets you format your code cells in your Jupyter notebook directly.

All you have to do is right-click on the cell you want to format and press “format cell”.

It will formats your cell right away.

So that is how you can use flake8 and black to clean up your code.

Remember, these tools don’t do everything.

You’ll learn about some of the things that black and flake8 don’t pick up in the next section.

Let’s apply what we learned!