Небанальные правила чистого Python. Часть 1

Большинство питонистов не раз слышали о таких правилах как «функции должны быть глаголами» или «не наследуйтесь явно от object в Python 3». В этой статье мы рассмотрим не такие банальные, но полезные правила чистого кода в Python.

Необязательное вступление

Идея статьи возникла при выполнении Code review одного проекта. В тот момент я понял что пора объединить и структурировать накопленные правила чистого кода.

Эти правила я использую постоянно и, после их применения, начинаю быстрее читать и понимать код. Соглашаться с ними или нет — ваш выбор, но если считаете, что какое-то правило неэффективно, давайте обсудим это в комментариях.

Функции

Правило №1 — Имя начинается с нижнего подчёркивания, если функция используется только в том модуле, в котором она создана

Такой подход даёт понять, что функция не используется и не должна использоваться в других файлах. По крайней мере, на уровне соглашений.

Например в проекте есть модули «a.py», «b.py» и «c.py». Функция get_user_name создана в модуле «a.py». Используется она тоже только в нём. Тогда её следует переименовать в _get_user_name.

Правило №2 — Примеры использования функции в docstrings пишутся в виде doctest

Напишем такую функцию:

def get_sum(number_1: int, number_2: int) -> int:     """Вернёт сумму двух чисел.      Примеры:     get_sum(0, 2) = 2     get_sum(1, 2) = 3     get_sum(3, 5) = 8      """      return number_1 + number_2   print(get_sum(10, 15))

Функция работает, но запустив код, мы никак не проверим примеры из docstring:

# Флаг «v» выводит дополнительные детали выполнения программы $ python script.py -v 25

Исправим это с помощью модуля doctest:

from doctest import testmod   def get_sum(number_1: int, number_2: int) -> int:     """Вернёт сумму двух чисел.      >>> get_sum(0, 2)     2     >>> get_sum(1, 2)     3     >>> get_sum(3, 5)     8      """      return number_1 + number_2   if __name__ == "__main__":     print(get_sum(10, 15))      testmod()

Теперь запустим программу:

$ python script.py -v 25 Trying:     get_sum(0, 2) Expecting:     2 ok Trying:     get_sum(1, 2) Expecting:     3 ok Trying:     get_sum(3, 5) Expecting:     8 ok 1 items had no tests:     __main__ 1 items passed all tests:    3 tests in __main__.get_sum 3 tests in 2 items. 3 passed and 0 failed. Test passed.

Мы получили результат работы программы и результат выполнения тестов из docstring. Уберите флаг «v», если хотите вывести только результат работы программы:

$ python script.py 25

Правило №3 — У аргументов функции указан type hint

Взгляните на эту функцию:

def is_user_name_valid(user_name): pass

Какое значение нужно передать в переменную user_name? Строку с именем? Словарь с ФИО? Может ещё что-то? Скорее всего строку с именем, но для полной уверенности надо читать саму функцию. Type hint освобождает от этой траты времени:

def is_user_name_valid(user_name: str): pass

Плюсы использования type hint:

1. Позволяет не думать над типом аргумента;

2. Немного документирует код;

3. Уменьшает число ошибок, связанных с типом аргумента;

4. Облегчает разработку в некоторых IDE. Например PyCharm может ругаться на аргумент, который не соответствует type hint.

Type hint для аргументов по умолчанию

Для аргументов по умолчанию тоже можно задать type hint:

def is_user_name_valid(user_name: str = "admin"): pass

Особенно это полезно если аргумент может принимать значения разных типов:

# Для Python 3.10 def is_positive(number: int | float = 100): pass   # Для Python 3.9 и ниже from typing import Union  def is_positive(number: Union[int, float] = 100): pass

Type hint для переменных

Для переменных тоже можно указать type hint. Но нет смысла это делать, если тип переменной и так понятен.

Плохо:

cat_name: str = "Tom"

Хорошо:

# settings.PAGE_SIZE может иметь значение разных типов, например str и int page_size: int = settings.PAGE_SIZE

Правило №4 — У функции указан type hint возвращаемого значения

Type hint полезен не только для аргументов и переменных, но и для возвращаемого значения функции. За счёт него можно не заглядывать в тело функции, а сразу понять какой тип она вернёт.

from typing import Callable   def get_user_name() -> str: ...  def is_user_name_valid(user_name: str) -> bool: ...  def get_wrapped_function() -> Callable: ...  def run_tests() -> None: ...

У функции, которая возвращает другую функцию, указывается type hint Callable. У функции, которая ничего не возвращает, указывается type hint None.

Классы

Правило №5 — Приватные методы располагаются ниже магических и публичных

Допустим, есть такой кот класс:

class Cat:     """Просто кот"""      def __init__(self, name: str):         self.name = name      def ask_for_food(self) -> None:         self.__say_meow()         self.__say_meow()      def __say_meow(self) -> None:         print(f"{self.name} says meow")

Мы создаем его объект и вызываем публичный метод:

tom = Cat("Tom") tom.ask_for_food()

Если человек захочет понять что делает метод ask_for_food, то он прочитает содержимое класса Cat в таком порядке:

1. Прочитает метод __init__ и поймёт куда заносится имя "Tom";

2. Прочитает метод ask_for_food и увидит в нём вызов метода __say_meow;

3. Прочитает метод __say_meow.

Т.е. приватный пользовательский метод читается в последнюю очередь. Так всегда происходит со всеми не магическими private-методами, если в коде соблюдаются принципы ООП.

Что касается порядка создания публичных и магических методов, то это дело вкуса. Я обычно создаю методы в такой последовательности:

1. __new__ (если такой метод используется в классе);

2. __init__;

3. Остальные магические методы;

4. Public-методы;

5. Protected-методы;

6. Private-методы.

Переменные

Правило №6 — Названия переменных, в которых хранятся измеряемые данные, содержат единицу измерения

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

Плохо

cooking_time = 30 user_weight = 5

Лучше, но всё ещё плохо:

# Время в минутах cooking_time = 30  # Вес в килограммах user_weight = 5

Хорошо

cooking_time_in_minutes = 30 user_weight_in_kg = 5

Дополнительно об этом правиле можно прочитать в книге «Чистый код», глава 2, пункт «Имена должны передавать намерения программиста».

Правило №7 — Названия неиспользуемых переменных заменяются на нижнее подчёркивание

Напишем следующий код:

for i in range(10):     print("Hello!")

Переменная i внутри цикла не используется. Заменим её на нижнее подчеркивание — традиционное обозначение неиспользуемых переменных:

for _ in range(10):     print("Hello!")

С точки зрения Python мы поменяли имя переменной i на _. Работа программы от этого не изменилась. Но зато человек, который будет читать код, поймёт, что внутри цикла не используется итерационная переменная.

Это правило обычно применяется и при распаковке последовательностей:

# a = 1; _ = 2 a, _ = 1, 2  # a = 1; _ = [2, 3, 4] a, *_ = (1, 2, 3, 4) a, *_ = [1, 2, 3, 4] a, *_ = {1, 2, 3, 4} a, *_ = {1: '1', 2: '2', 3: '3', 4: '4'}

Т.е. значения 2, 3 и 4 мы использовать не собираемся, но сохранить их где-то надо.

Когда не следует использовать это правило

Не используйте это правило если пишите на Django, и в вашем коде есть функция gettext. Её принято заменять на нижнее подчёркивание. Хотя ошибки в коде не произойдет, но у программиста может возникнуть недопонимание:

from django.utils.translation import gettext as _   title = _("Интернет-магазин «Кошачий рай»")  # Программист: «Почему здесь исользуется функция gettext?» for _ in range(10): # Цикл спокойно работает     print(1)

Дополнительно об этом правиле читайте тут.

Числа

Правило №8 — Число разделяется нижним подчеркиванием через каждые 3 цифры

Для удобства пользователя, в большинстве приложений числа разделяются пробелом через каждые 3 цифры. Например, вместо 1000000 пишется 1 000 000. В Python тоже есть такая возможность, но вместо пробела используется нижнее подчеркивание.

Плохо

number_of_accounts = 1500  sum_in_rubles = 1234567890

Хорошо

number_of_accounts = 1_500  sum_in_rubles = 1_234_567_890

Дополнительно о правиле читайте в этой статье, в пункте «Example 5: Single underscore in numeric literals».

Правило №9 — Число пишется в виде формулы, если его можно так записать

Плюсы применения правила:

1. Легче и быстрее понять, как появилось число;

2. Легче и быстрее изменить число — надо просто поменять параметры формулы;

3. Из кода удаляются «магические числа»;

4. В коде становится меньше лишних комментариев.

Плохо:

flight_time_in_seconds = 10_800

Лучше, но всё ещё плохо:

# 60 секунд * 60 минут * 3 flight_time_in_seconds = 10_800

Хорошо:

flight_time_in_seconds = 60 * 60 * 3

Очень хорошо:

MIN_IN_SECONDS = 60 HOUR_IN_SECONDS = MIN_IN_SECONDS * 60  flight_time_in_seconds = HOUR_IN_SECONDS * 3

Идеально:

# Код файла constants.py MIN_IN_SECONDS = 60 HOUR_IN_SECONDS = MIN_IN_SECONDS * 60  # Код файла script.py from constants import HOUR_IN_SECONDS  flight_time_in_seconds = HOUR_IN_SECONDS * 3

Объём кода становится больше, но времени на осознание и, при необходимости, изменение переменной flight_time_in_seconds — меньше.

Ещё 2 статьи по правилам чистого кода

Во второй части статьи я расскажу про остальные правила. Также в ближайшее время планируется публикация по правилам чистого кода в Django-проектах.

Надеюсь, полученная информация принесла вам пользу. До скорых встреч)