Write clean Python code using pylint and black

First encounter

The very first time I encountered linters and style formatters for Python was during this year's Hacktoberfest. My CI/CD runs kept failing for one particular pull request on GitHub due to errors on black, isort, gitlint. Multiple times. The code was working, but why were my CI/CD runs failing so many times? You can read all about the CI/CD nightmare in this blog. I was frustrated and questioned the need for such checks. Now, I have studied all about pylint to integrate it into my static site generator - rwar. I understand how important it is for code to go through such checks to help spot silly errors that programmers often make and keep the code bug free in the long run, especially when many programmers are working on one big project. Imagine it this way, while typing things on a word document we almost always use a spellchecker to catch typos. Similarly, linters help us catch those silly errors that might snowball into a bigger problem if not addressed on time. They put quality control checks in place. Plus, linters are customizable, allowing us to set rules for the checks we want for our code.

What is pylint

pylint is a tool that checks for errors in Python code, enforces a coding standard, and checks for bad code smell, giving us immediate feedback about our code. After analyzing the code it gives an overall score out of 10 along with errors in the file. Honestly, this was really fun for me to see all the possible ways I could make my code better. I, then, went through each of the warning messages to fix them all.

However, it is important to note that:

"What Pylint says is not to be taken as gospel and Pylint isnt smarter than you are: it may warn you about things that you have conscientiously done." (source: pylint docs)

The errors: Before fixing the score was 9.35/10

After fixing, the score was 10/10

To install pylint I had to first:

pip install pylint 

To run pylint on my project I typed in pylint ./rwar.py ./src/

The .pylintc file

pylint requires a .pylintrc file for configuration. While I am no expert at writing out .pylintrc files, I did a little bit of googling to find good .pylintrc files that reside on the internet. Then I copied it and slightly modified it for my project.

What is black

black is a great tool for formatting your Python code automatically, while you give full attention to the logic of the code.

To use black I first had to install it by

pip install black 

After that you specify black filename.py in the terminal and black automatically formats your code. As shown below when I ran black on rwar.py file, it reformatted everything according to the PEP8 standard.

Integrating to VSCode

While black can be installed in many different IDEs, I personally love and use VSCode.

Open your VSCode settings, by going Code -> Preferences -> Settings.

Search for 'python formatting provider' and then select 'black' from the drop down menu:

After that search for 'format on save' and enable the "Editor: Format On Save" option

Now, everytime you save, the code will be automatically formatted.

The Contributing.md file

The CONTRIBUTING.md file for my project contains information regarding the linters and formatters used for my project and ways to install them with useful links to its documentation. As I improve my static site generator and build it along the way, this file is also going to get bigger.

What's next...

I had fun experimenting with black and pylint. Next, I am going to install a pre-commit hook to my project. I tried to get it done this week but had some setbacks with lots of errors while attempting to install it. By investing a little bit more time in it, I believe I can get the pre-commit hook, up and running before my next weekly blog on this python project story series. The second thing, I am going to experiment with before the next blog would be adding a virtual environment for Python.