Python как оформить программу

Как организовать код в Python-проекте, чтобы потом не пожалеть

Python отличается от таких языков программирования, как C# или Java, заставляющих программиста давать классам имена, соответствующие именам файлов, в которых находится код этих классов.

Python — это самый гибкий язык программирования из тех, с которыми мне приходилось сталкиваться. А когда имеешь дело с чем-то «слишком гибким» — возрастает вероятность принятия неправильных решений.

• Хотите держать все классы проекта в единственном файле main.py ? Да, это возможно.
• Надо читать переменную окружения? Берите и читайте там, где это нужно.
• Требуется модифицировать поведение функции? Почему бы не прибегнуть к декоратору!?

Применение многих идей, которые легко реализовать, может привести к негативным последствиям, к появлению кода, который очень тяжело поддерживать.

Но, если вы точно знаете о том, что делаете, последствия гибкости Python не обязательно окажутся плохими.

Здесь я собираюсь представить вашему вниманию рекомендации по организации Python-кода, которые сослужили мне хорошую службу, когда я работал в разных компаниях и взаимодействовал со многими людьми.

Структура Python-проекта

Сначала обратим внимание на структуру директорий проекта, на именование файлов и организацию модулей.

Рекомендую держать все файлы модулей в директории src , а тесты — в поддиректории tests этой директории:

 ├── src │ ├── /* │ │ ├── __init__.py │ │ └── many_files.py │ │ │ └── tests/* │ └── many_tests.py │ ├── .gitignore ├── pyproject.toml └── README.md

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

Часто имя главного модуля совпадает с именем всего проекта. Но это — не некое жёсткое правило.

Аргументы в пользу директории src

Я видел множество проектов, устроенных по-другому.

Например, в проекте может отсутствовать директория src , а все модули будут просто лежать в его корневой директории:

non_recommended_project ├── /* │ ├── __init__.py │ └── many_files.py │ ├── .gitignore │ ├── tests/* │ └── many_tests.py │ ├── pyproject.toml │ ├── /* │ ├── __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] = KEY_MAP: dict[str, str] = # Имена словарей остаются существительными в единственном числе

Имена классов должны говорить сами за себя, но использование суффиксов — это нормально

Отдавайте предпочтение именам классов, понятным без дополнительных пояснений. При этом можно использовать и суффиксы, вроде 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 .

Соглашения по именованию сущностей

Следуйте этим соглашениям по именованию сущностей:

Тип

Общедоступный

Внутренний

Пишем программу на Python с помощью ChatGPT

Представим ситуацию: мы не умеем программировать на Python, но знаем, что ChatGPT умеет. Наша задача — не написав самим ни одной строчки кода, создать код, который будет делать что-то полезное. Всё, что мы можем делать — это отправлять запросы в чат, брать оттуда код и смотреть на результат. Заодно узнаем, получится ли так программировать или нет.

Что делаем

Мы попросим ChatGPT написать код, который угадает число от 1 до 100 за 7 попыток. В «Коде» мы уже писали про эту задачу и про алгоритм её решения, поэтому будем сверяться с ним.

Для решения используем сервис Chad — внутри ChatGPT 3.5 и 4 на выбор, работает в России без ВПН и понимает русский язык.

Первый подход: код есть, но не работает

Открываем Chad и выбираем режим для разработчиков, который посередине:

Пишем запрос в самой простой форме, указывая только ключевые моменты:

Напиши программу на Python, которая угадывает число, которое загадал пользователь от 1 до 100 за 7 попыток или меньше.

В ответ сервис даёт код и поясняет, что он делает: как будет работать и для чего нужна определённая переменная:

import random def guess_number(start, end, max_attempts): print(f"Загадайте число от до . Я попытаюсь его угадать за попыток или меньше.") low = start high = end for attempt in range(1, max_attempts + 1): guess = random.randint(low, high) print(f"Попытка #: Я думаю, это число .") if guess == user_number: print("Ура! Я угадал число!") return elif guess < user_number: print("Мое число слишком маленькое.") low = guess + 1 else: print("Мое число слишком большое.") high = guess - 1 print("К сожалению, я не смог угадать число за заданное количество попыток.") user_number = random.randint(1, 100) # Пользователь загадывает число от 1 до 100 guess_number(1, 100, 7)

Но при запуске этого кода мы получаем странный результат — программа моментально проходит 7 попыток и сообщает, что ничего не угадала:

Второй подход: исправляем ошибку

Раз компьютер не отгадал число за 7 попыток, значит, с алгоритмом явно что-то не так. Просим объяснить, что происходит в программе:

Прокомментируй в этом коде каждую строку

Это код на языке Python, который представляет собой простую игру "угадай число". Давай разберем его построчно:

1. `import random` - импорт модуля random, который позволяет нам генерировать случайные числа.

2. `def guess_number(start, end, max_attempts):` - определение функции с именем `guess_number`, которая принимает три аргумента: `start` (начальное значение диапазона чисел), `end` (конечное значение диапазона чисел) и `max_attempts` (максимальное количество попыток).

3. `print(f"Загадайте число от до . Я попытаюсь его угадать за попыток или меньше.")` - выводит сообщение с использованием значений `start`, `end` и `max_attempts` для подсказки пользователю о правилах игры.

4. `low = start` - присваивает переменной `low` значение `start`. Переменная `low` будет использоваться для хранения текущего нижнего значения диапазона.

5. `high = end` - присваивает переменной `high` значение `end`. Переменная `high` будет использоваться для хранения текущего верхнего значения диапазона.

6. `for attempt in range(1, max_attempts + 1):` - начинает цикл, который будет выполняться `max_attempts` раз. Переменная `attempt` будет принимать значения от 1 до `max_attempts`.

7. `guess = random.randint(low, high)` - генерирует случайное число в диапазоне от `low` до `high` и присваивает его переменной `guess`. Это предполагаемое число, которое попытается угадать компьютер

8. `print(f"Попытка #: Я думаю, это число .")` - выводит сообщение с использованием текущего значения `attempt` и `guess` для показа предполагаемого числа компьютера.

9. `if guess == user_number:` - проверяет, равно ли предполагаемое число `guess` загаданному пользователем числу `user_number`.

10. `print("Ура! Я угадал число!")` - выводит сообщение, если компьютер угадал число пользователя.

11. `return` - прерывает выполнение функции и возвращает управление обратно в основную программу.

13. `print("Мое число слишком маленькое.")` - выводит сообщение, если предполагаемое число `guess` слишком маленькое.

14. `low = guess + 1` - присваивает переменной `low` значение `guess + 1`, чтобы ограничить будущие предполагаемые числа в большем диапазоне.

15. `else:` - выполняется, если ни одно из предыдущих условий не выполнилось, что означает, что `guess` больше, чем `user_number`.

16. `print("Мое число слишком большое.")` - выводит сообщение, если предполагаемое число `guess` слишком большое.

17. `high = guess - 1` - присваивает переменной `high` значение `guess - 1`, чтобы ограничить будущие предполагаемые числа в меньшем диапазоне.

18. `print("К сожалению, я не смог угадать число за заданное количество попыток.")` - выводит сообщение, если компьютер не смог угадать число в заданное количество попыток.

19. `user_number = random.randint(1, 100)` - генерирует случайное число от 1 до 100 и присваивает его переменной `user_number`. Это число, которое пользователь должен загадать.

20. `guess_number(1, 100, 7)` - вызывает функцию `guess_number` с аргументами `1`, `100` и `7`. Это начинает игру, где пользователь должен загадать число от 1 до 100, а компьютер будет пытаться угадать за 7 попыток или меньше.

Ага, значит, значение переменной guess, которая отвечает за очередную попытку угадать число, выбирается случайным образом (точно так же, как это делает user_number ). Но в теоретическом решении написано, что нужно взять диапазон и поделить его пополам. Значит, нам нужно попросить исправить код, чтобы диапазон делился пополам:

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

Вот что получили в ответ:

Понимаю, извините за путаницу. Вот исправленный код, который выполняет угадывание числа путем деления диапазона пополам.
В этом обновленном коде используется метод деления диапазона пополам для каждой попытки. Вместо случайного числа, программе необходимо определить середину текущего диапазона (guess = (low + high) // 2).
После предложения числа пользователь проверяет ответ и сообщает программе, является ли загаданное число больше или меньше предложенного числа. Затем диапазон обновляется путем изменения нижней или верхней границы в зависимости от ответа пользователя.

def guess_number(start, end, max_attempts): print(f"Загадайте число от до . Я попытаюсь его угадать за попыток или меньше.") low = start high = end for attempt in range(1, max_attempts + 1): guess = (low + high) // 2 print(f"Попытка #: Я думаю, это число .") if guess == user_number: print("Ура! Я угадал число!") return elif guess < user_number: print("Мое число слишком маленькое.") low = guess + 1 else: print("Мое число слишком большое.") high = guess - 1 print("К сожалению, я не смог угадать число за заданное количество попыток.") user_number = random.randint(1, 100) # Пользователь загадывает число от 1 до 100 guess_number(1, 100, 7)

Копируем, вставляем в редактор кода, запускаем — и получаем ошибку NameError: name 'random' is not defined . Спрашиваем, что с ней делать:

Что означает ошибка NameError: name 'random' is not defined и как её исправить

Вот что предлагает ChatGPT:

Ошибка NameError: name 'random' is not defined возникает, когда пытаемся использовать имя, которое не было определено или импортировано в текущей области видимости.

В приведенном коде, ошибка может возникнуть, если модуль random не был импортирован в вашей программе.

Чтобы исправить эту проблему, в начале программы добавьте строку import random. Это позволит использовать функции и классы из модуля random.

Оказывается, сервис забыл добавить команду import random, чтобы можно было пользоваться генератором случайных чисел. Берём её из первой версии кода и запускаем:

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

Третий подход: добавляем интерактив

Чтобы пользователь тоже поучаствовал в игре, просим ChatGPT добавить интерактив:

Сейчас у тебя в коде загаданное число задаётся случайным образом. Сделай так, чтобы пользователь сам вводил число, которое он загадал.

Вот что получаем в ответ:

В этой версии кода после предложения ввести число пользователь будет приглашен ввести загаданное число, с которым программа будет пытаться угадать. Загаданное число сохраняется в переменную user_number в виде целого числа с помощью функции int(input()).

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

def guess_number(start, end, max_attempts): print(f"Загадайте число от до . Я попытаюсь его угадать за попыток или меньше.") low = start high = end user_number = int(input("Введите загаданное число: ")) for attempt in range(1, max_attempts + 1): guess = (low + high) // 2 print(f"Попытка #: Я думаю, это число .") if guess == user_number: print("Ура! Я угадал число!") return elif guess < user_number: print("Мое число слишком маленькое.") low = guess + 1 else: print("Мое число слишком большое.") high = guess - 1 print("К сожалению, я не смог угадать число за заданное количество попыток.") guess_number(1, 100, 7)

Уже интереснее, но всё равно игра проходит слишком быстро. Надо поменять компьютер и игрока местами, чтобы игрок сам отвечал на вопросы, давая подсказки компьютеру.

Четвёртый подход: добавляем ответы игрока

Улучшаем код и пишем такой запрос:

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

Сервис сразу меняет код и даёт большое пояснение, как что внутри работает:

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

На каждой итерации цикла программа предлагает свой вариант с помощью переменной guess, затем ожидает ввода пользователя с помощью input(). Ввод пользователя сохраняется в переменную user_input.

Затем, в зависимости от ответа пользователя, программе сообщается об изменении диапазона для следующей попытки. Если число пользователя больше предложенного, мы обновляем нижнюю границу, увеличивая ее на 1 (low = guess + 1). Если число пользователя меньше предложенного, обновляем верхнюю границу, уменьшая ее на 1 (high = guess - 1). Если число пользователя равно предложенному, программа завершается.

def guess_number(start, end): print(f"Загадайте число от до . Я попытаюсь его угадать.") low = start high = end while True: guess = (low + high) // 2 print(f"Я думаю, это число .") user_input = input("Ваше число больше (>), меньше (<) или равно (=) предложенному? ") if user_input == '>': low = guess + 1 elif user_input == '

def guess_number(start, end): print(f"Загадайте число от до . Я попытаюсь его угадать.") low = start high = end attempts = 0 while True: guess = (low + high) // 2 attempts += 1 print(f"Попытка #: Я думаю, это число .") user_input = input("Ваше число больше (>), меньше (<) или равно (=) предложенному? ") if user_input == '>': low = guess + 1 elif user_input == ' <': high = guess - 1 elif user_input == '=': print(f"Ура! Я угадал число за попыток!") return else: print("Некорректный ввод. Попробуйте снова.") print("К сожалению, я не смог угадать число.") guess_number(1, 100)

from termcolor import colored def guess_number(start, end): print(f"Загадайте число от до . Я попытаюсь его угадать.") low = start high = end attempts = 0 while True: guess = (low + high) // 2 attempts += 1 print(colored(f"Попытка #: Я думаю, это число .", 'green')) user_input = input("Ваше число больше (>), меньше (<) или равно (=) предложенному? ") if user_input == '>': low = guess + 1 elif user_input == ' <': high = guess - 1 elif user_input == '=': print(colored(f"Ура! Я угадал число за попыток!", 'blue')) return else: print("Некорректный ввод. Попробуйте снова.") print("К сожалению, я не смог угадать число.") guess_number(1, 100)