Python Pro: От учебных скриптов к реальным продуктам

Экосистема профи: Git, виртуальные окружения и стандарты кода

Добро пожаловать в профессиональную лигу. Если раньше ваш код жил в одном файле main.py на рабочем столе, а библиотеки устанавливались глобально командой pip install, то сегодня мы меняем правила игры.

Переход от любителя к профессионалу начинается не со знания сложных алгоритмов, а с организации рабочего пространства. В этой статье мы настроим фундамент, на котором будут строиться все наши будущие проекты: от CLI-утилит до веб-сервисов.

Почему «работает на моем компьютере» — это не аргумент

Представьте, что вы строите дом. Любительский подход — это прийти на стройку с одним молотком и кучей разнородных материалов, сваленных в кучу. Профессиональный подход — это организованный склад, четкие чертежи и стандартизированные инструменты.

В Python «склад» и «инструменты» — это виртуальные окружения, управление зависимостями и контроль версий. Без них любой проект сложнее «Hello World» обречен на так называемый «Dependency Hell» (Ад зависимостей).

Виртуальные окружения: Изоляция прежде всего

Главное правило Python-разработчика: никогда не устанавливайте пакеты в системный интерпретатор.

Почему? Представьте, что Проекту А нужен Django 3.0, а Проекту Б — Django 4.0. Если вы ставите их глобально, один из проектов перестанет работать. Виртуальное окружение (venv) создает изолированную папку с собственной копией интерпретатора Python и менеджера пакетов pip.

Классический подход: venv

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

# Windows
python -m venv venv

# macOS / Linux
python3 -m venv venv

После создания его нужно активировать:

• Windows: venv\Scripts\activate
• macOS / Linux: source venv/bin/activate

Когда окружение активировано, в терминале появится префикс (venv). Теперь все, что вы установите через pip install, попадет только в эту папку.

Современный стандарт: Poetry

Хотя venv и requirements.txt (список зависимостей) являются классикой, индустрия движется к более мощным инструментам. Мы в курсе будем использовать Poetry.

Poetry решает сразу три задачи:

1. Управляет виртуальным окружением (создает его сама).
2. Управляет зависимостями (разрешает конфликты версий).
3. Помогает упаковывать проект для публикации.

Установка Poetry (выполняется один раз глобально):

# macOS / Linux / WSL
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

Инициализация нового проекта:

poetry new my-project

Это создаст правильную структуру папок и файл pyproject.toml — паспорт вашего проекта.

Управление зависимостями: pyproject.toml

Файл requirements.txt — это просто список. Файл pyproject.toml — это декларация. В нем описывается не только то, какие библиотеки нужны, но и какие версии совместимы, а также настройки инструментов разработки.

Пример добавления библиотеки через Poetry:

poetry add requests

Poetry автоматически:

1. Найдем подходящую версию requests.
2. Скачает её и все её зависимости.
3. Запишет информацию в pyproject.toml и poetry.lock.

Файл poetry.lock критически важен. Он «замораживает» конкретные версии всех установленных пакетов. Это гарантирует, что если ваш коллега скачает проект и запустит poetry install, у него будет бит-в-бит то же самое окружение, что и у вас.

Git: Ваша машина времени

Git — это не просто способ сохранить код. Это история развития вашего продукта. В профессиональной разработке мы следуем нескольким правилам:

1. Правильный .gitignore

Не все файлы должны попадать в репозиторий. Мусор, временные файлы, настройки IDE и само виртуальное окружение должны быть проигнорированы.

Типичный .gitignore для Python:

__pycache__/
*.py[cod]
.venv/
.env
.DS_Store
.idea/
.vscode/

Обратите внимание на .env. В этом файле хранятся секреты (пароли, API-ключи). Никогда не отправляйте .env в Git. Для примера создают файл .env.example с пустыми значениями.

2. Атомарные коммиты

Плохой коммит:

"Исправил баг, добавил новую фичу и переписал половину проекта"

Хороший коммит:

"Fix: исправление ошибки валидации email"

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

Чистота кода: Линтеры и Форматтеры

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

Flake8: Полиция нравов

flake8 проверяет ваш код на соответствие стандарту PEP 8 и ищет логические ошибки (например, импортированный, но неиспользуемый модуль).

Установка:

poetry add --group dev flake8

Запуск:

poetry run flake8 src/

Black: Бескомпромиссный форматтер

Споры о том, ставить пробелы вокруг знака = или нет, отнимают время. Black решает эти споры раз и навсегда. Он просто берет ваш код и переписывает его в едином стиле.

Установка:

poetry add --group dev black

Запуск:

poetry run black .

isort: Порядок в импортах

Импорты должны быть отсортированы: сначала стандартные библиотеки, потом сторонние, потом ваши собственные. isort делает это автоматически.

Структура профессионального проекта

Забудьте о свалке файлов в корне папки. Стандартная структура выглядит так:

my-project/
├── .github/             # Настройки для GitHub (CI/CD)
├── src/                 # Исходный код проекта
│   └── my_app/          # Основной пакет
│       ├── __init__.py
│       └── main.py
├── tests/               # Тесты
│   ├── __init__.py
│   └── test_main.py
├── .env                 # Секреты (не в Git!)
├── .gitignore           # Что игнорировать
├── pyproject.toml       # Настройки проекта и зависимости
├── README.md            # Описание проекта
└── poetry.lock          # Фиксация версий

Папка src (source) используется для того, чтобы избежать путаницы при импортах и четко отделить код приложения от конфигурационных файлов.

Практическое задание: Настройка окружения

Прежде чем мы начнем писать код первого проекта (CLI-утилиты), подготовьте свою рабочую станцию:

1. Установите Git и настройте user.name и user.email.
2. Установите Python 3.10+.
3. Установите Poetry.
4. Создайте тестовый проект командой poetry new python-pro-setup.
5. Добавьте в него flake8 и black как dev-зависимости.
6. Создайте репозиторий на GitHub и отправьте туда первый коммит (не забудьте про .gitignore!).

Теперь вы готовы к настоящей разработке. В следующем модуле мы напишем нашу первую профессиональную CLI-утилиту, используя этот фундамент.

Проект 1: Разработка надежной CLI-утилиты и работа с файлами

В предыдущем модуле мы подготовили профессиональную среду разработки: настроили Git, Poetry и линтеры. Теперь пришло время написать код, который не стыдно показать коллегам.

Мы не будем писать очередной скрипт «Hello World». Мы создадим FileSorter — полноценную CLI-утилиту (Command Line Interface) для автоматической сортировки файлов в директории по их расширениям. Это классическая задача автоматизации, на примере которой мы разберем отличия любительского скрипта от надежного инженерного решения.

Отличие скрипта от инструмента

Любитель пишет скрипт, который работает «здесь и сейчас» на конкретной машине. Профессионал создает инструмент, который:

1. Предсказуем: Он не удалит ваши файлы случайно.
2. Универсален: Работает на Windows, Linux и macOS без переписывания путей.
3. Информативен: Сообщает, что делает, и объясняет ошибки, а не просто падает с Traceback.

Современная работа с файловой системой: pathlib

Долгое время стандартом в Python был модуль os.path. Вы наверняка видели код вроде os.path.join(dir, file). В современном Python (3.4+) мы используем модуль pathlib. Это объектно-ориентированный подход к путям.

Почему pathlib — это выбор профи:

• Кроссплатформенность: Windows использует обратные слеши \, а Unix — прямые /. pathlib обрабатывает это автоматически.
• Читаемость: Вместо вложенных функций вы используете методы объектов.

Сравните:

# Старый стиль (os.path)
import os
full_path = os.path.join(os.getcwd(), "data", "file.txt")

# Новый стиль (pathlib)
from pathlib import Path
full_path = Path.cwd() / "data" / "file.txt"

Обратите внимание на оператор /. В pathlib он перегружен и работает как интуитивное объединение частей пути.

Проектирование интерфейса: argparse

Профессиональная утилита не должна спрашивать данные через input(). Интерактивный ввод блокирует автоматизацию. Если вы хотите запустить свой сортировщик по расписанию ночью, некому будет вводить путь к папке.

Мы будем использовать аргументы командной строки. Стандартная библиотека Python предлагает мощный модуль argparse.

Наша утилита должна принимать:

1. Путь к папке, которую нужно разобрать (обязательный аргумент).
2. Флаг --dry-run (опционально) — режим «сухого прогона», когда программа только пишет, что сделала бы, но не трогает файлы реально. Это золотой стандарт безопасности.

Каркас приложения

Создайте файл src/filesorter/main.py (структура из прошлого урока) и начнем с парсера:

import argparse
from pathlib import Path
import sys

def parse_args():
    parser = argparse.ArgumentParser(
        description="Утилита для сортировки файлов по расширениям"
    )
    parser.add_argument(
        "source",
        type=Path,
        help="Путь к директории для сортировки"
    )
    parser.add_argument(
        "--output",
        "-o",
        type=Path,
        default=None,
        help="Путь, куда перемещать файлы (по умолчанию: внутрь source)"
    )
    parser.add_argument(
        "--dry-run",
        action="store_true",
        help="Запустить без реального перемещения файлов"
    )
    return parser.parse_args()

if __name__ == "__main__":
    args = parse_args()
    print(f"Обрабатываем: {args.source}")
    print(f"Режим Dry Run: {args.dry_run}")

Теперь, если вы запустите программу с флагом --help, Python автоматически сгенерирует документацию. Это и есть профессиональный подход: самодокументируемый код.

Логирование вместо print

Использование print() для отладки или сообщений о статусе — плохая практика в продакшене. print выводит все в стандартный поток вывода (stdout). Но что, если пользователь хочет перенаправить вывод ошибок в файл?

Используйте модуль logging. Он позволяет разделять сообщения по уровням важности:

• DEBUG: подробная информация для разработчика.
• INFO: стандартные сообщения о ходе работы.
• WARNING: что-то пошло не так, но работа продолжается.
• ERROR: ошибка, операция не выполнена.

Настроим простой логгер:

import logging

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(levelname)s - %(message)s",
    datefmt="%H:%M:%S"
)
logger = logging.getLogger(__name__)

Реализация логики сортировки

Теперь напишем «сердце» нашей программы. Нам нужно:

1. Проверить, существует ли папка.
2. Пройтись по всем файлам.
3. Определить расширение файла.
4. Создать целевую папку (например, Images для .jpg).
5. Переместить файл.

Безопасное перемещение

Главный страх при работе с файлами — перезапись. Если у вас есть photo.jpg в корне и photo.jpg в папке Images, простое перемещение может уничтожить один из них.

Реализуем функцию с защитой:

import shutil

def move_file(file: Path, target_dir: Path, dry_run: bool = False):
    target_path = target_dir / file.name

    # Если файл уже существует, добавляем счетчик
    if target_path.exists():
        stem = file.stem
        suffix = file.suffix
        counter = 1
        while target_path.exists():
            target_path = target_dir / f"{stem}_{counter}{suffix}"
            counter += 1

    if dry_run:
        logger.info(f"[DRY RUN] Перемещение {file.name} -> {target_path}")
    else:
        target_dir.mkdir(parents=True, exist_ok=True)
        shutil.move(str(file), str(target_path))
        logger.info(f"Перемещено: {file.name} -> {target_path}")

Обратите внимание на shutil. Модуль pathlib умеет перемещать файлы через Path.rename(), но shutil.move надежнее работает при перемещении между разными физическими дисками.

Собираем все вместе

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

EXTENSION_MAP = {
    ".jpg": "Images", ".png": "Images", ".jpeg": "Images",
    ".pdf": "Documents", ".docx": "Documents", ".txt": "Documents",
    ".mp4": "Video", ".mov": "Video",
    ".zip": "Archives", ".rar": "Archives"
}

def main():
    args = parse_args()
    source_dir: Path = args.source.resolve()

    if not source_dir.exists() or not source_dir.is_dir():
        logger.error(f"Директория не найдена: {source_dir}")
        sys.exit(1)

    logger.info(f"Начинаем сортировку в: {source_dir}")

    # iterdir() возвращает итератор по содержимому папки
    for item in source_dir.iterdir():
        if item.is_file():
            # Игнорируем скрытые файлы (начинаются с точки)
            if item.name.startswith("."):
                continue

            # Получаем папку назначения
            ext = item.suffix.lower()
            folder_name = EXTENSION_MAP.get(ext, "Others")

            # Определяем целевую директорию
            # Если указан output, используем его, иначе создаем папки внутри source
            base_output = args.output if args.output else source_dir
            target_dir = base_output / folder_name

            try:
                move_file(item, target_dir, dry_run=args.dry_run)
            except Exception as e:
                logger.error(f"Ошибка при перемещении {item.name}: {e}")

if __name__ == "__main__":
    main()

Почему этот код лучше, чем у 90% новичков

1. Обработка исключений: Мы обернули перемещение в try...except. Если один файл заблокирован системой, программа не упадет, а запишет ошибку в лог и продолжит работу со следующими файлами.
2. Dry Run: Вы можете запустить python main.py ./my_folder --dry-run и безопасно посмотреть, что произойдет.
3. Resolve: Метод .resolve() превращает относительный путь (например, .) в абсолютный. Это важно для логирования, чтобы вы точно знали, где происходили изменения.
4. Type Hinting: Мы явно указываем типы (file: Path), что помогает IDE подсказывать методы и предотвращает глупые ошибки.

Практическое задание

Ваша задача — доработать этот проект до состояния готового продукта.

1. Скопируйте код в свой проект, созданный через Poetry.
2. Добавьте в EXTENSION_MAP категории для музыки (.mp3, .wav) и кода (.py, .js, .html).
3. Реализуйте аргумент --recursive (или -r), который заставит утилиту проходить не только по указанной папке, но и по всем вложенным подпапкам. Подсказка: изучите метод Path.rglob().
4. Запустите линтеры (flake8, black), чтобы привести код к идеальному стилю.

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

Проект 2: Создание REST API сервиса на FastAPI

В предыдущем модуле мы научились создавать надежные инструменты для локального использования. Но современный мир разработки не ограничивается одним компьютером. Сегодня программы общаются друг с другом через сеть. Мобильные приложения, веб-сайты и микросервисы — все они обмениваются данными через API.

В этом модуле мы перейдем от скриптов к сервисам. Мы создадим TaskTracker API — веб-сервис для управления задачами. Это будет не просто учебный пример, а фундамент для полноценного бэкенда, построенный на самом современном фреймворке Python — FastAPI.

Что такое REST API и почему FastAPI?

Если CLI-утилита принимает аргументы командной строки, то веб-сервис принимает HTTP-запросы.

REST (Representational State Transfer) — это архитектурный стиль взаимодействия компонентов распределенного приложения в сети. Упрощенно, это набор правил того, как программист должен организовать URL-адреса и методы HTTP, чтобы всем было понятно, как пользоваться его сервисом.

Почему мы выбираем FastAPI, а не Django или Flask?

1. Скорость: Он действительно быстрый (на уровне Go и NodeJS) благодаря асинхронности.
2. Строгая типизация: FastAPI глубоко интегрирован с подсказками типов (Type Hints), что снижает количество багов.
3. Автоматическая документация: Вы пишете код, а FastAPI сам генерирует интерактивную документацию Swagger UI.

Настройка окружения

Продолжаем использовать Poetry. Создайте новый проект или используйте существующий репозиторий.

Нам понадобятся две главные библиотеки:

• fastapi: сам веб-фреймворк.
• uvicorn: высокопроизводительный ASGI-сервер, который будет запускать наше приложение.

poetry add fastapi "uvicorn[standard]"

Контракты данных: Pydantic

В CLI-утилите мы проверяли входные данные вручную. В веб-сервисе данные приходят от пользователей в формате JSON, и они могут прислать что угодно. Валидация — критически важный этап.

FastAPI использует библиотеку Pydantic. Мы описываем структуру данных как класс, а библиотека гарантирует, что данные соответствуют этому описанию.

Создайте файл src/main.py:

from typing import Optional
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI(title="TaskTracker API")

# Модель данных задачи
class Task(BaseModel):
    id: Optional[int] = None
    title: str
    description: Optional[str] = None
    is_completed: bool = False

Здесь мы объявили, что каждая задача обязана иметь заголовок (title), может иметь описание и статус выполнения. Если пользователь пришлет задачу без заголовка, FastAPI автоматически вернет ошибку, даже не запуская нашу логику.

Реализация эндпоинтов (Endpoints)

Эндпоинт — это точка входа в API (конкретный URL и метод). Поскольку мы пока не подключили базу данных, будем хранить задачи в оперативной памяти.

Добавьте этот код в src/main.py:

# Имитация базы данных в памяти
tasks_db = []

@app.get("/tasks", response_model=list[Task])
async def get_tasks():
    """
    Получить список всех задач.
    """
    return tasks_db

@app.post("/tasks", response_model=Task, status_code=201)
async def create_task(task: Task):
    """
    Создать новую задачу.
    """
    # Генерируем ID (в реальной БД это происходит автоматически)
    task.id = len(tasks_db) + 1
    tasks_db.append(task)
    return task

Разберем магию декораторов:

• @app.get и @app.post: указывают HTTP-метод.
• response_model: говорит FastAPI, в каком формате отдавать ответ. Это фильтрует лишние данные.
• async def: позволяет серверу обрабатывать тысячи запросов одновременно, не блокируясь на ожидании (например, пока база данных ответит).

Обработка ошибок и параметры пути

Что если клиент запросит задачу, которой нет? Мы должны вернуть правильный HTTP-код ошибки (404 Not Found).

@app.get("/tasks/{task_id}", response_model=Task)
async def get_task(task_id: int):
    """
    Получить конкретную задачу по ID.
    """
    for task in tasks_db:
        if task.id == task_id:
            return task

    # Если не нашли — выбрасываем исключение
    raise HTTPException(status_code=404, detail="Задача не найдена")

Обратите внимание на {task_id} в пути и аргумент task_id: int в функции. FastAPI автоматически извлечет число из URL и передаст его в функцию. Если пользователь напишет /tasks/hello, FastAPI вернет ошибку валидации, так как "hello" — это не int.

Запуск сервера

Веб-сервис — это процесс, который должен работать постоянно. Для запуска используем Uvicorn.

В терминале (находясь в корне проекта):

poetry run uvicorn src.main:app --reload

• src.main:app: путь к объекту приложения (файл src/main.py, переменная app).
• --reload: режим разработчика. Сервер будет перезагружаться автоматически при изменении кода.

Если вы увидите надпись Application startup complete, значит, ваш сервер запущен на http://127.0.0.1:8000.

Интерактивная документация

Теперь самое интересное. Откройте в браузере адрес:

http://127.0.0.1:8000/docs

Вы увидите Swagger UI. Это автоматически сгенерированная веб-страница, где перечислены все ваши эндпоинты. Вы можете нажать кнопку "Try it out", заполнить JSON и отправить реальный запрос к вашему API прямо из браузера.

Это профессиональный стандарт. Фронтенд-разработчики и тестировщики будут любить вас за такую документацию.

Структура проекта: Router

Хранить весь код в main.py — плохая практика, допустимая только для прототипов. В реальном проекте мы разделяем логику.

Профессиональная структура FastAPI проекта:

src/
├── main.py            # Точка входа, создание app
├── models.py          # Pydantic модели
└── routers/           # Папка с маршрутами
    ├── __init__.py
    └── tasks.py       # Логика работы с задачами

В src/routers/tasks.py мы используем APIRouter:

from fastapi import APIRouter, HTTPException
from ..models import Task # Импорт модели из соседнего файла

router = APIRouter(prefix="/tasks", tags=["Tasks"])

@router.get("/")
async def get_tasks():
    # Логика...
    pass

А в main.py просто подключаем его:

from fastapi import FastAPI
from .routers import tasks

app = FastAPI()
app.include_router(tasks.router)

Практическое задание

Ваша задача — превратить этот прототип в полноценный API для управления списком дел.

1. Реализуйте метод DELETE для удаления задачи по ID.
2. Реализуйте метод PUT для обновления задачи (например, чтобы отметить её как выполненную).
3. Добавьте валидацию: длина заголовка задачи не должна превышать 50 символов (изучите pydantic.Field).
4. Разнесите код по файлам: модели отдельно, роутеры отдельно, main.py отдельно.

В следующем модуле мы подключим к нашему API настоящую базу данных, чтобы задачи не исчезали после перезагрузки сервера.

Культура разработки: тестирование с Pytest и обработка ошибок

Вы написали код, запустили его, и он сработал. Отлично! Но можете ли вы гарантировать, что он будет работать завтра? А если вы измените одну строчку в другой части проекта, не сломается ли текущий функционал?

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

Страх изменений и регрессия

Представьте ситуацию: вы добавляете новую функцию в наш FileSorter (из Проекта 1) — например, распаковку архивов. Вы дописали код, проверили — архивы распаковываются. Вы довольны.

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

Ручное тестирование («прокликивание» или запуск скрипта руками) с ростом проекта становится невозможным. На помощь приходят автоматические тесты.

Почему Pytest?

В Python есть встроенный модуль unittest, вдохновленный Java JUnit. Он надежный, но громоздкий. Стандартом современной разработки является Pytest.

Его преимущества:

1. Лаконичность: Не нужно создавать классы-наследники. Обычные функции — это уже тесты.
2. Магия assert: Не нужно помнить методы вроде self.assertEqual или self.assertTrue. Вы просто пишете assert x == y.
3. Фикстуры (Fixtures): Мощный механизм подготовки данных.

Установка

Добавим библиотеку в наш проект через Poetry (как dev-зависимость, так как в продакшене тесты не нужны):

poetry add --group dev pytest

Пишем первый тест

Вспомним наш проект FileSorter. У нас была логика определения папки по расширению файла. Давайте вынесем её в отдельную функцию (если вы этого еще не сделали) и протестируем.

Файл src/filesorter/logic.py:

EXTENSION_MAP = {
    ".jpg": "Images",
    ".txt": "Documents",
    ".zip": "Archives"
}

def get_target_folder(extension: str) -> str:
    """Возвращает имя папки для заданного расширения."""
    return EXTENSION_MAP.get(extension.lower(), "Others")

Теперь создадим файл tests/test_logic.py. Pytest автоматически ищет файлы, начинающиеся на test_.

from src.filesorter.logic import get_target_folder

def test_get_target_folder_jpg():
    result = get_target_folder(".jpg")
    assert result == "Images"

def test_get_target_folder_unknown():
    result = get_target_folder(".xyz")
    assert result == "Others"

def test_get_target_folder_case_insensitive():
    result = get_target_folder(".JPG")
    assert result == "Images"

Запустите тесты командой:

poetry run pytest

Вы увидите зеленый прогресс-бар. Если вы намеренно сломаете код (например, измените "Images" на "Pictures"), Pytest покажет детальный отчет: что ожидалось и что было получено.

Параметризация: DRY в тестах

Писать отдельную функцию для каждого расширения (test_jpg, test_txt, test_zip) — это нарушение принципа DRY (Don't Repeat Yourself). Pytest позволяет запускать один и тот же тест с разными данными.

Используем декоратор @pytest.mark.parametrize:

import pytest
from src.filesorter.logic import get_target_folder

@pytest.mark.parametrize("extension, expected_folder", [
    (".jpg", "Images"),
    (".txt", "Documents"),
    (".JPG", "Images"),
    (".unknown", "Others"),
    ("", "Others")
])
def test_get_target_folder(extension, expected_folder):
    assert get_target_folder(extension) == expected_folder

Теперь Pytest запустит эту функцию 5 раз с разными аргументами. Это позволяет покрыть десятки граничных случаев в несколько строк кода.

Фикстуры: работа с файловой системой

Самое сложное в тестировании — это внешние зависимости (файлы, базы данных, сеть). Если ваш тест реально создает файлы на диске, вам нужно потом их удалять. Если тест упадет посередине, мусор останется.

В Pytest есть встроенная фикстура tmp_path. Она создает временную директорию, которая гарантированно удаляется после теста.

Протестируем функцию сортировки (предположим, у нас есть функция sort_directory):

# tests/test_sorter.py
from src.filesorter.main import sort_directory

def test_sort_directory_moves_files(tmp_path):
    # 1. Подготовка (Arrange)
    # tmp_path - это объект pathlib.Path, указывающий на временную папку
    source_dir = tmp_path / "source"
    source_dir.mkdir()

    # Создаем тестовые файлы
    (source_dir / "photo.jpg").touch()
    (source_dir / "notes.txt").touch()

    # 2. Действие (Act)
    sort_directory(source_dir)

    # 3. Проверка (Assert)
    # Проверяем, что файлы исчезли из корня
    assert not (source_dir / "photo.jpg").exists()

    # Проверяем, что они появились в нужных папках
    assert (source_dir / "Images" / "photo.jpg").exists()
    assert (source_dir / "Documents" / "notes.txt").exists()

Обратите внимание: мы не писали логику создания и удаления папки. Мы просто добавили аргумент tmp_path, и Pytest сделал всё за нас.

Культура обработки ошибок

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

EAFP против LBYL

В Python принят принцип EAFP (Easier to Ask for Forgiveness than Permission — Проще попросить прощения, чем разрешения).

LBYL (Look Before You Leap — классический подход C/Java):

import os
if os.path.exists(file_path):
    os.remove(file_path)
else:
    print("Файла нет")

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

EAFP (Pythonic way):

try:
    os.remove(file_path)
except FileNotFoundError:
    print("Файла уже нет")

Этот код надежнее и часто быстрее.

Создание собственных исключений

Никогда не используйте raise Exception("Ошибка"). Это слишком общее исключение, которое трудно перехватить точечно. Создавайте свои классы ошибок для проектов.

class FileSorterError(Exception):
    """Базовый класс для ошибок сортировщика"""
    pass

class DestinationNotWritableError(FileSorterError):
    """Вызывается, если нет прав на запись в целевую папку"""
    pass

Теперь в коде вы можете выбрасывать конкретную ошибку:

if not target_dir.stat().st_mode & 0o200:
    raise DestinationNotWritableError(f"Нет прав на запись: {target_dir}")

А на уровне выше — ловить именно её:

try:
    move_file(file, target)
except DestinationNotWritableError:
    logger.error("Проверьте права доступа!")
except FileSorterError:
    logger.error("Общая ошибка сортировки")

Тестирование исключений

Как проверить, что ваша программа правильно ломается? Если функция должна выбросить ошибку при неверных данных, а она этого не делает — это баг.

Используйте контекстный менеджер pytest.raises:

import pytest
from src.filesorter.main import move_file

def test_move_file_raises_error_on_readonly(tmp_path):
    # Создаем файл и папку только для чтения
    f = tmp_path / "test.txt"
    f.touch()

    readonly_dir = tmp_path / "readonly"
    readonly_dir.mkdir()
    # Убираем права на запись (chmod 444)
    readonly_dir.chmod(0o444)

    # Ожидаем, что вызов move_file выбросит PermissionError
    with pytest.raises(PermissionError):
        move_file(f, readonly_dir)

Если move_file выполнится без ошибок (например, вы забыли проверку прав), тест упадет.

Тестирование API (FastAPI)

Для нашего второго проекта (TaskTracker) Pytest тоже незаменим. FastAPI предоставляет TestClient, который позволяет делать запросы к вашему API без запуска реального сервера.

# tests/test_api.py
from fastapi.testclient import TestClient
from src.main import app

client = TestClient(app)

def test_create_task():
    response = client.post("/tasks", json={"title": "Купить молоко"})
    assert response.status_code == 201
    data = response.json()
    assert data["title"] == "Купить молоко"
    assert "id" in data

def test_create_task_invalid():
    # Пытаемся создать задачу без заголовка
    response = client.post("/tasks", json={})
    assert response.status_code == 422 # Unprocessable Entity

Практическое задание

Теперь ваша очередь превратить ваш код в профессиональный продукт.

1. Установите pytest в ваш проект.
2. Для FileSorter: напишите параметризованный тест для функции определения расширений. Напишите тест с tmp_path, проверяющий, что файлы реально перемещаются.
3. Для TaskTracker: напишите тесты для эндпоинтов создания и получения задач. Проверьте, что API возвращает 404, если запросить несуществующий ID задачи.
4. Запустите pytest и добейтесь 100% прохождения тестов.

В следующем модуле мы упакуем наши протестированные приложения в Docker-контейнеры, чтобы запускать их на любом сервере одной командой.

Финализация: контейнеризация в Docker и подготовка к релизу

Поздравляю! Вы прошли долгий путь. Мы начали с настройки окружения, написали CLI-утилиту для сортировки файлов, создали REST API сервис на FastAPI и покрыли всё это тестами. Ваш код чист, структурирован и работает. На вашем компьютере.

Но в профессиональной разработке фраза «работает на моей машине» (It works on my machine) — это не оправдание. Серверы в облаке, компьютеры коллег и ноутбук заказчика могут иметь другую операционную систему, другую версию Python или отсутствующие системные библиотеки.

В этой финальной статье курса мы упакуем наш проект в Docker. Это превратит ваше приложение в универсальный «кирпичик», который гарантированно запустится где угодно.

Проблема зависимостей и её решение

Представьте, что вы хотите отправить другу домашний пирог. Вы можете отправить ему рецепт (исходный код). Но у друга может не быть нужной муки, духовка греет слабее, а вместо сахара он по ошибке возьмет соль. Результат будет непредсказуемым.

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

Контейнеры против Виртуальных машин

Раньше для изоляции приложений использовали виртуальные машины (VM). Это было надежно, но тяжело: каждая VM запускала полноценную операционную систему, съедая гигабайты памяти.

Docker использует контейнеры. Контейнер — это легкая изолированная среда. Она использует ядро основной операционной системы (Linux), но имеет свою файловую систему, свои библиотеки и настройки.

Пишем Dockerfile

Чтобы Docker понял, как упаковать ваше приложение, ему нужна инструкция — файл с именем Dockerfile (без расширения). Мы будем упаковывать наш проект TaskTracker (API на FastAPI).

Создайте файл Dockerfile в корне вашего проекта:

# 1. Базовый образ
# Мы берем официальный легкий образ Python 3.10
FROM python:3.10-slim

# 2. Переменные окружения для Python
# PYTHONDONTWRITEBYTECODE=1: не создавать .pyc файлы
# PYTHONUNBUFFERED=1: вывод логов сразу в консоль, без буферизации
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1

# 3. Установка рабочей директории внутри контейнера
WORKDIR /app

# 4. Установка системных зависимостей (если нужны)
# Для нашего простого проекта они не нужны, но часто здесь ставят gcc или libpq
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

# 5. Установка Poetry
# Мы скачиваем и устанавливаем Poetry глобально внутри контейнера
RUN curl -sSL https://install.python-poetry.org | python3 -
ENV PATH="/root/.local/bin:$PATH"

# 6. Настройка Poetry
# В контейнере нам не нужен venv, так как контейнер сам по себе изолирован
RUN poetry config virtualenvs.create false

# 7. Копирование файлов зависимостей
COPY pyproject.toml poetry.lock ./

# 8. Установка зависимостей проекта
# --no-root означает, что мы пока не ставим сам наш пакет, только библиотеки
RUN poetry install --no-root --no-interaction --no-ansi

# 9. Копирование исходного кода
COPY src/ src/

# 10. Команда запуска
# Запускаем uvicorn, слушая все интерфейсы (0.0.0.0) на порту 8000
CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8000"]

Разбор ключевых шагов

1. FROM: Любой образ строится на базе другого. python:3.10-slim — это минималистичная версия Linux (Debian) с уже установленным Python.
2. WORKDIR: Это как команда cd. Все дальнейшие команды будут выполняться в папке /app внутри контейнера.
3. COPY: Мы копируем файлы с вашего компьютера (хост) внутрь контейнера. Сначала мы копируем только файлы зависимостей (pyproject.toml, poetry.lock). Почему? Docker кэширует слои. Если вы измените код программы, но не зависимости, Docker пропустит долгий этап установки библиотек.
4. CMD: Это команда, которая выполнится, когда контейнер запустится.

Игнорирование лишнего: .dockerignore

Контейнер должен быть максимально легким. Нет смысла тащить туда папку .git (которая может весить сотни мегабайт), локальное виртуальное окружение или кэш тестов.

Создайте файл .dockerignore (синтаксис как у .gitignore):

.git
.venv
__pycache__
.pytest_cache
.env
tests/
README.md

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

Сборка и запуск

Теперь превратим наш код в Docker-образ. Откройте терминал в папке проекта.

Шаг 1: Сборка (Build)

docker build -t task-tracker:v1 .

• -t task-tracker:v1: Мы даем образу имя (tag) task-tracker и версию v1.
• .: Точка в конце означает «искать Dockerfile в текущей директории».

Docker скачает Python, установит Poetry, скачает библиотеки и создаст «слепок» вашего приложения.

Шаг 2: Запуск (Run)

docker run -d -p 8000:8000 --name my-api task-tracker:v1

• -d (detach): Запустить в фоновом режиме.
• -p 8000:8000: Пробросить порт. Левая часть — порт на вашем компьютере, правая — внутри контейнера. Если вы напишете -p 9090:8000, то приложение будет доступно по адресу localhost:9090.
• --name: Имя для запущенного контейнера.

Проверьте работу, открыв http://localhost:8000/docs.

Оркестрация: Docker Compose

Запускать команды docker run с кучей флагов неудобно. К тому же, реальные приложения состоят из нескольких сервисов (API + База данных + Кэш).

Docker Compose — это инструмент для описания и запуска мульти-контейнерных приложений. Конфигурация хранится в файле docker-compose.yml.

Создайте docker-compose.yml в корне проекта:

version: '3.8'

services:
  api:
    build: .  # Строим образ из текущей папки
    container_name: task-tracker-app
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
    volumes:
      - ./src:/app/src  # Прокидываем код внутрь для горячей перезагрузки (опционально)
    restart: always

Теперь для запуска всего проекта достаточно одной команды:

docker compose up --build

Эта команда соберет образ и запустит контейнер. Если вы добавите в этот файл базу данных (например, PostgreSQL), Docker Compose запустит и её, и даже настроит внутреннюю сеть, чтобы API мог «видеть» базу.

Лицо проекта: README.md

Вы упаковали проект, но как другие узнают, как им пользоваться? Профессиональный разработчик всегда сопровождает код документацией.

Файл README.md в корне репозитория — это первое, что видит работодатель или коллега на GitHub. Хороший README должен отвечать на вопросы: «Что это?», «Зачем это?» и «Как это запустить?».

Структура идеального README

1. Заголовок и бейджы: Название проекта и статус тестов (CI/CD pass/fail).
2. Описание: Кратко (2-3 предложения) о том, какую проблему решает сервис.
3. Технологический стек: Python 3.10, FastAPI, Docker, Poetry, Pytest.
4. Установка и запуск:
   • Локально через Poetry.
   • В контейнере через Docker Compose.
5. Примеры использования: Примеры запросов к API (можно скриншоты из Swagger UI).

Пример фрагмента README:

# TaskTracker API 🚀

REST API сервис для управления задачами. Позволяет создавать, просматривать и редактировать список дел.

## Быстрый старт с Docker

1. Клонируйте репозиторий:
   `git clone https://github.com/user/task-tracker.git`
2. Запустите проект:
   `docker compose up -d`
3. Откройте документацию:
   `http://localhost:8000/docs`

Заключение курса

Поздравляю! Вы прошли путь от простых скриптов до создания готового к релизу продукта.

Давайте оглянемся назад и посмотрим, чему вы научились:

1. Организация: Вы больше не сваливаете файлы в кучу, а используете src, tests и виртуальные окружения.
2. Инструментарий: Git, Poetry, Flake8, Black — ваши верные спутники.
3. Архитектура: Вы понимаете разницу между CLI-утилитой и REST API, умеете использовать Pydantic для валидации данных.
4. Качество: Вы пишете тесты на Pytest, чтобы спать спокойно.
5. Доставка: Вы упаковываете приложение в Docker, делая его бессмертным и переносимым.

Что дальше?

Этот курс дал вам фундамент. Дальнейшее развитие зависит от ваших интересов:

• Backend: Подключите настоящую базу данных (PostgreSQL) через SQLAlchemy и изучите миграции (Alembic).
• DevOps: Настройте CI/CD (GitHub Actions), чтобы тесты запускались автоматически при каждом коммите, а Docker-образ сам улетал на сервер.
• Frontend: Попробуйте написать простой интерфейс на React или Vue, который будет общаться с вашим API.

Вы больше не новичок. Вы — разработчик, который умеет создавать продукты. Удачи в новых проектах!