PythonCodingGuidelines
1.0.0
Рекомендации по кодированию на Python — это набор проверенных рекомендаций, правил и лучших практик кодирования на Python.
Цель рекомендаций — помочь разработчикам эффективно использовать Python и предоставить более читабельный современный стиль Python. Код, который легко поддерживать и масштабировать. Кроме того, установить стандарт разработки, которому необходимо следовать при разработке приложений или библиотек на Python.
Я надеюсь, что этот документ также поможет вам начать работу с Python. Если вы используете другой язык сценариев, например JavaScript, вы обнаружите, что Python очень похож, и этот документ представляет собой способ перехода на Python.
Рекомендации ориентированы на все ресурсы, предоставляемые языком Python, обычно определенные в стандарте PEP8. PEP8 Здесь PEP8 используется только как основа для данного предложения по руководству по кодированию. Я хочу продвигать более читабельный и современный стиль Python.
Вы можете обнаружить, что некоторые правила этого руководства противоречат вашим ожиданиям или даже вашему опыту.
Если я не предлагал вам каким-либо образом изменить свой стиль кодирования, значит, я потерпел неудачу!
Пожалуйста, попробуйте подтвердить или опровергнуть правила этого руководства. В частности, мне бы очень хотелось, чтобы некоторые из предложенных правил были подкреплены измерениями или лучшими примерами.
Это общее правило разработки программного обеспечения, направленное на создание читаемых, поддерживаемых и масштабируемых приложений. Это не всегда правда, но мы стремимся к этой цели.
Стандарты кода — это инструменты, которые помогают создавать приложения с использованием вышеупомянутых принципов триады. Вот некоторые преимущества, которые дает установление последовательного стандарта разработки:
️ Предупреждение: это действующий документ, который постоянно совершенствуется. Комментарии и предложения по улучшению приветствуются. Я планирую изменять и расширять этот документ по мере улучшения нашего понимания и развития языка набора доступных библиотек.
| Имя | Соглашение | Пример кода |
|---|---|---|
| одно имя переменной | Snake_case | age: int = 100 |
| имя составной переменной | Snake_case | first_name: str = "Akira" |
| постоянное имя | КОНСТ | CPU: number = 8 |
| составное имя константы | КОНСТ | MAX_NUMBER: number = 100 |
| имя перечисления | ПаскальКейс | class Color(Enum): RED = 1 GREEN = 2 |
| имя функции | Snake_case | def main() |
| функция с параметрами | Snake_case | def calculate(n1: int, n2: int) |
| функция с возвращаемым типом | Snake_case | def calculate(n1: int, n2: int) -> int: |
| имя составной функции | Snake_case | def add_two_numbers(n1: int, n2: int) -> int: |
| имя класса | ПаскальКейс | class Base |
| имя составного класса | ПаскальКейс | class MyClass |
| интерфейсы | ПаскальКейс | class IUser(ABC) |
| кастинг | по умолчанию | age: int = int(100) |
| список | верблюдЧехол | myList: list[int] = [1,2,3] |
| кортеж | верблюдЧехол | myTuple: tuple[int] = (1,2,3) |
| набор | Snake_case | my_set: set[int] = {1,2,3} |
| словарь | Snake_case | my_dictionary: dict = {"name": "John", "age": 100} |
| хинтинг нескольких типов | Snake_case | var_a: Union[int, str] |
Мы предложили использовать стиль Google Doc Style для документации Python, поскольку его легче всего читать и понимать. Руководство по стилю Google также очень популярно и широко используется в сообществе Python.
def add_binary ( a : int , b : int ) -> int :
"""
Returns the sum of two decimal numbers in binary format.
Parameters:
a (int): First number to add
b (int): Second number to add
Returns:
binary (int): Binary int of the sum of a and b
"""
binary_sum = bin ( a + b )[ 2 :]
return int ( binary_sum )Подсказка типа — это формальное решение для статического указания типа значения.
Пример:
def addBinary(a: int, b: int)-> int:
...
В приведенной выше функции явно указано, что функция ожидает значения int в переменных a и b и возвращает значение int .
Проверьте эту ссылку: Официальная документация по типизации Python.
Но разве Python не является нетипизированным языком? Да, это не так. Если вы передадите какое-либо значение, отличное от int , это сработает.
Как проверить попадание типа в Python?
Вам следует использовать библиотеку mypy .
Mypy — это дополнительная программа проверки статического типа для Python, целью которой является объединение преимуществ динамической (или «утиной») и статической типизации. (Источник: Официальная документация)
pip install mypy
mypy mycode.py
Идея использования линтера для Python состоит в том, чтобы обеспечить соблюдение рекомендаций по кодированию, предложенных в этом документе. Я буду использовать Precommit.
pip install pre-commit
Базовая конфигурация:
.pre-commit-config.yml для сохранения конфигураций предварительной фиксацииВ этом примере ниже скрипт выполнит следующие шаги:
Пример:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-json
- id: detect-private-key
- repo: https://github.com/PyCQA/isort
rev: 5.12.0
hooks:
- id: isort
- repo: https://github.com/psf/black
rev: 22.12.0
hooks:
- id: black
language_version: python3.10
- repo: https://github.com/charliermarsh/ruff-pre-commit
rev: 'v0.0.260'
hooks:
- id: ruff
pyproject.toml для сохранения конфигураций бегунов перед фиксациейПример:
[tool.black]
line-length = 80
target-version = ['py310']
include = '.pyi?$'
[tool.isort]
line_length = 79
multi_line_output = 3
include_trailing_comma = true
force_grid_wrap = 0
use_parentheses = true
ensure_newline_before_comments = true
После этой конфигурации каждый раз, когда вы делаете фиксацию, будет выполняться предварительная фиксация.
Предварительная фиксация официальной документации
Фреймворк, предложенный для тестирования, — pytest. Это также очень популярная среда тестирования Python.
tests : pytest
pytest --cov . 
Дополнительные команды pytest можно найти в официальной документации здесь pytest.
Вот пример определения функции для теста:
После создания функции, как показано в примере ниже: 
Вы можете создать модульный тест, выполнив следующие действия:
test_ в имени функции.
Чтобы начать новый проект, вы можете клонировать его, используя следующую команду:
git clone https://github.com/rsaz/python-project-templateВот предлагаемая структура проекта по умолчанию.
Структура проекта основана на следующем:
| Папка/файл | Описание |
|---|---|
| утилиты | Скрипты PowerShell, позволяющие создавать, активировать, деактивировать и удалять среды, а также обновлять и создавать зависимости. |
| .vscode | Специальная конфигурация редактора |
| источник | Основная исходная папка проекта |
| тест | Папка, содержащая все модульные тесты приложения. |
| венв | Виртуальная среда Python |
| .pylintrc | Конфигурационный файл статического анализатора кода pylint для Python |
| pytest.ini | Конфигурационный файл для pytest |
| ЛИЦЕНЗИЯ.txt | Условия лицензии проекта |
| README.md | Детали проекта |
| требования.txt | Зависимости проекта |
| setup.cfg и setup.py | Начальная конфигурация проекта |
