Рассмотрим популярные инструменты для анализа кода Python и подробно расскажем об их специфике и основных принципах работы.
Автор: Валерий Шагур, teacher assistance на курсе Программирование на Python
Высокая стоимость ошибок в программных продуктах предъявляет повышенные
требования к качеству кода. Каким критериям должен соответствовать хороший код?
Отсутствие ошибок, расширяемость, поддерживаемость, читаемость и наличие документации. Недостаточное внимание к любому из этих критериев может привести к появлению новых ошибок или снизить вероятность обнаружения уже существующих. Небрежно написанный или чересчур запутанный код, отсутствие документации напрямую влияют на время исправления найденного бага, ведь разработчику приходится заново вникать в код. Даже такие, казалось бы, незначительные вещи как неправильные имена переменных или отсутствие форматирования могут сильно влиять на читаемость и понимание кода.
Командная работа над проектом еще больше повышает требования к качеству кода, поэтому важным условием продуктивной работы команды становится описание формальных требований к написанию кода. Это могут быть соглашения, принятые в языке программирования, на котором ведется разработка, или собственное (внутрикорпоративное) руководство по стилю. Выработанные требования к оформлению кода не исключают появления "разночтений" среди разработчиков и временных затрат на их обсуждение. Кроме этого, соблюдение выработанных требований ложится на плечи программистов в виде дополнительной нагрузки. Все это привело к появлению инструментов для проверки кода на наличие стилистических и логических ошибок. О таких инструментах для языка программирования Python мы и поговорим в этой статье.
Анализаторы и автоматическое форматирование кода
Весь инструментарий, доступный разработчикам Python, можно условно разделить на две группы по способу реагирования на ошибки. Первая группа сообщает о найденных ошибках, перекладывая задачу по их исправлению на программиста. Вторая — предлагает пользователю вариант исправленного кода или автоматически вносит изменения.
И первая, и вторая группы включают в себя как простые утилиты командной строки для решения узкоспециализированных задач (например, проверка docstring или сортировка импортов), так и богатые по возможностям библиотеки, объединяющие в себе более простые утилиты. Средства анализа кода из первой группы принято называть линтерами (linter). Название происходит от lint — статического анализатора для языка программирования Си и со временем ставшего нарицательным. Программы второй группы называют форматировщиками (formatter).
Даже при поверхностном сравнении этих групп видны особенности работы с ними. При применении линтеров программисту, во-первых, необходимо писать код с оглядкой, дабы позже не исправлять найденные ошибки. И во вторых, принимать решение по поводу обнаруженных ошибок — какие требуют исправления, а какие можно проигнорировать. Форматировщики, напротив, автоматизируют процесс исправления ошибок, оставляя программисту возможность осуществлять контроль.
Список рассматриваемых инструментов для анализа кода Python
Часть 1
Часть 2
Соглашения принятые в статье и общие замечания
Прежде чем приступить к обзору программ, мы хотели бы обратить ваше внимание на несколько важных моментов.
Версия Python: во всех примерах, приведенных в статье, будет использоваться третья версия языка программирования Python.
Установка всех программ в обзоре практически однотипна и сводится к использованию пакетного менеджера pip.
$ python3.6 -m pip install --upgrade <package_name>
Некоторые из библиотек имеют готовые бинарные пакеты в репозиториях дистрибутивов linux или возможность установки с использованием git. Тем не менее для большей определенности и возможности повторения примеров из статьи, установка будет производится с помощью pip.
Об ошибках: стоит упомянуть, что говоря об ошибках, обнаруживаемых анализаторами кода, как правило, имеют в виду два типа ошибок. К первому относятся ошибки стиля (неправильные отступы, длинные строки), ко второму — ошибки в логике программы и ошибки синтаксиса языка программирования (опечатки при написании названий стандартных функций, неиспользуемые импорты, дублирование кода). Существуют и другие виды ошибок, например — оставленные в коде пароли или высокая цикломатическая сложность.
Тестовый скрипт: для примеров использования программ мы создали простенький по содержанию файл example.py. Мы сознательно не стали делать его более разнообразным по наличию в нем ошибок. Во-первых, добавление листингов с выводом некоторых анализаторов в таком случае сильно “раздуло” бы статью. Во-вторых, у нас не было цели детально показать различия в “отлове” тех или иных ошибок для каждой из утилит.
Содержание файла example.py:
import os
import notexistmodule
def Function(num,num_two):
return num
class MyClass:
"""class MyClass """
def __init__(self,var):
self.var=var
def out(var):
print(var)
if __name__ == "__main__":
my_class = MyClass("var")
my_class.out("var")
notexistmodule.func(5)
В коде допущено несколько ошибок:
- импорт неиспользуемого модуля os,
- импорт не существующего модуля notexistmodule,
- имя функции начинается с заглавной буквы,
- лишние аргументы в определении функции,
- отсутствие self первым аргументом в методе класса,
- неверное форматирование.
Руководства по стилям: для тех, кто впервые сталкивается с темой оформления кода, в качестве знакомства предлагаем прочитать официальные руководства по стилю для языка Python PEP8 и PEP257. В качестве примера внутрикорпоративных соглашений можно рассмотреть Google Python Style Guide — https://github.com/google/styleguide/blob/gh-pages/pyguide.md
Pycodestyle
Pycodestyle — простая консольная утилита для анализа кода Python, а именно для проверки кода на соответствие PEP8. Один из старейших анализаторов кода, до 2016 года носил название pep8, но был переименован по просьбе создателя языка Python Гвидо ван Россума.
Запустим проверку на нашем коде:
$ python3 -m pycodestyle example.py example.py:4:1: E302 expected 2 blank lines, found 1 example.py:4:17: E231 missing whitespace after ',' example.py:7:1: E302 expected 2 blank lines, found 1 example.py:10:22: E231 missing whitespace after ',' example.py:11:17: E225 missing whitespace around operator
Лаконичный вывод показывает нам строки, в которых, по мнению анализатора, есть нарушение соглашений PEP8. Формат вывода прост и содержит только необходимую информацию:
<имя файла>: <номер строки> :<положение символа>: <код и короткая расшифровка ошибки>
Возможности программы по проверке соглашений ограничены: нет проверок на правильность именования, проверка документации сводится к проверки длины docstring. Тем не менее функционал программы нельзя назвать “спартанским”, он позволяет настроить необходимый уровень проверок и получить различную информацию о результатах анализа. Запуск с ключом --statistics -qq выводит статистику по ошибкам:
$ python3 -m pycodestyle --statistics -qq example.py 1 E225 missing whitespace around operator 2 E231 missing whitespace after ',' 2 E302 expected 2 blank lines, found 1
Более наглядный вывод можно получить при использовании ключа --show-source. После каждого сообщения об ошибке будет выведена строка исходного кода, в которой содержится ошибка.
$ python3 -m pycodestyle --show-source example.py example.py:4:1: E302 expected 2 blank lines, found 1 def Function(num,num_two): ^ example.py:4:17: E231 missing whitespace after ',' def Function(num,num_two): ^ example.py:7:1: E302 expected 2 blank lines, found 1 class MyClass: ^ example.py:10:22: E231 missing whitespace after ',' def __init__(self,var): ^ example.py:11:17: E225 missing whitespace around operator self.var=var ^
Если есть необходимость посмотреть, какие из соглашений PEP8 были нарушены, используйте ключ -- show-pep8. Программа выведет список всех проверок с выдержками из PEP8 для случаев нарушений. При обработке файлов внутри директорий предусмотрена возможность фильтрации по шаблону. Pycodestyle позволяет сохранять настройки поиска в конфигурационных файлах как глобально, так и на уровне проекта.
Pydocstyle
Утилиту pydocstyle мы уже упоминали в статье Работа с документацией в Python: поиск информации и соглашения. Pydocstyle проверяет наличие docstring у модулей, классов, функций и их соответствие официальному соглашению PEP257.
$ python3 -m pydocstyle example.py example.py:1 at module level: D100: Missing docstring in public module example.py:4 in public function `Function`: D103: Missing docstring in public function example.py:7 in public class `MyClass`: D400: First line should end with a period (not 's') example.py:7 in public class `MyClass`: D210: No whitespaces allowed surrounding docstring text example.py:10 in public method `__init__`: D107: Missing docstring in __init__ example.py:13 in public method `out`: D102: Missing docstring in public method
Как мы видим из листинга, программа указала нам на отсутствие документации в определениях функции, методов класса и ошибки оформления в docstring класса. Вывод можно сделать более информативным, если использовать ключи --explain и --source при вызове программы. Функционал pydocstyle практически идентичен описанному выше для pycodestyle, различия касаются лишь названий ключей.
Pyflakes
В отличие от уже рассмотренных инструментов для анализа кода Python pyflakes не делает проверок стиля. Цель этого анализатора кода — поиск логических и синтаксических ошибок. Разработчики pyflakes сделали упор на скорость работы программы, безопасность и простоту. Несмотря на то, что данная утилита не импортирует проверяемый файл, она прекрасно справляется c поиском синтаксических ошибок и делает это быстро. С другой стороны, такой подход сильно сужает область проверок.
Функциональность pyflakes — “нулевая”, все что он умеет делать — это выводить результаты анализа в консоль:
$ python3 -m pyflakes example.py example.py:1: 'os' imported but unused
В нашем тестовом скрипте, он нашел только импорт не используемого модуля os. Вы можете самостоятельно поэкспериментировать с запуском программы и передачей ей в качестве параметра командной строки Python файла, содержащего синтаксические ошибки. Данная утилита имеет еще одну особенность — если вы используете обе версии Python, вам придется установить отдельные утилиты для каждой из версий.
Pylint
До сих пор мы рассматривали утилиты, которые проводили проверки на наличие либо стилистических, либо логических ошибок. Следующий в обзоре статический инструмент для анализа кода Python — Pylint, который совместил в себе обе возможности. Этот мощный, гибко настраиваемый инструмент для анализа кода Python отличается большим количеством проверок и разнообразием отчетов. Это один из самых “придирчивых” и “многословных” анализаторов кода. Анализ нашего тестового скрипта выдает весьма обширный отчет, состоящий из списка найденных в ходе анализа недочетов, статистических отчетов, представленных в виде таблиц, и общей оценки кода:
$ python3.6 -m pylint --reports=y text example.py
************* Module text
/home/ququshka77/.local/lib/python3.6/site-packages/pylint/reporters/text.py:79:22: W0212: Access to a protected member _splitstrip of a client class (protected-access)
************* Module example
example.py:4:16: C0326: Exactly one space required after comma
def Function(num,num_two):
^ (bad-whitespace)
example.py:10:21: C0326: Exactly one space required after comma
def __init__(self,var):
^ (bad-whitespace)
example.py:11:16: C0326: Exactly one space required around assignment
self.var=var
^ (bad-whitespace)
example.py:1:0: C0111: Missing module docstring (missing-docstring)
example.py:2:0: E0401: Unable to import 'notexistmodule' (import-error)
example.py:4:0: C0103: Function name "Function" doesn't conform to snake_case naming style (invalid-name)
example.py:4:0: C0111: Missing function docstring (missing-docstring)
example.py:4:17: W0613: Unused argument 'num_two' (unused-argument)
example.py:13:4: C0111: Missing method docstring (missing-docstring)
example.py:13:4: E0213: Method should have "self" as first argument (no-self-argument)
example.py:7:0: R0903: Too few public methods (1/2) (too-few-public-methods)
example.py:18:4: C0103: Constant name "my_class" doesn't conform to UPPER_CASE naming style (invalid-name)
example.py:19:4: E1121: Too many positional arguments for method call (too-many-function-args)
example.py:1:0: W0611: Unused import os (unused-import)
Report
======
112 statements analysed.
Statistics by type
+----------+----------+---------------+-------------+-------------------+---------------+
|type |number |old number |difference |%documented |%badname |
+======+======+========+========+===========+========+
|module |2 |2 |= |50.00 |0.00 |
+-----------+----------+---------------+-------------+-------------------+---------------+
|class |5 |5 |= |100.00 |0.00 |
+-----------+----------+---------------+-------------+-------------------+---------------+
|method |11 |11 |= |90.91 |0.00 |
+-----------+----------+---------------+-------------+-------------------+---------------+
|function |4 |4 |= |75.00 |25.00 |
+-----------+----------+---------------+-------------+-------------------+---------------+
External dependencies
::
pylint
\-interfaces (text)
\-reporters (text)
| \-ureports
| \-text_writer (text)
\-utils (text)
Raw metrics
+-------------+----------+-------+-----------+-------------+
|type |number |% |previous |difference |
+=======+======+=====+=====+========+
|code |128 |48.30 |128 |= |
+-------------+----------+--------+-----------+------------+
|docstring |84 |31.70 |84 |= |
+-------------+----------+--------+-----------+------------+
|comment |16 |6.04 |16 |= |
+-------------+----------+--------+-----------+------------+
|empty |37 |13.96 |37 |= |
+-------------+----------+--------+-----------+------------+
Duplication
+-------------------------------+------+------------+-------------+
| |now |previous |difference |
+=================+=====+======+========+
|nb duplicated lines |0 |0 |= |
+-------------------------------+-------+------------+------------+
|percent duplicated lines |0.000 |0.000 |= |
+-------------------------------+-------+------------+------------+
Messages by category
+--------------+----------+-----------+-------------+
|type |number |previous |difference |
+========+======+======+========+
|convention |8 |8 |= |
+--------------+----------+-----------+-------------+
|refactor |1 |1 |= |
+--------------+-----------+----------+-------------+
|warning |3 |3 |= |
+--------------+-----------+----------+-------------+
|error |3 |3 |= |
+--------------+-----------+----------+-------------+
% errors / warnings by module
+-----------+--------+-----------+----------+--------------+
|module |error |warning |refactor |convention |
+======+=====+======+======+========+
|example |100.00 |66.67 |100.00 |100.00 |
+-----------+---------+----------+-----------+-------------+
|text |0.00 |33.33 |0.00 |0.00 |
+-----------+---------+----------+-----------+-------------+
Messages
+-----------------------------+----------------+
|message id |occurrences |
+=================+=========+
|missing-docstring |3 |
+-----------------------------+----------------+
|bad-whitespace |3 |
+------------------------------+---------------+
|invalid-name |2 |
+------------------------------+---------------+
|unused-import |1 |
+------------------------------+---------------+
|unused-argument |1 |
+------------------------------+---------------+
|too-many-function-args |1 |
+------------------------------+---------------+
|too-few-public-methods |1 |
+------------------------------+---------------+
|protected-access |1 |
+------------------------------+---------------+
|no-self-argument |1 |
+------------------------------+---------------+
|import-error |1 |
+------------------------------+---------------+
------------------------------------------------------------------------------------------
Your code has been rated at 7.59/10 (previous run: 7.59/10, +0.00)
Программа имеет свою внутреннюю маркировку проблемных мест в коде:
[R]efactor — требуется рефакторинг,
[C]onvention — нарушено следование стилистике и соглашениям,
[W]arning — потенциальная ошибка,
[E]rror — ошибка,
[F]atal — ошибка, которая препятствует дальнейшей работе программы.
Для вывода подробного отчета мы использовали ключ командной строки --reports=y.
Более гибко настроить вывод команды позволяют разнообразные ключи командной строки. Настройки можно сохранять в файле настроек rcfile. Мы не будем приводить подробное описание ключей и настроек, для этого есть официальная документация — https://pylint.readthedocs.io/en/latest/index.html#, остановимся лишь на наиболее интересных, с нашей точки зрения, возможностях утилиты:
— Генерация файла настроек (--generate-rcfile). Позволяет не писать конфигурационный файл с нуля. В созданном rcfile содержатся все текущие настройки с подробными комментариями к ним, вам остается только отредактировать его под собственные требования.
— Отключение вывода в коде. При редактировании кода есть возможность вставить блокирующие вывод сообщений комментарии. Чтобы продемонстрировать это, в определение функции в файле примера example.py добавим строку:
# pylint: disable=unused-argument
и запустим pylint. Из результатов проверки “исчезло” сообщение:
example.py:4:17: W0613: Unused argument 'num_two' (unused-argument)
— Создание отчетов в формате json (--output-format=json). Полезно, если необходимо сохранение или дальнейшая обработка результатов работы линтера. Вы также можете создать собственный формат вывода данных.
— Параллельный запуск (-j 4). Запуск в нескольких параллельных потоках на многоядерных процессорах сокращает время проверки.
— Встроенная документация. Вызов программы с ключом --help-msg=<key> выведет справку по ключевому слову key. В качестве ключевого слова может быть код сообщения (например: E0401) или символическое имя сообщения (например: import-error). Ниже приведен листинг получения справки по ключу import-error:
$ python3.6 -m pylint --help-msg=import-error :import-error (E0401): *Unable to import %s* Used when pylint has been unable to import a module. This message belongs to the imports checker.
— Система оценки сохраняет последний результат и при последующих запусках показывает изменения, что позволяет количественно оценить прогресс исправлений.
— Плагины — отличная возможность изменять поведение pylint. Их применение может оказаться полезным в случаях, когда pylint неправильно обрабатывает код и есть “ложные” срабатывания, или когда требуется отличный от стандартного формат вывода результатов.
Vulture
Vulture — небольшая утилита для поиска “мертвого” кода в программах Python. Она использует модуль ast стандартной библиотеки и создает абстрактные синтаксические деревья для всех файлов исходного кода в проекте. Далее осуществляется поиск всех объектов, которые были определены, но не используются. Vulture полезно применять для очистки и нахождения ошибок в больших базовых кодах.
Продолжение следует
Во второй части мы продолжим разговор об инструментах для анализа кода Python. Будут рассмотрены линтеры, представляющие собой наборы утилит. Также мы посмотрим, какие программы можно использовать для автоматического форматирования кода.
ФРОО рекомендует:
До конца октября действует промокод backupmaster, который дает скидку 5000 рублей на курс Программирование на Python и 5000 рублей на курс Машинное обучение и анализ данных.
Комментарии