Python code formatting

Introduction

Python, or rather its most famous representative of CPython, is not very designed for any quick calculations. In other words, his performance is not so good . But the speed of development and readability is excellent.

Readability will be discussed, but rather how to increase it.

Formatting Issues

Ideal code formatting does not exist. For each language, it is worth adapting to the generally accepted rules for code design. What can I say, if among the newcomers to C ++ there are still wars about putting brackets on the next line or not.
For python, the main formatting issue is the “C style”. It’s not uncommon for people to come to the language in question from C-like languages, but it’s common for them to write with the characters “) (;".
Symbols are not the only problem, there is also the problem of redundant construction of constructs. Python, unlike Java, is less verbose and It takes a lot of time for beginners to get used to it
, these are the two main problems that are most often encountered.

Standards and guidelines for design

If different approaches can be used to increase the speed of code execution , although these approaches are very individual, then there is a direct slyle guide for text formatting - this is pep8. Further I will call it “standard”.
You can read about the standard here , in Russian you can here
Pep8 is very extensive and allows the programmer to write REALLY readable code.

It includes:

• maximum length of lines of code and documentation
• source code encodings
• recommendations on how to make comments
• conventions for naming functions / classes, arguments
• and much more

In general, it covers many code formatting rules. However, it is worth noting that not all python programmers comply with these rules.
Large companies, such as Google, have their own recommendations for writing python code, you can read them here and here .
Very interesting reading, I recommend.

Automate formatting

If you look at how many rules there are in pep8, then you can sit down for refactoring for a long time. That's just lazy, and when writing new code, there will be some kind of rule errors. To do this, consider how you can simplify your life.

pep8

In order to have an idea of ​​how many design errors are in the code, it is worth using the pep8 utility .
It has a sufficient list of parameters that allows you to recursively view all the files in folders for compliance with the pep8 standard.
The utility output is something like this:

$ pep8 --first optparse.py
optparse.py:69:11: E401 multiple imports on one line
optparse.py:77:1: E302 expected 2 blank lines, found 1
optparse.py:88:5: E301 expected 1 blank line, found 0
optparse.py:222:34: W602 deprecated form of raising exception
optparse.py:347:31: E211 whitespace before '('
optparse.py:357:17: E201 whitespace after '{'
optparse.py:472:29: E221 multiple spaces before operator
optparse.py:544:21: W601 .has_key() is deprecated, use 'in'

From it you can clearly understand: where is the error and what happened.

autopep8

Standard errors are often repeated from file to file. And there is a strong desire to automate the correction. In this case autopep8 enters the arena .
Like pep8, it can independently detect errors, as well as correct them. A list of correctable formatting errors can be found here.
Using autopep8 itself is extremely simple and might look like this:

$ autopep8 ./ --recursive --in-place -a

After executing this command, the utility will recursively go through the subfolders and start fixing the errors in the files themselves.

autoflake

You can go further and take autoflake as a weapon . This utility helps to remove unused imports and variables.
Used like this:

$ autoflake --in-place --remove-all-unused-imports --remove-unused-variables -r ./

This will recursively clean the files in the directory.

unify

The final, final point in code editing is the lines. Someone likes to write them in single apostrophes, someone in double. That's just for this, there is the recommendation, as well as a utility that allows you to automatically brought into line - unify
Usage:

$ unify --in-place -r ./src/

As elsewhere, the utility will do its dirty job recursively for files in a folder.

docformatter

All the time we are talking about the code itself, and comments have never been discussed. The time has come - docformatter . This utility helps bring your docstring under a PEP 257 agreement . The agreement prescribes how to draw up documentation.
Using the utility is no more complicated than the previous ones:

$ docformatter --in-place example.py

Can you all be together?

The utilities are described above, their launch, you can add some bash script under the magic name clean.bash and run it. Or you can go the other way and use wrapper over these utilities - pyformat

conclusions

Python code is easy to read, however, there are ways to make noodles out of readable code too.
In this article, some problems of code design, as well as ways to find these problems, were voiced. Several utilities were considered that allow you to automatically remove some flaws in the design of the code.
It is worth voicing out loud the following recommendation when writing code that is universal for any language: a more important design rule than similar pep8 documents is the constancy of style. You’ve chosen what style you will write the program in, and write all the code in the same.

If readers are interested, then in the next article I will describe how to automatically search for errors in the code.