Beginners Guide to Auto Formatting
Tags: python, tooling, beginners, productivity
Published: 2021-03-28 17:41:56

Everybody loves Python! (mostly). But why? I asked many programmers across my network (Trust me, I did!). And the most pronounced response was its high readability, simple syntax, and similar Pythonic traits. Indeed, a high level of readability was on the top of the mind of **Guido van Rossum** as he developed Python.

Let’s take a small example. The staple of all programs, the infamous **“Hello World!” program** in Java, looks like this:

```java
class HelloWorld {
    public static void main(String[] args) {
        System.out.println(“Hello, World!”); 
    }
}
```

While in Python, it looks like this:

```py
print(‘Hello, world!’)
```

Looks simple right? Even better examples, like opening and appending files in Python, are comparatively more straightforward and less taxing than other languages.

But before proceeding, let’s make a few things clear.

1. There are languages with even simpler syntax and learning curves, Lisp and Smalltalk are great examples. Even Ruby on Rails can fit the constraints.

1. Even though it is simple, Python is not THE best programming language; there is NO best programming language. There are languages which you know, you love it and sharpen your skills using them, and there are languages which you don’t know and might learn someday own the line. (PHP is an exception, you never want to practice PHP).

1. There are beginner-friendly languages, Python is one of them, but I don’t think it’s a good description.

Programming languages are situational, to say the least; it depends upon what you want to achieve, how you want to achieve, and when you want to achieve.

_________________________________________________________________

## Python Styling Guidelines

Now with that out of the way, let’s talk about why Python is so great :stuck_out_tongue:. So, like previously mentioned, is it the easy syntax? Higher flexibility? Or something else? Well actually the big picture is a little bit different. Python was developed with a high level of readability in mind, it’s the idea **that code is read much more often than it is written**, and this is where everything glues together. 

Python is good because it is easier to **read and comprehended**, sure it means that writing is more accessible. But writing is not the idea behind Python, it’s **reading the code**. The easier syntax does make it easier to write the programs, but the true purpose they serve is to the readers and reviewers, other benefits are just cherry on top. For that very reason, Pythonistas follow a set of guidelines, a.k.a. “Pythonic” idioms. But why am I talking about this? It is evident that Python is flexible and easy to read/write; a lot of people are attracted to writing programs in Python, but what they forget is the styling part of Python, and hence the result is a poorly formatted code, which don’t get me wrong, still works fine but isn’t what Python is actually meant for. This tweet summarizes the Styling part really well.

![tweet](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/40ahsvkhevvpx87ugv3j.png)

_________________________________________________________________
_________________________________________________________________

### PEP-8

In a nutshell, we have some not-so-strict styling guidelines for Python. Ummm NO. Actually, the procedures are very strict, adequately formatted, and universally accepted; just the problem is that beginners don’t abide by them, and with time it becomes habitual.

**PEP-8 is the de facto code style guide for Python.** It should be strictly followed and mandatory in top projects such as “Flask”, “Tensorflow” etc.

A well-documented version of the guidelines can be found [here](https://pep8.org/). The [Hitchhiker’s Guide to Python](https://docs.python-guide.org/writing/style/) is my go-to version of guidelines for properly formatted code.

If you are a beginner and want a simpler take on PEP-8 guidelines, I have prepared my [own version](https://github.com/HarshCasper/Rotten-Scripts/blob/master/Python/CONTRIBUTION-GUIDELINE.md) of Python guidelines used in an open-source project, [Rotten-Scripts](https://github.com/HarshCasper/Rotten-Scripts). This is way more beginner-friendly but also aligns with the mandatory guidelines of PEP-8.

_________________________________________________________________

## Auto Formatting

Now let’s address the elephant in the room; Have you just started coding in Python, and these guidelines seem way too much? Are you a seasoned pro, but PEP-8 guidelines still overwhelm you at times? There is a simple solution for all this, **Auto Formatting**. Before getting into Auto Formatting, _it should be clear that the tools mentioned below can just act as an aid,_ and one should try to learn the guidelines, and one should be able to write good quality code without using any tool.

Several auto-formatting tools can reformat your code to comply with PEP-8.
We will discuss 3 of my favorites.

* [autopep8](https://pypi.org/project/autopep8/)
* [yapf](https://github.com/google/yapf)
* [black](https://pypi.org/project/black/)

But before discussing auto-formatting, one question pops up in mind; What if my script is already looking good and everything is working correctly? For example, take this python script, 

![Test Script](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hyz9yv93e397azytewcp.PNG)

It looks horrible but is working correctly, now I know that this is a rather extreme example, but it serves the purpose here. Before anything, we need to determine what are the discrepancies in our code. For this, we will use `pycodestyle`, previously known as `pep8`.

```bash
pip install pycodestyle
pycodestyle test.py
```

Output:

```py
test.py:1:12: E401 multiple imports on one line
test.py:1:17: E703 statement ends with a semicolon
test.py:3:1: E302 expected 2 blank lines, found 1
test.py:4:5: E265 block comment should start with '# '
test.py:4:80: E501 line too long (135 > 79 characters)
test.py:5:15: E225 missing whitespace around operator
test.py:5:17: E201 whitespace after '('
test.py:5:21: E231 missing whitespace after ','
test.py:5:26: E231 missing whitespace after ','
test.py:5:31: E202 whitespace before ')'
test.py:5:33: E703 statement ends with a semicolon
test.py:6:18: E225 missing whitespace around operator
'
'
'
```

As expected there are a lot of problems here, this code is nothing short of a nightmare for a debugger and/or reviewer. Now we can start playing around using the autoformatting tools mentioned above. I won’t be discussing the detailed workings of these tools, as they have proper documentation, multiple options, and configurations for helping you out. Instead, we will be focusing on some hands-on implementation of the formating tools to provide a good starting ground.

So, let’s start by downloading the required packages. I personally prefer to make separate virtual environments for these tools, validate a copy of my scripts in that virtual environment, and simply do the changes in the original scripts. You can do the same by [setting up a virtual environment](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) and run the following commands. **I am planning to make a cheat sheet for this soon as well, stay tuned.**

```bash
pip install yapf black autopep8
```

After downloading all the required packages, let’s use all the formatting tools one by one and see how they can help us. All the tools follow similar steps and provide matching options but can still offer different results. Just ensure that you are in the directory in which your scripts are.

_________________________________________________________________

#### Autopep8

**Autopep8**, Just like its name, it automatically formats Python code to conform to the PEP-8 style guide. A simple hands-on approach autopep8 is widely regarded for its flexibility and customization. To correct your file, use the following command.

```bash
autopep8 -i -v test.py
```

`-i` or `--in-place` flag make changes to files in place, and `-v` or `--verbose` is for verbose messages.

Output:

![Test Script after autopep8](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ikcczqxzcyi4mtnrgom8.PNG)
 
Look at that, way better! But wait, there is more. The good thing about `autopep8` is, it allows aggressive changes as well. By using `-a` or `--aggressive` flag, `autopep8` aggressively formats the code, enabling non-whitespace changes. Let's see this in action, shall we?

```bash
autopep8 -i -v -a test.py
```

Output:

![Test Script after autopep8 aggressive](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1o79djf7lvq2rbky1c7g.PNG)

Clearly so much has changed, this shows how flexible `auotpep8` actually is, but there is even more.

By stacking multiple `-a`, 

```bash
autopep8 -i -v -a -a -a test.py
```

even more aggressive changes can be forced. After using the aggressive flag multiple times, this is what the file looks like.

Output:

![Test Script after autopep8 aggressive 3 layers](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/okf5k0ohrbj6gwvzs1jn.PNG)

3 level of aggressive changes in my opinion is a bit of overkill and solves most of the purposes.

_________________________________________________________________

#### YAPF

**YAPF** is a project by Google is a rather advanced auto-formatting tool and can even beautify code that follows PEP-8 guidelines to make it look even better. The approach is similar to `clang` and `gofmt`, in order to auto-format a file, use the following command:

```bash
yapf -i -vv test.py
```

`-i` or `--in-place` flag make changes to files in place, and `-vv` or `--verbose` is for verbose messages.

![Test Script after yapf](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/zh14psmigy3j4fdiebis.PNG)

`yapf` allows you to format the code according to Google and Facebook guidelines as well; by using `style google` or `style facebook` scripts can be reformatted according to the prescribed styling guidelines.

```bash
yapf -i -vv test.py style google
```
_________________________________________________________________

#### Black

**Black** is the most-loved and/or most-hated formatter (depends on how you look at it), a truly uncompromising formatter, refactoring the code to its minute details, black results in a faster, more optimized code. Its uncompromising nature can result in scripts utterly different from the original ones and is many a time considered an overfill. In order to use black, use the command:

```bash
black test.py
```

![Test Script after black](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sflnyh6t7pu4rrf80clw.PNG)

Notice the shift from single to double quote, extra blank lines, etc. Black incorporates multiple changes that can completely change the way a script looks like.
_________________________________________________________________

Coming back to my early statement, _`Black` is the most-loved and/or most-hated formatter_, **how?** `Black` provides nearly **No**, and by that, I mean no customization; it is truly uncompromising. There are definitely things that can be changed, but the fact that Black is a simple nonconfigurable tool still holds true. A common argument is that the "best tools do not need any configurations"; this might hold true for `gofmt` (a similar auto-formatting tool for Go) but Python is not Go. A lot of people still love using `Black`. **“Black is opinionated, so you don’t need to be.”** sum everything up pretty well.

Other tools like `autopep8` and `yapf` provide much more configurations and customizations, but that part is out of this article’s scope.
_________________________________________________________________
_________________________________________________________________

### Why no Auto Formatter?

There are reasons why you should not use Auto-Formatter, like the unnecessary clutter that Black introduces in the output of `git blame`, but since the newer versions of git, these problems have been solved, and tools support ignoring revisions, so its no longer an issue.

### My Final Take

`Black`, `yapf`, and `autopep8` are some great tools, but personally, `autopep8` is my go-to auto formatter with a `flake8 linter` (What is a linter? Wait for my next blog, maybe :P) and `Travis` for test cases and continuous integration.

## Bottom-line:

Auto format tools like `yapf`, `autopep8` and `black` are just **options, not solutions**. Ultimately you should strive to learn the guidelines yourself as they are the heart and soul of Python. In case you are contributing to open-source projects, tools like these help a lot. Every maintainer loves good clean code. Always remember, _it is not enough for code to work if you want, So if you want to go fast, if you want to get done quickly, if you want your code to be easy to write, make it easy to read._

Like I said earlier, **I am planning to make a cheat sheet for this soon as well, stay tuned.**

_________________________________________________________________

Liked what you read? I have restarted blogging after a long time; I talk about multiple stuff (Football, Anime, IoT, Music, Human Emotions, to name a few). You can follow me on my socials if you want.

_________________________________________________________________

* Let connect; I love to get in touch with people who have a similar mindset, my [LinkedIn](https://www.linkedin.com/in/vybhav-chaturvedi-0ba82614a/).
* For **exclusive Tech Posts**, check my [Dev Profile](https://dev.to/vybhav). 
* Go through my [GitHub](https://github.com/vybhav72954), you might find something interesting.

_Vybhav Chaturvedi_, Over and Out.

_________________________________________________________________
_________________________________________________________________