Кодовый стиль python проектов в 2023 году

Рассказал о том как эволюционировал кодовый стиль в нашем комьюнити и за его пределами. Пойдем от базового PEP8 и постараемся разобраться достаточно ли только его, что за линтеры нужны, какие актуальны, а какие не очень. Поговорим о том стоит ли писать документацию или нет, а так же чем нам может помочь во всём этом AI.

https://nastachku.ru/kodovyy-stil-python-proektov-v-2023-godu

Дальнейшее развитие темы (upd от 2024 года) можно найти тут: https://github.com/community-of-python/pylines

Transcript

1. / Денис Аникин https://xfenix.ru Кодовый стиль python проектов в 2023 году
2. Денис Аникин 2 Что я делаю — работаю в Райфе — teamlead в 3 командах — community lead в Python Community — fullstack: typescript, python, devops — много раз выступал на конференциях и митапах https://xfenix.ru
3. Немного слов в начале 3 —Я расскажу о том какой codestyle сейчас у нас (а мы работаем над ним постоянно, поэтому он может быть полезен) в community —Расскажу о том каким он был ранее —На основе этого расскажу как вам самостоятельно писать код по качеству лучше, чем в 95%+ проектов, что существуют вокруг, как защититься от типовых ошибок —Даже если вы уже работаете в крупной организации, некоторые решения могут быть для вас новыми
4. Что я понимаю под codestyle? 4 Это может быть не очевидно —Стандартные соглашения по тому как писать код —Стандартные способы предовтращения появления ошибок —Стандартные способы улучшения вашего кода —Стандартные инструменты, помогающие всего этого достигать —Типовые настройки для всего вашего рабочего процесса (от локальной среды до CI/CD конвейера) —И не только
5. Зачем нам нужен codestyle — Снижение когнитивной нагрузки — Ускорение восприятия информации — Как следствие, возможность проще и легче поддерживать (делать новые части и не позволять старым «гнить») ваши проекты — Унификация (многие вещи понятны, даже если не вы их писали) — Устранение многих ошибок ещё до момента их возникновения
6. Итак, сказочка! 6
7. Знакомьтесь! 7
9. Трицератослав. Древнерусский тимлид 9
10. А это его команда — 10
11. Junior у него свой меч в спине застрял Middle у него всё норм Senior именно он сжег деревню
12. Они любят жечь деревни 12
13. Как же с ними делать продукт? 13
14. Договориться о правилах — code style, иначе… 14
16. А если не выйдет? 16
17. Трицератослав тимлид, сейчас микроменеджер
18. Вы знаете рецепт — мы просто берем линтеры и размещяем их в пайплайнах 18
19. И вот теперь поговорим о том, что и как размещать 19
20. black 20
22. PEP8 и не только 22 Вместе c black —Стандартный кодовый стиль для питон проектов —Разработчики часто путают PEP и PEP8 —Имеет смысл использовать его как стандарт по-умолчанию и не искать ничего лучшего
23. Многие его не помнят. Я считаю, что это ошибка и PEP8 стоит заучить 23
24. Black 24 Если вы его еще не используете —Имеет мало опций настройки и это правильно (я не очень поддерживаю grey) —Можно конфигурировать длину линии, у нас стандарт 120 —Проверяет, что код продуцирует валидное AST —За более чем 4 года работы в качестве автоматического инструмента у очень большого количества людей показал себя как действительно надежный инструмент
25. А ещё вы можете сказать: our code is blacked 25
26. isort 26
27. И вновь PEP8 27 https://peps.python.org/pep-0008/#imports —Импорты надо разбивать на 3 группы: встроенные, сторонние библиотеки и свой код —Разделять стоит 1 пустой строкой —После этого блока 2 пустых строки
29. Открытие 1: большинство нарушает это правило 29
30. Открытие 2: isort по-умолчанию настроен просто ужасно! 30
31. Типовая конфигурация isort 31 Ну и где здесь pep8? —FUTURE —STDLIB —THIRDPARTY —FIRSTPARTY —LOCALFOLDER
32. isort default 32 from __future__ import absolute_import import os import sys from third_party import (lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14, lib15) from my_lib import Object, Object2, Object3 print("Hey") print("yo")
33. isort default — нормальные импорты 33 from __future__ import absolute_import import os import sys from third_party import (lib1, lib2, lib3, lib4, lib5, lib6, lib7, lib8, lib9, lib10, lib11, lib12, lib13, lib14, lib15) from my_lib import Object, Object2, Object3 print("Hey") print("yo")
34. isort default — а вот так вообще хорошо 34 from __future__ import absolute_import import os import sys import third_party import my_lib print("Hey") print("yo")
35. Дополнительные соглашения по импортам 35 —Импортируйте встроенные модули целиком (особенно typing) —Если у вас 2 и более импортов из модуля — импортируйте его целиком —Стандартный pep8, но все таки: не импортируйте «звездочку»
36. Конфигурация isort pyproject.toml 36 Для соблюдения PEP8 [tool.isort] line_length = 120 multi_line_output = 3 include_trailing_comma = true lines_after_imports = 2 lexicographical = true sections = ["FUTURE", "STDLIB", "FIRSTPARTY", "THIRDPARTY", "LOCALFOLDER"] no_lines_before = ["STDLIB", "THIRDPARTY"] known_third_party = [] known_local_folder = []
37. docformatter 37
38. Оказывается, одного PEP8 недостаточно. Нужен ещё PEP257 38
41. У этого инструмента есть режим inplace исправления кода 41
42. autoflake 42
43. autoflake 43 —Удаляет неиспользуемые переменные —Удаляет мертвые импорты —Тоже умеет inplace
44. Если настроить автоматом, у вас никогда не будет мертвого кода 44
45. pyupgrade 45
46. Что представляет из себя pyupgrade 46 —Умеет переписывать код под новые версии python —Все так же умеет inplace —В постоянную работу, все же, взять его проблематично (если у вас больше 1 проекта)
47. Я зову эту штуку «вечно свежий python» 47
48. pybetter 48
49. Код ещё лучше 49 —Внедряет некоторые хорошие практики написания кода (их всего 10, но они важные) —И тоже умеет inplace —Увы, слабо развивается
50. 50 Пример 1
51. 51 Пример 2
52. eradicate 52
53. Все тоже 53 —Берет комментарий, eval’ит его и если тот eval’ится, то удаляет такой комментарий —Тоже умеет inplace
56. Всё просто: при наличии git нет необходимости захламлять код 56
57. Last but not least: Pylint 57
58. Битва pylint vs flake8 58 Плюсы —На мой взгляд pylint содержит нереальное количество хороших практик и советов из коробки —Этот инструмент сразу даёт возможность писать как минимум хорошо —Для тех, кто устал от пачек линтеров, решение «всё в одном»
59. Битва pylint vs flake8 59 А вот дальше идут минусы —Нереально медленный —Очень сложная конфигурация —Fix режима нет (а так можно было?)
60. Картинка по запросу «конфигурация pylint»
61. Аннотации типов 61
62. Лучший тайп чекер — mypy 62 Альтернатива ему — pyright —Сейчас, в 2023 году, имеет смысл включать strict по-умолчанию —Не забывайте о mypy . --install-types —Для pydantic можно подключить комплектный плагин —У моего коллеги, Миши Гурбанова, вышел доклад с подробным исследованием текущих тайпчекеров: https://pycon.ru/da-kto-takie-ehti-vashi- tajp-chekery
63. Свежайшие решения (2023 год) 63
64. Мы выкинули все линтеры! 64
66. …и взяли Ruff 66
68. 68 Ruff из Байкала помогает древним разработчикам писать хороший код!
69. 69 Деревни больше не горят!
70. Что заменил собой ruff? 70
71. Это впечатляет 71 У вас есть почти всё, что вы вообще могли бы хотеть. И это на космической скорости —pylint —isort —около 30 плагинов flake8 —perflint (устраняет некоторые анти-паттерны, убивающие производительность) —refurb (но частично) —pyupgrade —eradicate —pydocstyle —numpy, airflow, pandas-vet, flynt, mccabe, pep8-naming, pycodstyle —свои правила
72. А теперь кое-что очень важное 72
74. Ruff исправляет. Ошибки. За вас! 74
76. Но если только вы включите все правила по-умолчанию 76
77. Как ruff сконфигурировать? 77
78. Пример CLI 78 ruff check .\ --ignore=I,EM,FBT,TRY003,S101,D1,G004,FA,ANN101\ --line-length=120\ --fixable=ALL\ --select=ALL
79. Пример CLI 79 ruff check .\ --ignore=I,EM,FBT,TRY003,S101,D1,G004,FA,ANN101\ --line-length=120\ --fixable=ALL\ --select=ALL
80. Таким образом, мы делаем ваш код потрясающим автоматически 80
81. Некоторые правила мы все же отключаем 81 Лишь небольшую часть —I так как передать конфигурацию глобально невозможно. Если вы индвидуально запускаете ruff в каждом проекте, то можно использовать pyproject.toml (информация уточняется) —TRY003 писать message в exception это нормально —D1 можно пропускать все докстринги —G004, если вы любите f-строки в логах —ANN101 можно отключать, если вы не хотите везде подписывать typing.Self, так как он нормально выводится mypy сейчас автоматически —EM если вы любите добавлять сообщения в ваши эксепшены —FBT довольно спорный набор правил, запрещающий bool аргументы
82. Как pyproject.toml может выглядеть 82 Для конфигурации ruff (в бонус пресет для тестов) [tool.ruff] fix = true line-length = 120 select = ["ALL"] ignore = ["D1", "D203", "D213", "FA102", "I”, “ANN001”] [tool.ruff.extend-per-file-ignores] "tests/*.py" = ["S101", "S311"]
83. И это не всё 83
84. Скорость! 84 И это не обман
85. Другие интересные нюансы 85 —Более 600 правил и число растет быстро —Есть кеширование —Дружит с монорепами
86. Еще не перешли на ruff? 86
88. Я уже ставлю RUFF!
89. Поставил pylint случайно :(
90. Документация 90
91. 91 Показал подруге объем документации на проекте
94. Я раскрыл заговор 94
96. Документация 96 —Все считают, что она должна быть —Почти у всех её либо нет, либо она не актуальная (что хуже её отсутствия) —Всем всегда стыдно, что её нет и, почему-то, менее стыдно, что она не актуальная —Нет хороших подходов, есть спорные —Автодокументация не работает, её почти не читают —Спеки выглядят хорошо в начале дороги, после сотой в них не разобраться
97. Может быть, нам не писать документацию? 97
99. Не переключайте канал! 99
100. Я предлагаю вам самодокументируемый код 100
102. Основные принципы 102 Они довольно простые —Вербозные названия всего: переменных, классов, функций, констант —Не используйте слово get в большинстве случаев —Меньше магических методов (лучше вообще без них) —Никаких чисел кроме 0 и 1 в коде, все остальное — только константы с человеческими именами —Используйте enum для константных перечислений —Функция должна именоваться глаголом, а не существительным. Она что-то делает! —Зен питона — не набор правил
103. Полу-автоматический кодинг 103
104. Принцип 1: все что может быть сделано автоматом, должно быть сделано автоматом 104
105. Как этого достичь? 105 —Вам нужен vscode —Вам понадобятся стандартные плагины mypy, black и ruff, а так же, возможно, отдельностоящий isort
106. 106 Как выглядит конфигурация? "python.linting.mypyEnabled": true, "python.formatting.provider": "black", "python.formatting.blackArgs": [ "--line-length=120", ], "[python]": { "editor.formatOnPaste": true, "editor.formatOnType": true, "editor.formatOnSave": true, "editor.codeActionsOnSave": { "source.fixAll": true, }, }, "ruff.args": [ "--line-length=120", "--ignore=I,EM,FBT,TRY003,S101,D101,D102,D103,D104,D105,G004,D107,FA102", "--fixable=ALL", "--select=ALL" ], "emeraldwalk.runonsave": { "commands": [ { "match": ".py", "cmd": "isort --line-length 120 --lines-after-imports 2 --no-lines-before stdlib,localfolder ${file}", "isAsync": true, } ] }
107. Принцип 2: как можно больше AI утилит 107
108. Некоторые полезные решения 108 —Sourcery (правил меньше, чем у ruff, но несколько раз он находил что-то дополнительно). Пока пилотируем. Правил около 200 —Tabnine —Или Code whisperer —Copilot пока лучше всех, но не работает без VPN и аккаунта за 100$ —Можно использовать ChatGPT 3.5, Bard, GigaChat, TheB.AI
109. Аннотации типов 109
110. Как стартануть? 110 Я знаю, может быть не просто —Берете ruff —Берете mypy —Включите режим strict в mypy —Включаете все правила в ruff —Они вас заставят J
111. Стремитесь к покрытию кода в 100% Аннотации tips & tricks 111 —Освойте не только стандартные типы, но и Literal и особенно Final —Final имеет смысл аннотировать все переменные вообще по-умолчанию (чаще всего изменение переменных и ведет к ошибкам) —Примитивные типы можно не аннотировать (a = 5 не надо расписывать как a: int = 5) —Дженерики иногда полезны —Annotated помогает в валидации —сast, overload, final, never, noreturn, typealias, newtype, classvar, typeguard, unpack, Protocol, assert_type, assert_never, TYPE_CHECKING — очень полезные инструменты
112. 112 Пример с Final: до some_value = 5 some_another_value = 'kek’ for one_element in range(100): some_another_value = some_another_value * some_value some_value += 1
113. 113 Пример с Final: после import typing some_value: typing.Final = 5 # <- тут само выведет typing.Final[typing.Literal[5]] some_another_value: typing.Final = 'kek' for one_element in range(100): some_another_value = some_another_value * some_value # <- тайпчекер поймает some_value += 1
114. Тонкое эстетическое восприятие отдельных людей 114
115. Мне не нравится как форматирует black… 115
116. 5 групп импортов в isort — достаточно логичны… 116
117. Я многое погашу в ruff/pylint, потому что не согласен… 117
119. Легко намекну вам — 119
121. Серьезные советы 121 Правда (тм) —Успокойте свое чувство эстетики, оно совершенно неуместно когда речь заходит о больших и дорогих проектах —Общий кодовый стиль и подход стоят гораздо больше, чем «красивые» кавычки или более веселые переносы —Если гасите правила в линтерах, то обязательно записывайте в глобальные командные установки почему вы это делаете —Ваши аргументы должны быть адекватными («мне не понравилось» — не такой аргумент)
122. Дополнительно 122
123. Набор стандартных советов 123 —Всегда «сужайте» try-except блок до минимального количества строк (если возможно, до 1) —Всегда «сужайте» класс ошибки в except (не все знают, но это крайне полезная графическая иллюстрация стандартной иерархии ошибок https://docs.python.org/3/library/exceptions.html#exception-hierarchy) —Делайте ретраи, ограничивайте количество раз, делайте умный интервал и jitter (библиотека backoff поможет) —Храните всю конфигурацию линтеров в pyproject.toml —Избегайте вложенных и сложных условий с помощью инверсии —Используйте композицию и меньше наследования
124. И кое-что ещё 124 — https://github.com/regebro/pyroma позволяет оценить «дружелюбность» вашего пакета — https://github.com/jendrikseipp/vulture ищет мертвый код по всему проекту — https://github.com/dropbox/pyannotate выводит аннотации для вашего кода (но работа довольно ручная) — https://github.com/JelleZijlstra/autotyping добавляет типовые аннотации (не идеально) — https://github.com/bndr/pycycle обнаруживает циклические импорты (тесты?) — https://github.com/Instagram/Fixit любопытный фреймворк для автоисправлений кода (!) — https://github.com/lyz-code/autoimport сам добавляет нужные импорты — https://github.com/pyupio/safety проверяет безопасность проектов
125. Что по поводу SOLID & GRASP 125 —https://github.com/mschwager/cohesion проверяет связанность вашего кода —Mypy проверяет принцип Liskov substitution principle —Если вы хотите достичь DIP принципа, попробуйте паттерны IoC и DI: на pycon 2023 были посвященные этому доклады. Так же есть неплохие DI фреймворки, мне нравится dependency injector по своему, так же можно посмотреть di, rodi, lagom —Для некоторых других архитектурных линтеров советую доклад Коли https://pycon.ru/arhitektura-knuta-i-pryanika
128. Теперь качества кода станет значительно лучше 128
130. Денис Аникин https://xfenix.ru https://github.com/xfenix/ Вопросы? Поставьте лайк на гитхабе, пожалуйста