Our Blog
When you develop a program in a group of programmers, it is really important to have some standards. Especially helpful are standards of naming things and formatting code. If all team members format the code in the same way and use consistent names, then it is much easier to read the code. This also means that the team works faster.
The same rules apply when you develop software in Python.
For Python there is a document which describes some of the most desirable style features for Python code Style Guide for Python Code. However there are some problems with that, as even the standard Python library has some libraries which are not consistent. This shouldn’t be an excuse for your team to be inconsistent as well. Ensuring that the code is nice and readable is worth working for a moment on that.
In Python there are two tools which I use for writing code in Python—Python style guide checker and Python code static checker.
Program pep8 is a simple tool checking Python code against some of the style conventions in PEP 8 document.
Installation
You can install it within your virtual environment with simple:
Usage
Let’s test the pep8 command on such an ugly Python file named test.py:
The basic usage of the program is:
The above command prints:
Configuration
Pep8 is highly configurable. The most important options allow to choose which errors should be ignored. For this there is an argument –ignore. There is also one thing in PEP8 document, which I don’t agree with. This document states that the length of the line shouldn’t be bigger than 80 characters. Usually terminals and editors I use are much wider and having 100 characters doesn’t make your program unreadable. You can set the allowed length of your line with –max-line-length.
So if I want to ignore the errors about empty lines at the end of file and set maximum line length to 100, then the whole customized command is:
The output is different now:
Config file
The same effect can be achieved using a config file. PEP8 searches for this file at the project level, the file must be named .pep8 or setup.cfg. If such a file is not found, then it looks for a file
/.config/pep8. Only the first file is taken into consideration. After finding a file, it looks for a pep8 section in, if there is no such section, then no custom settings are used.
To have the same settings as in the above example, you can create a file .pep8 in the project directory with the following content:
The list of all all possible errors you can find at PEP8 documentation page.
Statistics
Another nice option which I use for checking the code is –statistics. It prints information about the type and number of problems found. I use it along with -qq option which causes pep8 to hide all other informations. The sort -n 1 -k -r part sorts the pep8 output in reverse order (biggest numbers come first) by first column treating that as numbers:
The first 10 lines of the above command run against Django 1.5.1 code look like:
pylint
Pylint is a program very similar to pep8, it just checks different things. The pylint’s goal is to look for common errors in programs and find potential code smells.
Installation
You can install pylint in a similar way as pep8:
Usage
Usage is similar as well:
Notice there is –reports argument. Without it, the output is much longer and quiet messy.
The output of the above command is:
Configuration
For pylint you can decide which problems should be ignored as well. If I want to ignore some errors, you have to know its number first. You can get the number in two ways, you can check at pylint errors list or add the message number with argument –include-ids=y:
Now I know the number of the problem I want to ignore, let’s assume it is C0103, then I can ignore it with:
Config file
Pylint also supports setting the options in a config file. This config file can be a little bit complicated, and I think the best way is to let pylint generate the file, this can be done with the –generate-rcfile argument:
This will create config file with all default settings and the changes from the command line.
To use the new config file, you should use the –rcfile argument:
Remarks
Pylint is great—sometimes even too great.
I usually ignore many of the errors, as too often the changes needed to satisfy pylint are not worth time spending on them. One of common problems found by pylint is that the variable name is too short. It has a rule that all the names should have between 2 and 30 characters. There is nothing bad with one letter variable, especially when it is something like Point(x, y) or it is a small local variable, something like for i in xrange(1,1000).
However on the other hand when a variable has much broader usage, or it should have some meaningful name to have code easier to read, it is a good idea to change the code.
For me it is good to have pylint checking such errors, so I don’t want pylint to ignore them. Sometimes it is OK to have code which violates those rules, so I just ignore them after ensuring that it is on purpose.
Форматирование Python-кода
Python, точнее его самый известный представитель CPython, не очень предназначен для каких-либо быстрых расчетов. Иначе говоря, производительность у него не такая уж хорошая. А вот скорость разработки и читаемости отличная.
О читаемости и пойдет речь, а точнее как ее увеличить.
Проблемы форматирования
Идеального форматирования кода не существует. Для каждого языка стоит подстраиваться под общепринятые правила оформления кода. Да что говорить, если среди новичков С++ еще до сих пор войны по поводу ставить скобки на следующей строке или нет.
Для python’а основными проблемами форматирования является «C стиль». Не редко в рассматриваемый язык приходят из С-подобных языков, а для них свойственно писать с символами «)(;».
Символы не единственная проблема, есть еще и проблема избыточности написания конструкций. Питон, в отличие от Java, менее многословен и чтобы к этому привыкнуть у новичков уходит большое количество времени.
Это две основные проблемы, которые встречаются чаще всего.
Стандарты и рекомендации к оформлению
Если для повышения скорости исполнения кода можно использовать разные подходы, хотя эти подходы очень индивидуальны, то для форматирования текста существует прям slyle guide — это pep8. Далее его буду называть «стандарт».
Почитать про стандарт можно здесь, на русском языке можно здесь
Pep8 весьма обширный и позволяет программисту писать РЕАЛЬНО читаемый код.
- максимальную длину строк кода и документации
- кодировки файлов с исходным кодом
- рекомендации как правильно оформлять комментарии
- соглашения именования функций/классов, аргументов
- и многое другое
Автоматизируем форматирование
Если посмотреть сколько всяких правил в pep8, то можно сесть за рефакторинг надолго. Вот только это лениво, да и при написании нового кода сиравно будут какие-то ошибки правил. Для этого рассмотрим как же себе можно упростить жизнь.
Дабы иметь представление сколько ошибок оформления в коде, стоит использовать утилиту pep8.
У нее достаточный список параметров, который позволяет рекурсивно просмотреть все файлы в папках на предмет соответствия стандарту pep8.
Вывод утилиты примерно такой:
По нему можно однозначно понять: где ошибка и что случилось.
autopep8
Ошибки стандарта часто повторяются от файла в файлу. И возникает сильное желание исправление автоматизировать. В этом случае на арену выходит autopep8.
Как и pep8, он умеет самостоятельно определять ошибки, а также исправлять их. Список исправляемых ошибок форматирования можно найти здесь
Само использование autopep8 крайне простое и может выглядеть так:
После выполнения данной команды, утилита рекурсивно пойдет по подпапкам и начнет в самих же файлах исправлять ошибки.
autoflake
Можно пойти дальше и в качестве оружия взять autoflake. Эта утилита помогает удалить не используемые импорты и переменные.
Используется примерно так:
Тем самым будут рекурсивно почищены файлы в директории.
unify
Крайний, заключительный момент в редактировании кода — это строки. Кто-то любит их писать в одиночных апострофах, кто-то в двойных. Вот только и для этого существует рекомендации, а также и утилита, которая позволяет автоматически приводить в соответствие — unify
Использование:
Как и везде, утилита выполнит свое грязное дело рекурсивно для файлов в папке.
docformatter
Все время говорим о самом коде, а о комментариях еще ни разу не шло речи. Настало время — docformatter. Эта утилита помогает привести ваши docstring по соглашению PEP 257. Соглашение предписывает как следует оформлять документацию.
Использование утилиты ничуть не сложнее предыдущих:
А все вместе можно?
Выше описаны утилиты, их запуск можно добавить какой-нибудь bash скрипт под магическим названием clean.bash и запускать. А можно пойти и по другому пути и использовать wrapper над этими утилитами — pyformat
Выводы
Python-код легко читается, однако, есть способы сделать лапшу и из читаемого кода.
В данной статье были озвучены некоторые проблемы оформления кода, а также способы поиска этих проблем. Были рассмотрены несколько утилит, которые позволяют в автоматическом режиме убрать некоторые изъяны оформления кода.
Стоит озвучить вслух следующую рекомендацию при написании кода, которая универсальна для любого языка: более важным правилом оформлением, чем подобные pep8-документы — это постоянство стиля. Выбрали в каком стиле будете писать программу, в этом же и пишите весь код.
Если читателям будет интересно, то в следующей статье я опишу как в автоматическом режиме искать ошибки в коде.
running pep8 or pylint on cython code
The neural network library Chainer has a pretty handy flake8 config for Cython:
Installation
Usage as a pre-commit hook
See pre-commit for instructions
Command-line example
-
The Overflow Blog
Related
Hot Network Questions
Subscribe to RSS
To subscribe to this RSS feed, copy and paste this URL into your RSS reader.
Site design / logo © 2023 Stack Exchange Inc; user contributions licensed under CC BY-SA . rev 2023.3.11.43304
By clicking “Accept all cookies”, you agree Stack Exchange can store cookies on your device and disclose information in accordance with our Cookie Policy.
How to make your Wagtail/Django project have good Python coding style
In this Wagtail tutorial, I will teach you how to check coding style for your Wagtail/Django project, how to fix it and how to keep it clean and concise. After reading this article, you will get:
How to check if your Wagtail project follows the PEP8 guidelines.
How to auto fix your Wagtail project to make it follow PEP8 using autopep8
How to organize your Wagtail project import statements using isort
How to check Wagtail project coding style in CI job.
Some great config files and commands which can be used in your Wagtail project directly.
Before you get started, please make sure you are in the same virtualenv as your Django/Wagtail project.
NOTE: You can find all config files in wagtail-bootstrap-blog , I would appreciate that if you could give this repo a star.
PEP8 is a document that provides guidelines and best practices on how to write Python code.
If your Python code is following the guidelines of PEP8, then your Python code would be easy to read and maintain.
Here we use pycodestyle (formerly called pep8) to let it helps us check our Python code.
pycodestyle is a tool to check your Python code against some of the style conventions in PEP 8.
NOTE: pycodestyle might give you different output in different versions, so please be careful to make pycodestyle version number consistent in your project.
Let’s first create a test python file test.py , as you can see, this file has bad coding style and not easy to read.
Now we use pycodestyle to check the above file.
pycodestyle give us some output and we can fix the Python file based on the output.
There are some other tools which can do similar jobs and here I recommend you to try flake8
flake8
Flake8 is a wrapper of pycodestyle and it also add some more useful features.
Here you might see flake8 and pycodestyle print the similar output, but I recommend you to use flake8 because it provide more features compared with pycodestyle
How to config flake8 check rule
By default, the max-line of Python file is 80, If you want to change the max-line length to 120 instead of 80. You can create setup.cfg in the root of your project. setup.cfg can contain many config sections for different tools, we can put them in one single file.
Below is a sample config file.
The exclude would tell flake8 to ignore some directory and ignore would tell it to ignore some errors. For example, if you have imported some module but did not use it in your code, you will see something like this. F401, module imported but unused . Then you can add F401 to your setup.cfg to let it pass.
If you want pyflake8 to ignore some lines in python file, you can append # noqa just like this.
# noqa tells pyflake8 to not check this line, this is commonly used in Wagtail settings file.
Now you can try run flake8 for your Django/Wagtail project.
Autopep8
If you are new to Python world, you might see long output after you run flake8 command, is there something that can help you solve this?
autopep8 can save you!
Now you can see the test.py has been fixed.
You can also let autopep8 to help you fix the whole directory
Please make sure you have two —aggressive in your command, the file would not be fixed if you only have one —aggressive
Troubleshoot Possible nested set for EXTRANEOUS_WHITESPACE_REGEX
Some people might see above error when run autopep8.
Please make sure you have the same pycodestyle and autopep8 version number as this tutorial.
After you install the package, please open a new terminal to check again. (I have met this problem and I fixed it using this way)
The last thing you need keep in mind is that autopep8 is not silverbullet and can not solve all problems in most cases.
At that time, you need to use Google and read some doc to fix it.
isort
When coding with Wagtail, most code are coming from django , wagtail , and some are coming from other 3-party packages. isort can help us better manage the import statement.
How to config isort rule
Makefile
Let’s add Makefile so we can check our code using simple make pylint instead of long command.
Now you can check your Python code by using make pylint , which is very clean and easy to remember.
Check Python coding style in CI job
You can also check coding style in your CI job, and return error or warning to keep your project code always have good style.
Below is the travis CI config file, you can modify it as you like.
Here the travis CI would mark the job as fail if it finds some style errors in code.
Conclusion
In this Wagtail tutorial, I talked about how to make your Wagtail/Django project have good python coding style.
NOTE: You can find all config files in wagtail-bootstrap-blog , I would appreciate that if you could give this repo a star.
What should you go next?
Try to start using above tools in your project and contact me if you still have question.
I will also publish tutorials about how to make your Wagtail project front-end code has good coding style, you can Subscribe to our Newsletter to get a notification at that time.
SaaS Hammer helps you launch products in faster way. It contains all the foundations you need so you can focus on your product.
Michael is a Full Stack Developer from China who loves writing code, tutorials about Django, and modern frontend tech.
He has published some ebooks on leanpub and tech course on testdriven.io.
He is also the founder of the AccordBox which provides the web development services.
Table of Contents
Django SaaS Template
It aims to save your time and money building your product
Build Jamstack web app with Next.js and Wagtail CMS.
Sign up for our newsletter
Do you want to get notified when a new blog post published? Sign up for our newsletter and you will be among the first to learn the new web tech.