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:
class HelloWorld {
public static void main(String[] args) {
System.out.println(“Hello, World!”);
}
}
While in Python, it looks like this:
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.
There are languages with even simpler syntax and learning curves, Lisp and Smalltalk are great examples. Even Ruby on Rails can fit the constraints.
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).
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 😛. 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.
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. The Hitchhiker’s Guide to Python 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 of Python guidelines used in an open-source project, 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.
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,
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.
pip install pycodestyle
pycodestyle test.py
Output:
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 and run the following commands. I am planning to make a cheat sheet for this soon as well, stay tuned.
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.
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:
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?
autopep8 -i -v -a test.py
Output:
Clearly so much has changed, this shows how flexible auotpep8 actually is, but there is even more.
By stacking multiple -a,
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:
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:
yapf -i -vv test.py
-i or --in-place flag make changes to files in place, and -vv or --verbose is for verbose messages.
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.
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:
black test.py
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.
- For exclusive Tech Posts, check my Dev Profile.
- Go through my GitHub, you might find something interesting.
Vybhav Chaturvedi, Over and Out.
Top comments (4)
I get it! Maybe i failed to convey my point correctly here, People use Python because they think the Syntax is way easier and hence should be a go-to language for everyone. This is not wrong actually but is not what Python stands for. The comparison between Java and Python is meant to showcase what we actually perceive is the biggest benefit of Python vs what the actual benefits are.
I will keep this in my mind for next for sure.
And I definitely agree Python many a time could be way complicated.
If am not wrong Python uses
autopep8only, with some additional customizations available.Black definitely allows some changes as I stated explicitly but compared to others is way more strict (that's the whole point of Black anyways).
Thanks for the suggestion, I would try to incorporate your suggestions next time and would work on my writing skills.
I wrote everything from a beginner's perspective and not going to lie, it makes blogs needlessly lengthy. Actually what inspired me to write this article was the DeepSource code analyzer I have in one of my Repos, and most new contributors always are terrified about failing checks in the Pull Requests because of unstructured code. I think auto formatters would be actually a good tool for them to use and would cause me lesser headaches as well, as I can expect some better quality code.
Definitely, Kotlin is love, I just started playing around with it, it's fun. Don't get me wrong, Java being the first language I learned, is one of my favs.
Also, check out our styleguide: github.com/wemake-services/wemake-...
It is pretty strict!
Looks like a good CI tool.
Might use it with a few of my Projects.