- PVSM.RU - https://www.pvsm.ru -

Форматирование Python-кода

Введение

Python, точнее его самый известный представитель CPython, не очень предназначен для каких-либо быстрых расчетов. Иначе говоря, производительность у него не такая уж хорошая [1]. А вот скорость разработки и читаемости отличная.

О читаемости и пойдет речь, а точнее как ее увеличить.

Проблемы форматирования

Идеального форматирования кода не существует. Для каждого языка стоит подстраиваться под общепринятые правила оформления кода. Да что говорить, если среди новичков С++ еще до сих пор войны по поводу ставить скобки на следующей строке или нет.
Для python'а основными проблемами форматирования является «C стиль». Не редко в рассматриваемый язык приходят из С-подобных языков, а для них свойственно писать с символами ")(;".
Символы не единственная проблема, есть еще и проблема избыточности написания конструкций. Питон, в отличие от Java, менее многословен и чтобы к этому привыкнуть у новичков уходит большое количество времени.
Это две основные проблемы, которые встречаются чаще всего.

Стандарты и рекомендации к оформлению

Если для повышения скорости исполнения кода можно использовать разные подходы [2], хотя эти подходы очень индивидуальны, то для форматирования текста существует прям slyle guide — это pep8. Далее его буду называть «стандарт».
Почитать про стандарт можно здесь [3], на русском языке можно здесь [4]
Pep8 весьма обширный и позволяет программисту писать РЕАЛЬНО читаемый код.

Он включает:

  • максимальную длину строк кода и документации
  • кодировки файлов с исходным кодом
  • рекомендации как правильно оформлять комментарии
  • соглашения именования функций/классов, аргументов
  • и многое другое

В целом, покрывает множество правил форматирования кода. Однако, стоит заметить, что не все python-программисты соблюдают данные правила.
Большие компании, такие как Google, имеют свои рекомендации к написанию python-кода, их можно почитать здесь [5] и здесь [6].
Весьма интересное чтиво, рекомендую.

Автоматизируем форматирование

Если посмотреть сколько всяких правил в pep8, то можно сесть за рефакторинг надолго. Вот только это лениво, да и при написании нового кода сиравно будут какие-то ошибки правил. Для этого рассмотрим как же себе можно упростить жизнь.

pep8

Дабы иметь представление сколько ошибок оформления в коде, стоит использовать утилиту pep8 [7].
У нее достаточный список параметров, который позволяет рекурсивно просмотреть все файлы в папках на предмет соответствия стандарту pep8.
Вывод утилиты примерно такой:

$ 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'

По нему можно однозначно понять: где ошибка и что случилось.

autopep8

Ошибки стандарта часто повторяются от файла в файлу. И возникает сильное желание исправление автоматизировать. В этом случае на арену выходит autopep8 [8].
Как и pep8, он умеет самостоятельно определять ошибки, а также исправлять их. Список исправляемых ошибок форматирования можно найти здесь [9]
Само использование autopep8 крайне простое и может выглядеть так:

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

После выполнения данной команды, утилита рекурсивно пойдет по подпапкам и начнет в самих же файлах исправлять ошибки.

autoflake

Можно пойти дальше и в качестве оружия взять autoflake [10]. Эта утилита помогает удалить не используемые импорты и переменные.
Используется примерно так:

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

Тем самым будут рекурсивно почищены файлы в директории.

unify

Крайний, заключительный момент в редактировании кода — это строки. Кто-то любит их писать в одиночных апострофах, кто-то в двойных. Вот только и для этого существует рекомендации, а также и утилита, которая позволяет автоматически приводить в соответствие — unify [11]
Использование:

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

Как и везде, утилита выполнит свое грязное дело рекурсивно для файлов в папке.

docformatter

Все время говорим о самом коде, а о комментариях еще ни разу не шло речи. Настало время — docformatter [12]. Эта утилита помогает привести ваши docstring по соглашению PEP 257 [13]. Соглашение предписывает как следует оформлять документацию.
Использование утилиты ничуть не сложнее предыдущих:

$ docformatter --in-place example.py

А все вместе можно?

Выше описаны утилиты, их запуск можно добавить какой-нибудь bash скрипт под магическим названием clean.bash и запускать. А можно пойти и по другому пути и использовать wrapper над этими утилитами — pyformat [14]

Выводы

Python-код легко читается, однако, есть способы сделать лапшу и из читаемого кода.
В данной статье были озвучены некоторые проблемы оформления кода, а также способы поиска этих проблем. Были рассмотрены несколько утилит, которые позволяют в автоматическом режиме убрать некоторые изъяны оформления кода.
Стоит озвучить вслух следующую рекомендацию при написании кода, которая универсальна для любого языка: более важным правилом оформлением, чем подобные pep8-документы — это постоянство стиля. Выбрали в каком стиле будете писать программу, в этом же и пишите весь код.

Если читателям будет интересно, то в следующей статье я опишу как в автоматическом режиме искать ошибки в коде.

Автор: WarmongeR

Источник [15]


Сайт-источник PVSM.RU: https://www.pvsm.ru

Путь до страницы источника: https://www.pvsm.ru/python/84106

Ссылки в тексте:

[1] хорошая: http://benchmarksgame.alioth.debian.org/u64q/python.html

[2] разные подходы: http://zokis.github.io/Python--Faster-Way/

[3] здесь: https://www.python.org/dev/peps/pep-0008/

[4] здесь: http://pep8.ru/doc/pep8/

[5] здесь: http://habrahabr.ru/post/179271/

[6] здесь: http://habrahabr.ru/post/180509/

[7] pep8: https://pypi.python.org/pypi/pep8

[8] autopep8: https://pypi.python.org/pypi/autopep8

[9] здесь: https://pypi.python.org/pypi/autopep8/1.1#features

[10] autoflake: https://pypi.python.org/pypi/autoflake/

[11] unify: https://pypi.python.org/pypi/unify

[12] docformatter: https://pypi.python.org/pypi/docformatter

[13] PEP 257: https://www.python.org/dev/peps/pep-0257/

[14] pyformat: https://pypi.python.org/pypi/pyformat

[15] Источник: http://habrahabr.ru/post/251531/