Введение

Большинство Python‑проектов начинается одинаково: один файл, удачная идея и мысль: «Соберу это за один вечер». Через неделю этот быстрый скрипт превращается в критичный инструмент для вашей команды (или для вас), и внезапно:

• Страшно трогать код — вдруг всё сломается.
• Никто (включая вас) уже не помнит, как ставить зависимости.
• Добавление новых фич больше похоже на хождение по минному полю.

Разница между хрупким скриптом и поддерживаемым приложением — не магия, а набор привычек и простых инструментов.

В этой статье разберём, как прокачать ваш пет‑проект: перейти от одного Python‑файла к небольшому, но серьёзному приложению. Поговорим о:

• Виртуальных окружениях и воспроизводимых установках
• Чёткой структуре проекта
• Именовании, докстрингах и самодокументируемом коде
• Учёте зависимостей через requirements.txt
• Контроле версий с Git
• Автоматическом тестировании, линтинге и форматировании
• Упаковке и распространении приложения

Не обязательно внедрять всё сразу. Относитесь к этому как к дорожной карте: начните с базы и развивайте практики по мере роста проекта.

1. Начните с виртуального окружения

Виртуальное окружение изолирует зависимости проекта от глобальной установки Python. Это значит, что:

• Больше никаких «у меня на машине работало».
• В разных проектах можно использовать разные версии библиотек.
• Окружение можно воспроизвести позже (или на другой машине).

Самый распространённый вариант — использовать встроенный модуль venv:

# Создать виртуальное окружение
python -m venv .venv

# Активировать (Linux/macOS)
source .venv/bin/activate

# Или в Windows
.venv\Scripts\activate

# Устанавливать пакеты внутрь этого окружения
pip install requests rich

После активации команды python и pip будут относиться именно к этому окружению. Сделайте привычкой:

• Создавать виртуальное окружение самым первым шагом в любом новом проекте.
• Добавлять .venv/ (или как вы его назвали) в .gitignore, чтобы не коммитить его в репозиторий.

Один этот шаг сэкономит вам массу головной боли в будущем.

2. Дайте проекту понятную структуру

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

• Несколько модулей (файлов)
• Тесты
• Конфигурацию
• Возможность упаковки в пакет

Простой и гибкий вариант структуры для небольшого приложения может выглядеть так:

my_app/
├─ src/
│  └─ my_app/
│     ├─ __init__.py
│     ├─ cli.py
│     ├─ core.py
│     └─ utils.py
├─ tests/
│  ├─ __init__.py
│  └─ test_core.py
├─ requirements.txt
├─ pyproject.toml  # или setup.cfg/setup.py, если позже будете паковать проект
├─ README.md
└─ .gitignore

Ключевые идеи:

• src/my_app/ хранит код приложения, а не корень репозитория. Это помогает отлавливать ошибки с импортами и отражает то, как приложение будет установлено как пакет.
• tests/ — место для автоматических тестов.
• README.md объясняет, что делает проект и как его запускать.
• Файлы __init__.py превращают каталоги в полноценные Python‑пакеты.

Необязательно иметь всё это с первого дня, но переход от одного плоского файла к структурированному проекту — один из самых заметных «уровней прокачки» любого пет‑проекта.

3. Даёте хорошим именам и докстрингам

По мере роста кодовой базы хорошие имена и документация становятся лучшей защитой от хаоса.

Осмысленные имена

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

• process_invoice() вместо proc_inv()
• download_report() вместо dr()
• user_repository.py вместо db.py

Группируйте по ответственности: например, логику командной строки — в cli.py, бизнес‑логику — в core.py, вспомогательные функции — в utils.py (или давайте более точные имена по мере развития проекта).

Докстринги

Докстринги располагаются в начале модулей, функций, классов и методов. Они делают код самодокументируемым и помогают IDE и другим инструментам показывать подсказки и описание параметров.

# src/my_app/core.py


def calculate_discount(price: float, percentage: float) -> float:
    """Вернуть цену после применения процентной скидки.

    Args:
        price: Исходная цена товара.
        percentage: Скидка в процентах, значение от 0 до 100.

    Returns:
        Цена с учётом скидки.
    """
    return price * (1 - percentage / 100)

Когда вы (или кто‑то ещё) вернётесь к этому коду через полгода, намерение будет очевидно.

4. Фиксируйте зависимости в requirements.txt

Как только вы начинаете ставить сторонние пакеты (например, requests, pydantic, rich), нужно зафиксировать, что именно нужно проекту.

Файл requirements.txt позволяет другим (и вам в будущем) установить ровно те зависимости, которые нужны вашему приложению:

pip install -r requirements.txt

Сгенерировать файл можно из активного виртуального окружения:

pip freeze > requirements.txt

Это запишет точные версии, например:

requests==2.32.3
rich==13.9.1

Рекомендации:

• Обновляйте requirements.txt каждый раз, когда добавляете или удаляете зависимости.
• Коммитьте его в репозиторий, чтобы окружение было воспроизводимым.
• Подумайте о разделении рантайм‑ и dev‑зависимостей (например, requirements.txt и requirements-dev.txt), особенно если тестовые и линтер‑инструменты нужны только при разработке.

Позже вы можете перейти на рабочий процесс с pyproject.toml или использовать Poetry и др., но requirements.txt — простой и эффективный старт.

5. Используйте контроль версий с первого дня

Контроль версий нужен не только командам; он нужен для борьбы прошлого вас с будущим вами.

Использование Git даёт вам:

• Историю изменений
• Возможность экспериментировать в ветках
• Безопасный откат, если что‑то сломалось
• Простое сотрудничество (и бэкапы) через GitHub, GitLab и т.п.

Базовая настройка:

git init

echo "*.pyc
__pycache__/ 
.venv/" > .gitignore

git add .
git commit -m "Initial commit: basic project structure"

В процессе работы:

• Делайте небольшие, логически цельные коммиты с понятными сообщениями.
• Используйте ветки для фич (feature/add-report-export) и исправлений (fix/discount-rounding).
• Пушьте на удалённый репозиторий ради бэкапа и совместной работы.

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

6. Добавьте тесты, линтер и форматтер

Когда ваш скрипт становится важным, ручного тестирования уже недостаточно. Нужны автоматические проверки, которые запускаются при каждом изменении кода.

Автоматическое тестирование

Простой старт — использовать pytest:

pip install pytest

Создайте файл тестов, например tests/test_core.py:

# tests/test_core.py
from my_app.core import calculate_discount


def test_calculate_discount():
    assert calculate_discount(100, 10) == 90

Запустите:

pytest

По мере добавления фич или исправления багов добавляйте тесты. Со временем набор тестов станет для вас «страховочной сеткой» при рефакторинге.

Линтинг и форматирование

Линтеры и форматтеры помогают держать код чистым и единообразным автоматически.

Популярные варианты:

• Flake8 или Ruff — линтеры: находят стилистические проблемы и потенциальные ошибки
• Black — форматтер: приводит код к единому стилю
• isort — сортирует импорты

Пример установки:

pip install black ruff isort

Запуск вручную:

black src tests
ruff src tests
isort src tests

Их также можно настроить через pyproject.toml, чтобы они запомнили ваши предпочтения.

Дополнительно можно:

• Подключить pre-commit hooks (с помощью утилиты pre-commit), чтобы линтеры и форматтеры автоматически запускались перед каждым коммитом.
• Настроить редактор или IDE на автоформатирование при сохранении.

Это снижает количество споров о стиле и освобождает голову для решения логических задач, а не вопросов расстановки пробелов.

7. Упакуйте и распространяйте приложение

Когда ваш пет‑проект становится реально полезным, может захотеться:

• Устанавливать его на другие машины через pip install my-app.
• Поделиться им с коллегами или сообществом.
• Дать нетехническим пользователям один исполняемый файл.

Основы упаковки Python‑приложения

Современная упаковка Python всё чаще строится вокруг pyproject.toml. Минимальный пример для устанавливаемого CLI‑приложения:

[project]
name = "my-app"
version = "0.1.0"
description = "A handy CLI tool that does X"
readme = "README.md"
requires-python = ">=3.10"

[project.scripts]
my-app = "my_app.cli:main"

Имея такой файл и выбрав сборщик (build backend), например setuptools или hatchling, можно собрать и установить проект локально:

pip install build
python -m build
pip install dist/my_app-0.1.0-py3-none-any.whl

Теперь вы можете запускать my-app из командной строки как установленную команду.

Шаблоны и инструменты

Упаковка может быть немного муторной, поэтому шаблоны проектов и генераторы сильно упрощают старт, предлагая готовые «best practices»:

• pyOpenSci copier templates: даёт готовые, «мнениями нагруженные» шаблоны проектов с тестами, документацией и CI «из коробки».
• Шаблоны самих фреймворков (например, fastapi или django-admin startproject), если ваш проект вписывается в эти экосистемы.

Такие шаблоны часто включают:

• Стандартизированную структуру
• Конфигурацию для линтеров и форматтеров
• Примеры документации и CI

Однофайловые исполняемые файлы

Если нужно отдать пользователям, у которых нет Python, один исполняемый файл:

• Инструменты вроде PyInstaller, cx_Freeze или другие «bundler’ы» в стиле py2exe могут собрать ваш код и зависимости в автономный исполняемый файл.
• Это удобно для внутренних утилит и десктопных приложений, где установка Python нежелательна.

Учтите, что такие сборки обычно получаются довольно крупными и зависят от платформы (отдельная сборка для Windows, отдельная — для macOS и т.д.), но для конечных пользователей это очень удобно.

Заключение

Преобразование «быстрого» скрипта в поддерживаемое Python‑приложение — это не столько про полную переписку, сколько про добавление структуры и защитных механизмов:

• Используйте виртуальное окружение, чтобы изолировать зависимости.
• Введите понятную структуру проекта, чтобы код мог расти без хаоса.
• Давайте осмысленные имена и пишите докстринги, чтобы код объяснял себя сам.
• Фиксируйте зависимости в requirements.txt для простых и воспроизводимых установок.
• Ведите проект в Git, чтобы безопасно экспериментировать, откатываться и сотрудничать.
• Добавьте автоматические тесты, линтер и форматтер, чтобы сохранять качество по мере развития.
• Осваивайте упаковку и бандлинг, когда будете готовы делиться приложением шире.

Не нужно ждать «большого» или «официального» продукта, чтобы применять такие практики. Если использовать их в пет‑проектах, работать над ними становится приятнее, делиться — проще, а сами проекты — гораздо менее хрупкими.

Начните с одного улучшения — например, сегодня настройте виртуальное окружение и Git, на следующей неделе добавьте тесты и форматирование — и продолжайте прокачивать проект. Будущий вы (и все пользователи вашего приложения) это оценят.