Python отличается от таких языков программирования, как C# или Java, заставляющих программиста давать классам имена, соответствующие именам файлов, в которых находится код этих классов.
Python — это самый гибкий язык программирования из тех, с которыми мне приходилось сталкиваться. А когда имеешь дело с чем-то «слишком гибким» — возрастает вероятность принятия неправильных решений.
- Хотите держать все классы проекта в единственном файле main.py? Да, это возможно.
- Надо читать переменную окружения? Берите и читайте там, где это нужно.
- Требуется модифицировать поведение функции? Почему бы не прибегнуть к декоратору!?
Но, если вы точно знаете о том, что делаете, последствия гибкости Python не обязательно окажутся плохими.
Здесь я собираюсь представить вашему вниманию рекомендации по организации Python-кода, которые сослужили мне хорошую службу, когда я работал в разных компаниях и взаимодействовал со многими людьми.
Структура Python-проекта
Сначала обратим внимание на структуру директорий проекта, на именование файлов и организацию модулей.Рекомендую держать все файлы модулей в директории src, а тесты — в поддиректории tests этой директории:
<project>
├── src
│ ├── <module>/*
│ │ ├── __init__.py
│ │ └── many_files.py
│ │
│ └── tests/*
│ └── many_tests.py
│
├── .gitignore
├── pyproject.toml
└── README.md
Здесь <module> — это главный модуль проекта. Если вы не знаете точно — какой именно модуль у вас главный — подумайте о том, что пользователи проекта будут устанавливать командой pip install, и о том, как, по вашему мнению, должна выглядеть команда import для вашего модуля.
Часто имя главного модуля совпадает с именем всего проекта. Но это — не некое жёсткое правило.
Аргументы в пользу директории src
Я видел множество проектов, устроенных по-другому.Например, в проекте может отсутствовать директория src, а все модули будут просто лежать в его корневой директории:
non_recommended_project
├── <module_a>/*
│ ├── __init__.py
│ └── many_files.py
│
├── .gitignore
│
├── tests/*
│ └── many_tests.py
│
├── pyproject.toml
│
├── <module_b>/*
│ ├── __init__.py
│ └── many_files.py
│
└── README.md
Уныло смотрится проект, в структуре которого нет никакого порядка из-за того, что его папки и файлы просто расположены по алфавиту, в соответствии с правилами сортировки объектов в IDE.
Главная причина, по которой рекомендуется пользоваться папкой src, заключается в том, чтобы активный код проекта был бы собран в одной директории, а настройки, параметры CI/CD, метаданные проекта находились бы за пределами этой директории.
Единственный минус такого подхода заключается в том, что, без дополнительных усилий, не получится воспользоваться в своём коде командой вида import module_a. Для этого потребуется кое-что сделать. Ниже мы поговорим о том, как решить эту проблему.
Именование файлов
Правило №1: тут нет файлов
Во-первых — в Python нет таких сущностей, как «файлы», и я заметил, что это — главный источник путаницы для новичков.Если вы находитесь в директории, содержащей файл __init__.py, то это — директория, включающая в себя модули, а не файлы.
Рассматривайте каждый модуль, как пространство имён.
Я говорю о «пространстве имён», так как нельзя сказать с уверенностью — имеется ли в модуле множество функций и классов, или только константы. В нём может присутствовать практически всё что угодно, или лишь несколько сущностей пары видов.
Правило №2: если нужно — держите сущности в одном месте
Совершенно нормально, когда в одном модуле имеется несколько классов. Так и стоит организовывать код (но, конечно, только если классы связаны с модулем).Выделяйте классы в отдельные модули только в том случае, если модуль становится слишком большим, или если его разные части направлены на решение различных задач.
Часто встречается мнение, что это — пример неудачного приёма работы. Те, кто так считают, находятся под влиянием опыта, полученного после использования других языков программирования, которые принуждают к другим решениям (например — это Java и C#).
Правило №3: давайте модулям имена, представляющие собой существительные во множественном числе
Давая модулям имена, следуйте общему правилу, в соответствии с которым эти имена должны представлять собой существительные во множественном числе. При этом они должны отражать особенности предметной области проекта.Правда, у этого правила есть и исключение. Модули могут называться core, main.py или похожим образом, что указывает на то, что они представляют собой некую единичную сущность. Подбирая имена модулей, руководствуйтесь здравым смыслом, а если сомневаетесь — придерживайтесь вышеприведённого правила.
Реальный пример именования модулей
Вот мой проект — Google Maps Crawler, созданный в качестве примера.Этот проект направлен на сбор данных из Google Maps с использованием Selenium и на их представление в виде, удобном для дальнейшей обработки (тут, если интересно, можно об этом почитать).
Вот текущее состояние дерева проекта (тут выделены исключения из правила №3):
gmaps_crawler
├── src
│ └── gmaps_crawler
│ ├── __init__.py
│ ├── config.py (форма единственного числа)
│ ├── drivers.py
│ ├── entities.py
│ ├── exceptions.py
│ ├── facades.py
│ ├── main.py (форма единственного числа)
│ └── storages.py
│
├── .gitignore
├── pyproject.toml
└── README.md
Весьма естественным кажется такой импорт классов и функций:
from gmaps_crawler.storages import get_storage
from gmaps_crawler.entities import Place
from gmaps_crawler.exceptions import CantEmitPlace
Можно понять, что в exceptions может иметься как один, так и множество классов исключений.
Именование модулей существительными множественного числа отличается следующими приятными особенностями:
- Модули не слишком «малы» (в том смысле, что предполагается, что один модуль может включать в себя несколько классов).
- Их, если нужно, в любой момент можно разбить на более мелкие модули.
- «Множественные» имена дают программисту сильное ощущение того, что он знает о том, что может быть внутри соответствующих модулей.
Именование классов, функций и переменных
Некоторые программисты считают, что давать сущностям имена — это непросто. Но если заранее определиться с правилами именования, эта задача становится уже не такой сложной.Имена функций и методов должны быть глаголами
Функции и методы представляют собой действия, или нечто, выполняющее действия.Функция или метод — это не просто нечто «существующее». Это — нечто «действующее».
Действия чётко определяются глаголами.
Вот — несколько удачных примеров из реального проекта, над которым я раньше работал:
def get_orders():
...
def acknowledge_event():
...
def get_delivery_information():
...
def publish():
...
А вот — несколько неудачных примеров:
def email_send():
...
def api_call():
...
def specific_stuff():
...
Тут не очень ясно — возвращают ли функции объект, позволяющий выполнить обращение к API, или они сами выполняют какие-то действия, например — отправку письма.
Я могу представить себе такой сценарий использования функции с неудачным именем:
email_send.title = "title"
email_send.dispatch()
У рассмотренного правила есть и некоторые исключения:
- Создание функции main(), которую вызовут в главной точке входа приложения — это хороший повод нарушить это правило.
- Использование @property для того, чтобы обращаться с методом класса как с атрибутом, тоже допустимо.
Имена переменных и констант должны быть существительными
Имена переменных и констант всегда должны быть существительными и никогда — глаголами (это позволяет чётко отделить их от функций).Вот примеры удачных имён:
plane = Plane()
customer_id = 5
KEY_COMPARISON = "abc"
Вот — неудачные имена:
fly = Plane()
get_customer_id = 5
COMPARE_KEY = "abc"
А если переменная или константа представляют собой список или коллекцию — им подойдёт имя, представленное существительным во множественном числе:
planes: list[Plane] = [Plane()] # Даже если содержит всего один элемент
customer_ids: set[int] = {5, 12, 22}
KEY_MAP: dict[str, str] = {"123": "abc"} # Имена словарей остаются существительными в единственном числе
Имена классов должны говорить сами за себя, но использование суффиксов — это нормально
Отдавайте предпочтение именам классов, понятным без дополнительных пояснений. При этом можно использовать и суффиксы, вроде Service, Strategy, Middleware, но — только в крайнем случае, когда они необходимы для чёткого описания цели существования класса.Всегда давайте классам имена в единственном, а не во множественном числе. Имена во множественном числе напоминают имена коллекций элементов (например — если я вижу имя orders, то я полагаю, что это — список или итерируемый объект). Поэтому, выбирая имя класса, напоминайте себе, что после создания экземпляра класса в нашем распоряжении оказывается единственный объект.
Классы представляют собой некие сущности
Классы, представляющие нечто из бизнес-среды, должны называться в соответствии с названиями связанных с ними сущностей (и имена должны быть существительными!). Например — Order, Sale, Store, Restaurant и так далее.Пример использования суффиксов
Представим, что надо создать класс, ответственный за отправку электронных писем. Если назвать его просто Email, цель его существования будет неясна.Кто-то может решить, что он может олицетворять некую сущность:
email = Email() # Предполагаемый пример использования
email.title = "Title"
email.body = create_body()
email.send_to = "guilatrova.dev"
send_email(email)
Такой класс следует назвать EmailSender или EmailService.
Соглашения по именованию сущностей
Следуйте этим соглашениям по именованию сущностей:Тип | Общедоступный | Внутренний |
Пакеты (директории) | lower_with_under | — |
Модули (файлы) | lower_with_under.py | — |
Классы | CapWords | — |
Функции и методы | lower_with_under() | _lower_with_under() |
Константы | ALL_CAPS_UNDER | _ALL_CAPS_UNDER |
Отступление о «приватных» методах
Если имя метода выглядит как __method(self) (любой метод, имя которого начинается с двух символов подчёркивания), то Python не позволит внешним классам/методам вызывать этот метод обычным образом. Некоторые, узнавая об этом, считают, что это нормально.Тем, кто, вроде меня, пришёл в Python из C#, может показаться странным то, что (пользуясь вышеприведённым руководством) метод класса нельзя защитить.
Но у Гвидо ван Россума есть достойная причина считать, что на это есть веские основания: «Мы все тут взрослые, ответственные люди».
Это значит, что если вы знаете, что не должны вызывать метод, тогда вы и не будете этого делать — если только не абсолютно уверены в своих действиях.
В конце концов, если вы и правда решите вызвать некий приватный метод, то вы для этого сделаете что-то неординарное (в C# это называется Reflection).
Поэтому давайте своим приватным методам/функциям имена, начинающиеся с одного символа подчёркивания, указывающего на то, что они предназначены лишь для внутреннего использования, и смиритесь с этим.
Когда создавать функцию, а когда — класс?
Мне несколько раз задавали вопрос, вынесенный в заголовок этого раздела.Если вы следуете рекомендациям, приведённым выше, то ваши модули будут понятными, а понятные модули — это эффективный способ организации функций:
from gmaps_crawler import storages
storages.get_storage() # Похоже на класс, но экземпляр не создаётся, а имя - это существительное во множественном числе
storages.save_to_storage() # Так может называться функция, хранящаяся в модуле
Иногда в модуле можно разглядеть некое подмножество чем-то связанных функций. В таких случаях подобные функции имеет смысл выделить в класс.
Пример группировки подмножества функций
Предположим, имеется уже встречавшийся нам модуль storages с 4 функциями:def format_for_debug(some_data):
...
def save_debug(some_data):
"""Выводит данные на экран"""
formatted_data = format_for_debug(some_data)
print(formatted_data)
def create_s3(bucket):
"""Создаёт бакет s3, если он не существует"""
...
def save_s3(some_data):
s3 = create_s3("bucket_name")
...
S3 — это облачное хранилище Amazon (AWS), подходящее для хранения любых данных. Это — нечто вроде Google Drive для программ.
Проанализировав этот код, мы можем сказать следующее:
- Разработчик может сохранять данные в режиме отладки (save_debug) (они просто выводятся на экран), или в S3 (save_s3) (они попадают в облако).
- Функция save_debug использует функцию format_for_debug.
- Функция save_s3 использует функцию create_s3.
class DebugStorage:
def format_for_debug(self, some_data):
...
def save_debug(self, some_data):
"""Выводит данные на экран"""
formatted_data = self.format_for_debug(some_data)
print(formatted_data)
class S3Storage:
def create_s3(self, bucket):
"""Создаёт бакет s3, если он не существует"""
...
def save_s3(self, some_data):
s3 = self.create_s3("bucket_name")
...
Вот эмпирическое правило, помогающее решить вопрос о функциях и классах:
- Всегда начинайте с функций.
- Переходите к классам в том случае, если у вас возникает ощущение, что вы можете сгруппировать различные подмножества функций.
Создание модулей и точки входа в приложение
У каждого приложения есть точка входа.То есть — имеется единственный модуль (другими словами — файл), который запускает приложение. Это может быть как отдельный скрипт, так и большой модуль.
Когда бы вы ни создавали точку входа в приложение — обязательно добавьте в код проверку на то, что этот код выполняется, а не импортируется:
def execute_main():
...
if __name__ == "__main__": # Добавьте это условие
execute_main()
Сделав это, вы обеспечите то, что импорт этого кода не приведёт к его случайному выполнению. Выполняться он будет только в том случае, если будет запущен явным образом.
Файл __main__.py
Вы, возможно, заметили, что некоторые Python-пакеты можно вызывать, пользуясь ключом -m:python -m pytest
python -m tryceratops
python -m faust
python -m flake8
python -m black
Система относится к таким пакетам почти как к обычным утилитам командной строки, так как запускать их ещё можно так:
pytest
tryceratops
faust
flake8
black
Для того чтобы оснастить ваш проект такой возможностью — нужно добавить файл __main.py__ в главный модуль:
<project>
├── src
│ ├── example_module Главный модуль
│ │ ├── __init__.py
│ │ ├── __main__.py Добавьте сюда этот файл
│ │ └── many_files.py
│ │
│ └── tests/*
│ └── many_tests.py
│
├── .gitignore
├── pyproject.toml
└── README.md
И не забудьте, что и тут, в файле __main__.py, понадобится проверка __name__ == "__main__".
Когда вы установите свой модуль — вы сможете запускать его командой вида python -m example_module.
Как организовать код в Python-проекте, чтобы потом не пожалеть
Каждая минута, потраченная на организацию своей деятельности, экономит вам целый час. Бенджамин Франклин Python отличается от таких языков программирования, как C# или Java, заставляющих программиста...
habr.com