# Правильное отношение к тестам

Вокруг тестов в Python, да и не только, много лишней драматургии. Обычно есть два крайних мнения. Первое звучит как: “без стопроцентного покрытия вы не разработчик”. Второе как: “мы стартап, нам не до тестов”. Оба подхода, конечно, имеют право на существование, но ведут, как правило не туда. В первом случае, погоня за стопроцентным покрытим с высокой вероятностью может привести к мусорным тестам, так как метрика покрытия (как бы она не вычисляллась) не идеальна. Например, никто не запрещяет через рефликисю получить все возможные объекты в коде, инстанцировать их, и вообще ничего не проверять, получив стопроцентное покрытие. Во втором случае, со временем процесс разработки будет становится все сложнее, а DE (developer experience) ухудшаться из-за рочных проверок “на каждый чих”.

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

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

# Зачем автотесты на практике

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

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

Документация поведения в тестах особенно заметна в долгоживущих проектах. Через полгода после запуска фичи никто уже не помнит, почему именно в случае отмененного заказа и частичного возврата комиссия пересчитывается определенным образом. Тест с понятным названием и явным assertion отвечает на этот вопрос быстрее, чем любой коммит в истории.

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

# Что именно мы тестируем: уровни и назначение

Слово “тест” без указания уровня мало что означает. Один тест может проверять чистую функцию за миллисекунды, другой гонять браузерный сценарий несколько минут. И это нормально, если мы понимаем, зачем каждый из них нужен.

Юнит-тест проверяет маленький фрагмент поведения в изоляции. Обычно это функция или небольшой класс без обращения к сети, диску и базе данных. Главная ценность юнита в скорости и точности сигнала. Если он упал, область поиска проблемы очень узкая.

Интеграционный тест проверяет стык нескольких модулей или слоев. Обычно здесь уже участвуют реальные адаптеры, БД, очередь, внешний HTTP-клиент через тестовый стенд. Такой тест медленнее, но он ловит ошибки контрактов и конфигураций, которые юнитами не поймать.

E2E тест проверяет сквозной пользовательский путь. Это не тест метода. Это тест бизнес-сценария целиком. Например, “регистрация -> подтверждение почты -> создание заказа -> оплата”. Такие тесты самые дорогие в поддержке, но на даже небольшое их количество, покрывающее критические участки системы, дают большую увернность в надёжности.

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

# Пирамида тестирования как модель затрат

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

Если команда пишет почти одни E2E, она быстро сталкивается с медленным feedback loop. Каждый запуск долгий, окружение хрупкое, тесты нестабильны. Разработчики начинают реже запускать их локально, а CI превращается в место сюрпризов.

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

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

# Архитектура и тестируемость связаны напрямую

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

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

class PaymentService:
    def pay(self, user_id: int, amount: int) -> None:
        db = PostgresClient("postgres://prod")
        gateway = StripeClient("secret")
        metrics = MetricsClient("statsd://metrics")

        user = db.fetch_user(user_id)
        if not user.active:
            raise ValueError("inactive user")

        gateway.charge(user.card_token, amount)
        db.save_payment(user_id, amount)
        metrics.increment("payments.success")

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

Лучший пример отделяет бизнес-решение от инфраструктуры и внедряет зависимости извне.

class PaymentService:
    def __init__(self, users_repo, payments_repo, gateway, metrics):
        self.users_repo = users_repo
        self.payments_repo = payments_repo
        self.gateway = gateway
        self.metrics = metrics

    def pay(self, user_id: int, amount: int) -> None:
        user = self.users_repo.get(user_id)
        if not user.active:
            raise ValueError("inactive user")

        self.gateway.charge(user.card_token, amount)
        self.payments_repo.save(user_id, amount)
        self.metrics.increment("payments.success")

Теперь юнит-тест может проверять решения домена через фейковые зависимости, а интеграционные тесты отдельно проверят репозиторий, шлюз и метрики. Такой код проще развивать и проще покрывать.

# Red -> Green -> Refactor

Red означает, что мы сначала формулируем ожидаемое поведение через падающий тест. Green означает, что мы пишем минимальный код, достаточный для прохождения. Refactor означает, что мы улучшаем структуру кода, не меняя поведение.

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

На фазе Red можно начать так:

def test_allocate_even_months_with_remainder():
    # 1000 cents over 3 months -> 333, 333, 334
    assert allocate_cents(1000, 3) == [333, 333, 334]

На фазе Green пишем минимальную реализацию:

def allocate_cents(total: int, months: int) -> list[int]:
    base = total // months
    remainder = total % months
    result = [base] * months
    result[-1] += remainder
    return result

На фазе Refactor добавляем защиту от некорректного ввода, делаем имя переменных яснее, добавляем тесты на крайние случаи.

import pytest


def allocate_cents(total: int, months: int) -> list[int]:
    if months <= 0:
        raise ValueError("months must be positive")
    if total < 0:
        raise ValueError("total must be non-negative")

    base = total // months
    remainder = total % months
    schedule = [base] * months
    schedule[-1] += remainder
    return schedule


def test_allocate_one_month():
    assert allocate_cents(500, 1) == [500]


def test_allocate_zero_total():
    assert allocate_cents(0, 4) == [0, 0, 0, 0]


def test_allocate_invalid_months():
    with pytest.raises(ValueError):
        allocate_cents(100, 0)

Именно так TDD удерживает фокус на контракте и предотвращает переусложнение раньше времени.

# Скорость обратной связи

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

Маленькие изолированные тесты дают сигнал за секунды. Тяжелые интеграционные проверки дают сигнал за минуты. E2E иногда дают сигнал за десятки минут. Все уровни нужны, но последовательность их использования критична.

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

Когда эта дисциплина есть, количество “красных” сюрпризов в CI существенно падает. А значит, падает и время ожидания, и количество контекстных переключений.

# London school и classicist school в реальном проекте

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

London school чаще использует моки и проверяет взаимодействия. Если ваш код это оркестратор нескольких внешних вызовов, этот подход дает очень точный контроль над тем, кто и как был вызван.

Classicist school чаще проверяет состояние и поведение через реальные объекты без агрессивного мокинга. Если у вас много чистой доменной логики, такой стиль обычно делает тесты более устойчивыми к рефакторингу.

Давайте посмотрим на один и тот же кейс двумя стилями.

В mock-heavy подходе:

from unittest.mock import Mock


def register_user(repo, email_sender, email: str) -> None:
    user_id = repo.create(email=email)
    email_sender.send_welcome(user_id=user_id, email=email)


def test_register_user_calls_dependencies():
    repo = Mock()
    repo.create.return_value = 101
    email_sender = Mock()

    register_user(repo, email_sender, "alice@example.com")

    repo.create.assert_called_once_with(email="alice@example.com")
    email_sender.send_welcome.assert_called_once_with(
        user_id=101,
        email="alice@example.com",
    )

В state-oriented подходе:

class InMemoryRepo:
    def __init__(self):
        self.items = []

    def create(self, email: str) -> int:
        user_id = len(self.items) + 1
        self.items.append({"id": user_id, "email": email})
        return user_id


class InMemoryEmailSender:
    def __init__(self):
        self.sent = []

    def send_welcome(self, user_id: int, email: str) -> None:
        self.sent.append({"user_id": user_id, "email": email})


def test_register_user_changes_state():
    repo = InMemoryRepo()
    sender = InMemoryEmailSender()

    register_user(repo, sender, "alice@example.com")

    assert repo.items == [{"id": 1, "email": "alice@example.com"}]
    assert sender.sent == [{"user_id": 1, "email": "alice@example.com"}]

Оба теста полезны. Первый лучше контролирует контракт вызовов. Второй лучше переживает рефакторинг внутренней реализации.

# Моки и стабы: когда помогают, а когда ломают картину

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

Разберем пример с внешним API курса валют. В production-коде мы делаем HTTP-запрос, но в юнит-тесте хотим проверить реакцию на ответы API без реальной сети.

import requests


def fetch_rate(base: str, quote: str) -> float:
    resp = requests.get(
        "https://rates.example.com/latest",
        params={"base": base, "quote": quote},
        timeout=3,
    )
    data = resp.json()
    return float(data["rate"])

Юнит-тест с mock:

from unittest.mock import Mock, patch


def test_fetch_rate_parses_response():
    fake_response = Mock()
    fake_response.json.return_value = {"rate": "95.4"}

    with patch("requests.get", return_value=fake_response) as get_mock:
        rate = fetch_rate("USD", "RUB")

    assert rate == 95.4
    get_mock.assert_called_once()

Тут мок оправдан. Мы не тестируем requests, мы тестируем, как наша функция обрабатывает ответ.

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

# unittest, pytest, nose2: что выбирать в 2026 году

Встроенный unittest остается рабочим вариантом, особенно там, где важна минимизация зависимостей и строгая стандартизация.

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

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

# AAA и структура теста, которую удобно читать через год

Одна из самых простых техник, которая сильно повышает поддерживаемость тестов, это явная структура Arrange, Act, Assert. Даже без комментариев она удерживает тест коротким и линейным.

def calculate_total(price: int, quantity: int, discount: float) -> int:
    subtotal = price * quantity
    return int(subtotal * (1 - discount))


def test_calculate_total_with_discount():
    price = 500
    quantity = 2
    discount = 0.1

    result = calculate_total(price, quantity, discount)

    assert result == 900

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

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

# Фикстуры, setup/teardown и контроль над состоянием

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

Сравним плохой и хороший подход.

Плохо, когда фикстура делает слишком много:

import pytest


@pytest.fixture
def app_everything():
    # создает БД, поднимает сервис, загружает данные,
    # настраивает очередь, запускает фоновые воркеры
    return {"warning": "fixture is too broad"}

Хорошо, когда фикстуры узкие и ясные по назначению:

import pytest


@pytest.fixture
def user_email():
    return "alice@example.com"


@pytest.fixture
def in_memory_repo():
    class Repo:
        def __init__(self):
            self.items = []

        def save(self, email: str):
            self.items.append(email)

    return Repo()


def test_repo_save(in_memory_repo, user_email):
    in_memory_repo.save(user_email)
    assert in_memory_repo.items == ["alice@example.com"]

Чем яснее фикстуры, тем проще понимать, откуда в тесте взялись данные и почему они именно такие.

# Рекомендации по юнит-тестам через конкретные примеры

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

import re


def normalize_phone(value: str) -> str:
    digits = re.sub(r"\D", "", value)
    if len(digits) == 11 and digits.startswith("8"):
        digits = "7" + digits[1:]
    if len(digits) != 11:
        raise ValueError("invalid phone")
    return "+" + digits

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

import pytest


def test_normalize_phone_ru_local_prefix():
    assert normalize_phone("8 (999) 000-00-00") == "+79990000000"


def test_normalize_phone_already_international():
    assert normalize_phone("+7 999 000 00 00") == "+79990000000"


def test_normalize_phone_invalid_length():
    with pytest.raises(ValueError):
        normalize_phone("123")

Теперь при падении точно видно, какой именно сценарий сломан.

# Как организовать test suite проекта, чтобы им реально пользовались

Рабочий test suite начинается с понятной структуры каталогов и режимов запуска. Когда уровни тестов разделены, разработчику проще выбирать нужный пакет под конкретную задачу.

project/
  app/
    domain/
    application/
    infrastructure/
  tests/
    unit/
    integration/
    e2e/
  pyproject.toml

В pyproject.toml удобно зафиксировать маркеры и общие настройки pytest, чтобы команда запускала тесты единообразно.

[tool.pytest.ini_options]
addopts = "-ra -q"
testpaths = ["tests"]
markers = [
  "integration: tests with real infrastructure",
  "e2e: end-to-end scenarios",
]

Тогда локально можно запускать быстрые тесты отдельно от тяжелых.

pytest tests/unit
pytest -m integration
pytest -m e2e

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

# Интеграционные тесты на примере API и базы данных

Разберем практический пример с FastAPI и SQLite, где мы хотим проверить полный путь “HTTP-запрос -> запись в БД -> HTTP-ответ”.

from fastapi import FastAPI
from pydantic import BaseModel
import sqlite3


app = FastAPI()


class ItemIn(BaseModel):
    name: str


def get_conn():
    conn = sqlite3.connect("test.db")
    conn.execute("CREATE TABLE IF NOT EXISTS items(name TEXT)")
    return conn


@app.post("/items")
def create_item(payload: ItemIn):
    conn = get_conn()
    conn.execute("INSERT INTO items(name) VALUES (?)", (payload.name,))
    conn.commit()
    conn.close()
    return {"ok": True}

Интеграционный тест:

from fastapi.testclient import TestClient
import sqlite3


client = TestClient(app)


def test_create_item_persists_to_db(tmp_path, monkeypatch):
    db_path = tmp_path / "items.db"

    def get_test_conn():
        conn = sqlite3.connect(db_path)
        conn.execute("CREATE TABLE IF NOT EXISTS items(name TEXT)")
        return conn

    monkeypatch.setattr("main.get_conn", get_test_conn)

    response = client.post("/items", json={"name": "book"})
    assert response.status_code == 200
    assert response.json() == {"ok": True}

    conn = sqlite3.connect(db_path)
    rows = conn.execute("SELECT name FROM items").fetchall()
    conn.close()

    assert rows == [("book",)]

Этот тест уже не юнит. Он проверяет интеграцию HTTP-слоя, валидации и хранилища.

# E2E на примере Playwright

E2E полезно показывать на коротких, но бизнес-значимых сценариях. Например, логин пользователя.

from playwright.sync_api import sync_playwright


def test_login_e2e():
    with sync_playwright() as p:
        browser = p.chromium.launch()
        page = browser.new_page()

        page.goto("http://localhost:8000/login")
        page.fill("input[name='email']", "alice@example.com")
        page.fill("input[name='password']", "qwerty")
        page.click("button[type='submit']")

        page.wait_for_url("**/dashboard")
        assert page.locator("text=Welcome").is_visible()

        browser.close()

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

# База данных в тестах: миграции, фикстуры, rollback

С БД в тестах есть одно правило, которое нельзя нарушать. Каждый тест должен быть независим по состоянию.

Один из рабочих шаблонов для SQLAlchemy это транзакция на тест, которая откатывается после выполнения.

import pytest
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker


@pytest.fixture
def db_session():
    engine = create_engine("sqlite:///:memory:")
    Session = sessionmaker(bind=engine)
    session = Session()

    tx = session.begin()
    try:
        yield session
    finally:
        tx.rollback()
        session.close()

Такой подход дает чистое состояние на каждый тест и сохраняет высокую скорость прогонов.

Если в проекте используются миграции, их нужно включать в процесс подготовки тестовой БД, иначе тесты начнут жить в схеме, которая отличается от production.

# Приватные методы: когда тестировать напрямую, а когда нет

По умолчанию лучше тестировать поведение через публичный API. Это делает тесты устойчивее к рефакторингу.

Рассмотрим пример.

class TaxCalculator:
    def calculate(self, amount: int) -> int:
        return amount + self._tax(amount)

    def _tax(self, amount: int) -> int:
        return int(amount * 0.2)

Стабильный тест проверяет calculate, а не _tax.

def test_calculate_adds_tax():
    calc = TaxCalculator()
    assert calc.calculate(100) == 120

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

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

# Время в тестах и детерминизм

Время это одна из самых частых причин flaky-тестов. Если тест зависит от datetime.now(), он может вести себя по-разному в разные дни, часы и timezone.

freezegun решает это элегантно.

from datetime import datetime
from freezegun import freeze_time


def current_period_start() -> str:
    now = datetime.now()
    return now.replace(day=1, hour=0, minute=0, second=0, microsecond=0).isoformat()


@freeze_time("2026-02-12 10:00:00")
def test_current_period_start():
    assert current_period_start() == "2026-02-01T00:00:00"

Такой тест детерминирован и не зависит от машины запуска.

# Плотный блок про pytest: от базы до полезных встроенных фикстур

Начнем с базового примера с assert.

def multiply(a: int, b: int) -> int:
    return a * b


def test_multiply_basic():
    assert multiply(3, 4) == 12

Параметризация позволяет расширять покрытие без копипаста.

import pytest


@pytest.mark.parametrize(
    "a,b,expected",
    [
        (2, 3, 6),
        (0, 10, 0),
        (-2, 3, -6),
    ],
)
def test_multiply_parametrized(a, b, expected):
    assert multiply(a, b) == expected

Проверка исключений:

import pytest


def divide(a: int, b: int) -> float:
    if b == 0:
        raise ZeroDivisionError("division by zero")
    return a / b


def test_divide_zero_raises():
    with pytest.raises(ZeroDivisionError, match="division by zero"):
        divide(10, 0)

tmp_path полезен для файловых сценариев.

def save_report(path, text: str) -> None:
    path.write_text(text, encoding="utf-8")


def test_save_report(tmp_path):
    report = tmp_path / "report.txt"

    save_report(report, "ok")

    assert report.read_text(encoding="utf-8") == "ok"

monkeypatch помогает временно менять окружение и атрибуты.

import os


def service_url() -> str:
    return os.getenv("SERVICE_URL", "https://prod.example.com")


def test_service_url_from_env(monkeypatch):
    monkeypatch.setenv("SERVICE_URL", "https://test.example.com")
    assert service_url() == "https://test.example.com"

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

# Интеграция типизации и тестов: две сетки безопасности лучше одной

Тесты и статический анализ закрывают разные области риска. Type checker ловит типовые несоответствия до запуска. Тесты ловят поведенческие и интеграционные ошибки при выполнении.

Например, type checker может заранее подсветить ситуацию, когда функция обещает вернуть int, а фактически возвращает float или None. Тесты в этот момент еще даже не запускались.

В CI зрелого проекта обычно запускают и type checker, и pytest. Это дает плотный и быстрый контур качества. Сначала отсекаются структурные ошибки, затем проверяется поведение.

# CI/CD: как сделать тесты частью процесса, а не пожеланием

Если тесты живут только локально, их ценность ограничена. Кто-то запускает их, кто-то нет, а качество становится вопросом дисциплины отдельных людей. CI снимает этот риск, потому что проверки становятся обязательным этапом потока.

Для GitHub Actions минимальный рабочий пайплайн может выглядеть так:

name: tests

on:
  pull_request:
  push:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt
      - run: pip install pytest pytest-cov pyright
      - run: pyright
      - run: pytest tests/unit tests/integration --cov=app --cov-fail-under=80

Для GitLab CI логика та же:

stages:
  - test

test:
  stage: test
  image: python:3.12
  script:
    - pip install -r requirements.txt
    - pip install pytest pytest-cov pyright
    - pyright
    - pytest tests/unit tests/integration --cov=app --cov-fail-under=80

Ключевая инженерная мысль здесь простая. Неважно, какая платформа CI выбрана. Важно, что правила качества автоматизированы и единообразны для всех.

# Частые анти-паттерны, из-за которых тесты теряют ценность

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

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

Третий анти-паттерн это flaky-тесты, которые иногда красные, иногда зеленые без изменений в коде. Как только команда привыкает к мысли “этот тест иногда сам по себе падает”, доверие к тестовому пакету рушится.

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

# Реальный сценарий Red -> Green -> Refactor на короткой функции

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

Сначала Red:

def test_validate_password_ok():
    assert validate_password("abc12345") is True


def test_validate_password_too_short():
    assert validate_password("a1") is False

Green, минимальная реализация:

def validate_password(value: str) -> bool:
    if len(value) < 8:
        return False
    has_digit = any(ch.isdigit() for ch in value)
    has_alpha = any(ch.isalpha() for ch in value)
    return has_digit and has_alpha

Refactor и расширение тестов:

import pytest


@pytest.mark.parametrize(
    "value,expected",
    [
        ("abc12345", True),
        ("abcdefgh", False),
        ("12345678", False),
        ("ab12", False),
    ],
)
def test_validate_password_parametrized(value, expected):
    assert validate_password(value) is expected

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

# Что делать уже завтра в реальном проекте

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

Параллельно стоит зафиксировать минимальные правила качества в CI. Запуск юнитов, запуск интеграционных тестов, запуск type checker, порог покрытия, блокировка merge при красном пайплайне. Это уже создает каркас процесса, который можно постепенно усиливать.

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

# Вместо финала

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

Команда, которая умеет писать понятные юниты, осмысленные интеграционные тесты и ограниченный набор E2E на критический путь, обычно выпускает изменения чаще и спокойнее. Не потому, что у нее “больше тестов”, а потому что у нее лучше управляется риск.

И в этом главный смысл всей темы. Тесты нужны не ради тестов. Они нужны ради управляемой разработки.

# Динамика vs Статика

Итак, что же такое типизация? Новым это понятие может оказаться только для питонистов, ведь большинство классических языков таких как C, Java, Rust и многие другие исходно были созданы, как языки со статической типизацией. Но что это означает? Давайте рассмотрим небольшой пример на C:

int sum(int a, int b) {
    return a + b;
}

int main() {
    printf("%d\n", sum(10, 20));

    // printf("%d\n", sum("10", 20));
}

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

error: passing argument 1 of ‘sum’ makes integer from pointer without cast
   10 |     printf("%d\n", sum("10", 20));
      |                        ^~~~
      |                        |
      |                        char *
note: expected ‘int’ but argument is of type ‘char *’

Лог сообщает нам, что параметр функции, ожидая int, получил аргумент типа char * (для упрощения можем считать это эквивалентом строки). На первый взгляд ничего удивительного, для нас с вами — питонистов, в этом нет. Ведь вот такой код на Python тоже упал бы с ошибкой:

def sum(a, b):
    return a + b

print(sum("10", 20)) # TypeError

В чем же разница, спросите вы? Давайте немного подправим оба этих примера на C и на Python. Попробуем вызвать функцию sum от двух строк:

print(sum("10", "20")) # > 1020

Здесь мы не получаем никаких ошибок, потому что действует полиморфизм, а для строк операция сложения тоже реализована. Но что будет в C?

int main() {
    printf("%d\n", sum("10", "20"));
}

Такую программу не выйдет даже скомпилировать. Мы опять получим точно такой же лог ошибки, который был ранее. Обратите внимание на то, как мы определяли функцию sum в языке C. Там мы явно указали типы входных аргументов как int. Это означает, что аргумент любого другого типа нельзя передать в эту функцию. Это и называется статической типизацией. Также статическая типизация обязывает указать тип для каждой переменной и запрещает менять типы переменных после определения оных. То есть тип фиксирован, статичен.

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

# Преимущества типизации

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

Python в этом рейтинге, кстати говоря, на последнем месте. Может быть типизированный Python как раз поможет нам исправить этот печальный факт? К сожалению, нет. Поскольку Python как не был исконно, так по сей день остается, не статически типизированным языком. Аннотации типов в Python остаются опциональными, их можно не указывать. И сам интерпретатор Python в runtime не проверят их.

Тут мы переходим ко второму преимуществу, которое открывают для нас типы. И это качество кода.

“Цель типизации в Python — помочь инструментам разработки искать ошибки в кодовых базах на Python с помощью статического анализа, то есть не выполняя тестов кода.”

Лусиану Рамальо, “Python. К вершинам мастерства”

Расширяя эту мысль, мы можем уточнить, что цели типизации это:

• Раннее выявление ошибок — до runtime-а, до падения кода на продакшене
• “Экстракция” тестов — правильная типизация помогает уменьшить количество тестов, писать и поддерживать которые сложнее, чем типы. В тестах остаётся тестировать бизнес логику, а не банальное несоответствие примитивов.
• Улучшение читаемости кода — PEP 20 говорит нам о том, что “явное лучше неявного”. Когда мы читаем код, нам достаточно увидеть сигнатуру функции, не вчитываясь в её реализацию
• Упрощение разработки в IDE — больше подсказок и предупреждений о потенциальных ошибках.
• Повышение качества архитектуры — типы “заставляют” проектировать правильные абстракции.

# Как писать типизированно

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

• Интерфейс — это класс, у которого все методы абстрактные, то есть не содержат деталей реализации.
• Абстрактный класс — это класс, у которого, помимо абстрактных методов, есть еще и реализованные методы.
• Протокол — это неявный интерфейс.

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

## Примитивы

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

def multi_string(string, n):
    return string * n

print(multi_string("cat", 3)) # > catcatcat

Это простейшая функция, которая принимает на вход строку и число, а возвращает строку, полученную путём конкатенации исходной строки с самой собой $n$ раз. Давайте типизируем эту функцию!

def multi_string(string: str, n: int) -> str:
    return string * n

Синтаксис простой: типы для входных параметров мы подписываем через двоеточие, а выходной тип с помощью стрелочки. Теперь наши редакторы кода (IDE) будут подсвечивать для нас ошибку, в случае если мы неправильно передадим входные или неправильно обработаем выходные значения функции:

Таким образом можно проаннотировать все классические примитивы — str, int, bytes, float, Decimal, bool.

## Объединение типов

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

def normalize(data: str | bytes) -> str:
    if isinstance(data, bytes):
        return data.decode("utf-8")
    return data

В примере выше функция normalize принимает на вход либо строку, либо последовательность байт и на выход всегда возвращает строку в кодировке utf-8. Через union (|) можно перечислить любое количество типов, но важно понимать, где это уместно. Если вам хочется написать простыню из объединения десяти типов, стоит хорошенько подумать. О том как такие ситуации разрешаются, мы скажем ниже.

Объединение также можно использовать и в указании типа возвращаемого значения. Но использовать это стоит только для спецификации опциональности. Например:

def parse_int(value: str) -> int | None:
    if not value.isdigit():
        return None
    return int(value)

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

## Спецификация коллекций

Помимо примитивов мы конечно же можем аннотировать и коллекции. Но лучше не ограничиваться простым data: list, а специфицировать и содержание коллекции тоже. Это можно сделать, используя синтаксис квадратных скобок. Давайте приведём несколько примеров:

def format_user(user: tuple[str, int]) -> str:
    name, score = user
    return f"{name}: {score} points"

def average(values: list[float]) -> float:
    if len(values) == 0:
        return 0
    return sum(values) / len(values)

def total_count(counters: dict[str, int]) -> int:
    return sum(counters.values())

Это, конечно, не покрывает все возможные сценарии, которые могут возникнуть в реальном продакшн коде. В секциях TypedDict, NamedTuple, Dataclass мы расширим наш инструментарий.

## Mapping и MutableMapping

Mapping и MutableMapping — это абстрактные классы для словари-подобных структур. Mapping гарантирует только чтение (ключи, значения, итерацию), а MutableMapping говорит, что объект можно изменять.

from collections.abc import Mapping, MutableMapping

def read_config(cfg: Mapping[str, str]) -> str:
    return cfg["DATABASE_URL"]

def patch_config(cfg: MutableMapping[str, str]) -> None:
    cfg["DEBUG"] = "1"

Если функция только читает данные, указывайте Mapping. Если меняет — MutableMapping. Это маленькая, но важная подсказка для читателя и статического анализатора.

## NamedTuple

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

from typing import NamedTuple

class User(NamedTuple):
    id: int
    username: str
    score: int

def print_user(user: User) -> str:
    return f"{user.username} ({user.id}) = {user.score}"

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

## TypedDict

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

from typing import TypedDict

class User(TypedDict):
    id: int
    username: str
    email: str | None

def send_email(user: User) -> None:
    ...

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

## Dataclass

dataclass — это удобный способ описать “контейнер данных” с инициализатором, сравнениями и читаемым repr. Такой класс изменяем, если не указать обратное, и отлично подходит для домена или DTO.

from dataclasses import dataclass

@dataclass
class User:
    id: int
    username: str
    email: str | None = None

def normalize(user: User) -> User:
    user.username = user.username.lower()
    return user

dataclass хорош, когда нужна структура, которая может изменяться, и когда важна ясная модель данных. Если объект должен быть неизменяемым, используйте @dataclass(frozen=True).

## Enum

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

from enum import Enum

class Status(Enum):
    NEW = "new"
    DONE = "done"
    FAILED = "failed"

def is_done(status: Status) -> bool:
    return status is Status.DONE

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

## Кастомные классы

Конечно же система типов позволяет специфицировать не только примитивы, но и наши собственные или библиотечные классы. Например:

class User:
    id: int
    username: str
    email: str
    friends: list[User]

def hand_shake(user1: User, user2: User) -> None:
    user1.friends.append(user2)
    user2.friends.append(user1)

## Абстрактные классы

В Python у нас существует прекрасный модуль collections.abc. Там уже описан ряд абстрактных классов, которые в 90% случаев закроют все наши потребности. Они полезны, когда вы хотите описывать поведение, а не конкретную реализацию. Итак, что же там представлено? А вот что:

collections.abc.ABCMeta
collections.abc.AsyncGenerator
collections.abc.AsyncIterable
collections.abc.AsyncIterator
collections.abc.Awaitable
collections.abc.Buffer
collections.abc.ByteString
collections.abc.Callable
collections.abc.Collection
collections.abc.Container
collections.abc.Coroutine
collections.abc.EllipsisType
collections.abc.FunctionType
collections.abc.Generator
collections.abc.GenericAlias
collections.abc.Hashable
collections.abc.ItemsView
collections.abc.Iterable
collections.abc.Iterator
collections.abc.KeysView
collections.abc.Mapping
collections.abc.MappingView
collections.abc.MutableMapping
collections.abc.MutableSequence
collections.abc.MutableSet
collections.abc.Reversible
collections.abc.Sequence
collections.abc.Set
collections.abc.Sized
collections.abc.ValuesView

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

from collections.abc import Iterable

def total(values: Iterable[int]) -> int:
    return sum(values)

total([1, 2, 3])
total((1, 2, 3))
total({1, 2, 3})

Иногда можно встретить такие же импорты из модуля typing: from typing import Iterable, Sequence. Но в реальности это просто реэкспорт реализаций из collections.abc. Поэтому сейчас лучше импортировать абстрактные классы напрямую из collections.abc.

## Sequence и Iterable

Эти два типа часто путают. Iterable гарантирует только то, что объект можно перебирать в цикле. Никаких индексов, длины или упорядоченности тут не обещается. Sequence же, кроме возможности итерации, гарантирует наличие индексации и длины, то есть __getitem__ и __len__. Из этого вытекает разница в том, что можно безопасно делать с объектом.

from collections.abc import Iterable, Sequence

def sum_any(values: Iterable[int]) -> int:
    total = 0
    for v in values:
        total += v
    return total

def head(values: Sequence[int]) -> int:
    return values[0]

Функция sum_any примет и список, и кортеж, и генератор. Функция head уже не сможет принять генератор, потому что у него нет индексации, и мы не можем написать values[0]. Поэтому, когда вам важно только итерироваться — используйте Iterable, а если вы опираетесь на индексацию или длину — Sequence.

## Callable

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

from collections.abc import Callable

def apply(values: list[int], fn: Callable[[int], int]) -> list[int]:
    return [fn(v) for v in values]

Если сигнатура заранее неизвестна, можно использовать Callable[..., ReturnType], но это стоит делать как крайний вариант.

## Дженерики (generics)

Generics — это параметризованные обобщённые типы. Проще говоря, это типы, которые сами принимают типы. Это важно, когда вы хотите сохранить связь между входом и выходом, а не потерять её в Any. Например, функция first возвращает элемент того же типа, что и внутри переданной коллекции:

from collections.abc import Sequence
from typing import TypeVar

T = TypeVar("T")

def first(items: Sequence[T]) -> T:
    return items[0]

Без дженериков нам пришлось бы писать Sequence[Any] и терять тип результата. А с дженериками анализатор знает, что если мы передали Sequence[str], то вернётся str. Это особенно важно для коллекций, фабрик и репозиториев, где один и тот же код обрабатывает разные типы.

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

from collections.abc import Hashable, Iterable
from typing import TypeVar

HashableT = TypeVar("HashableT", bound=Hashable)
def mode(data: Iterable[HashableT]) -> HashableT:
    ...

## Literal

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

from typing import Literal

def export_report(format: Literal["csv", "json"]) -> bytes:
    ...

Сигнатура выше сразу задаёт контракт: третьего формата тут нет. Это делает API понятнее и позволяет анализатору ловить опечатки вроде "jsno" до запуска.

## Статические анализаторы

И наконец пришло время познакомиться с тем, кто “оживляет” типизацию в Python: со статическими анализаторами. Они читают аннотации, сопоставляют их с кодом и подсвечивают ошибки до runtime.

• mypy - классический статический анализатор типов для постепенного внедрения типизации. Сильная сторона: экосистема плагинов и тонкая настройка строгости по модулям. Слабая сторона: без настройки может быть либо слишком мягким, либо слишком шумным.
• pyright - быстрый и понятный чекер. Сильная сторона: хорошие диагностические сообщения и быстрый feedback. Слабая сторона: расширяемость через плагины хуже, чем в mypy.
• pyrefly - новый быстрый анализатор на Rust. Сильная сторона: высокая скорость и интеграция с LSP. Слабая сторона: проект ещё молодой, поэтому часть поведения может меняться.
• ty - новый Rust-инструмент от Astral (пока beta). Сильная сторона: скорость и современная архитектура. Слабая сторона: pre-release стадия, часть возможностей ещё догоняет зрелые чекеры.

Установить и запускать их можно через uv:

uv tool install mypy
uv tool install pyright
uv tool install pyrefly
uv tool install ty

uvx mypy .
uvx pyright .
uvx pyrefly check
uvx ty check

Ниже бизнес-пример с намеренными ошибками типизации:

from dataclasses import dataclass
from typing import NewType

UserId = NewType("UserId", int)

@dataclass
class User:
    id: UserId
    email: str
    is_active: bool

def discount(total: int, percent: int) -> int:
    return total - total * (percent / 100)

def send_invoice(user: User, amount: int) -> str:
    if not user.is_active:
        return None
    return f"invoice for {user.email}: {amount}"

def main() -> None:
    user = User(id=42, email=123, is_active="yes")
    total = discount("1000", 10)
    send_invoice(user, "500")

Проверка pyright даст сообщения примерно такого вида:

error: Type "float" is not assignable to return type "int"
error: Type "None" is not assignable to return type "str"
error: "Literal[42]" is not assignable to "UserId"
error: "Literal[123]" is not assignable to "str"
error: "Literal['yes']" is not assignable to "bool"
error: "Literal['1000']" is not assignable to "int"
error: "Literal['500']" is not assignable to "int"

Что важно в этом выводе:

• Ошибки в discount и send_invoice показывают нарушение контракта функции: сигнатура обещает одно, реализация делает другое.
• Ошибки в main показывают, что граничный слой (ввод/DTO) передаёт неверные типы в доменную логику.
• Сообщение про UserId демонстрирует, зачем NewType полезен в бизнес-коде: id пользователя нельзя случайно подменить обычным int без явного решения разработчика.

## Stub файлы (.pyi)

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

Файл .pyi содержит только типовые сигнатуры и не содержит реализации. Статические анализаторы ищут их рядом с кодом или в отдельных пакетах types-*. Пример:

calc.py:

def add(a, b):
    return a + b

calc.pyi:

def add(a: int, b: int) -> int: ...

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

## TypeAlias

Когда тип становится сложным, его лучше вынести в алиас, чтобы сигнатуры были читаемыми. Это особенно полезно для бизнес-терминов вроде UserId, Currency, Payload. Для этого используют TypeAlias:

from typing import TypeAlias

UserId: TypeAlias = int
Payload: TypeAlias = dict[str, str | int | float]

Теперь можно писать:

def send(user_id: UserId, payload: Payload) -> None:
    ...

В Python 3.12+ для того же есть синтаксис type:

type UserId = int
type Payload = dict[str, str | int | float]

Это всё тот же алиас, просто короче и читабельнее.

## TypeAlias vs NewType

TypeAlias — это просто синоним типа, он не создаёт новый тип. NewType же создаёт новый тип на уровне статической проверки, хотя на runtime это всего лишь функция-обёртка. Это полезно, когда у вас есть логически разные значения одного базового типа, например UserId и OrderId.

from typing import NewType, TypeAlias

UserId: TypeAlias = int
OrderId = NewType("OrderId", int)

def get_user(user_id: UserId) -> None:
    ...

def get_order(order_id: OrderId) -> None:
    ...

UserId и int считаются одним и тем же типом, а вот OrderId уже не совместим с int без явного приведения.

# Как правильно использовать типизацию

Сразу хочу сформировать у вас верную предпосылку относительно типизации. Точно так же как и у тестов, задача у типов падать, не проходить, крашиться и бесить этим нас. Если они этого не делают, их можно просто выкинуть. Это означает, что чем менее снисходительна к нам система типизации, тем лучше для нас. Потому что это заставляет нас думать о том, как писать надёжный и безопасный код. Строгость системы типизации (как и у тестов) помогает выявлять ошибки, но для этого они должны не проходить.

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

## Возвращение None

Также обратите внимание на случай, когда функция ничего не возвращает:

def print_weather(weather: Weather):
    print("Weather:")
    for date, data in weather.by_days().items():
        print(date)
        print(f"\t{data.temperature}")
        print(f"\t{data.humidity}")
        print(f"\t{data.wind_speed}")
        print("========")

tmp = print_weather(Weather()) + 1

Как известно в Python, если в функции не стоит return, значит она ничего не возвращает. Об этом знают и статические анализаторы. Например, pyright для этого кода, где намеренно в последней строчке допущена ошибка, даст следующее предупреждение:

error:
    Operator "+" not supported for types "None" and "Literal[1]"

По этому сообщению становится ясно, что pyright “понимает”, что возвращаемый тип функции None. Так значит можно их не подписывать? Нет, не значит. Во-первых, тут можно просто сослаться на PEP 20, “явное лучше неявного”. Во-вторых, стоит учесть специфику developer experience (DX) при разработке на Python. Все, кто пишут на Python, знают, что типизация опциональна. И это создаёт двусмысленность: когда я смотрю на сигнатуру функции, где не специфицировано возвращаемое значение, я не понимаю, это автор кода просто не стал её типизировать и на самом деле она возвращает не None, либо там действительно возвращается None. Разрешается эта двусмысленность только погружением в детали реализации функции, что усложняет работу с кодом.

## Вход и выход у функции

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

Important

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

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

• Типизированный Python для профессиональной разработчики
• FastAPI type hints guide (Полезно для web-разработчиков)
• RealPython, Type Checking Guide
• Упражнения

Итак, с чего же начинается любой вклад. В идеале, с проблемы. Проблемой можно называть что угодно, в том числе нехватка каких-то новых фич, отсутствие либо неполнота страниц документации по определённому вопросу, какой-то вопрос, либо же банальные баги, которые есть везде. Лично вы проблему ни с чем не спутаете, ведь она обязательно будет сопровождать зудящим чувством, что “что-то подбешивает.” Но будет ли это проблемой для других пользователей и разработчиков? Для того, чтобы это понять и синхронизировать ваше представление с представлениями команды, и существует issue.

CONTRIBUTION.md

В каждом проекте есть свои собственные устоявшиеся правила того, как нужно в них участвовать. Эти правило описываются либо в README.md в отдельном параграфе “Contribution”, либо в специальном файле CONTRIBUTION.md. Обязательно прочитайте его в самом начале. Этот файл имеет первый приоритет. То есть даже если вы понимаете, что какие-то практики отходят от той правильной схемы, которую мы рассмотрим ниже, всё равно следуйте им. Некоторые крупные проекты, такие как Postgres или linux-kernel вообще до сих пор работает по mail-листам. Следует уважать те традиции, которые сложились в репозитории, даже если сейчас это выглядит как legacy.

# 1. Issue

Issue представляет из себя тикет, который хранится в репозитории. Создать его может любой человек, пришедший в репозиторий. Но я рекомендую вам, перед тем как бросаться описывать, вашу проблему, сделать несколько попыток по поиску подобных issue, чтобы не нагружать лишней работой мейнтейнеров репозитория. Давайте посмотрим как это можно сделать:

gh issue list --search "app crashed"

Этот и все дальнейшие примеры будут с использованием официальной утилиты gh. Она позволяет из консоли выполнять все базовые операции с GitHub. Рекомендую использовать её для простых операций, для ускорения работы.

Параметр search позволяет задавать прям в себе добавлять различные фильтры поиска. Давайте попробуем их добавить:

gh issue list --search "app crashed is:open label:bug created:>2024-01-01"

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

  graph LR
    A[Excepted] ---> B("Action (run/click/etc)")
    B ---> C[Got]

В крупных проектах существуют issue templates, которые помогут вам оформить issue в соответствии с теми стандартными, которые приняты в этом проекте. Создать issue можно командой:

gh issue create

Так же отличной практикой является предоставление docker образа, в котором настроено все окружение, и проблема гарантированно воспроизводима. Либо хотя бы предоставить лог. Профессиональным подходом так же будет локализация проблемы, настолько насколько это возможно. Например, вы получили ошибку в таком файле:

import fruits
import logistic

a = fruits.Apple()
basket = fruits.MakeBasket()
basket.put(a)
logistic.send(basket)

Конечно, можно было бы так в issue и написать. Но еще лучше будет самостоятельно поэкспериментировать с этим кодом и понять, что именно не так. Например проверить удалось ли добавить яблоко в корзину:

basket.put(a)
print(basket.content())

Возможно проблема в том, что мы пытаемся отправить пустую корзину, что будет означать баг в методе put. Либо же все-таки проблема в методе send. Таким образом, мы срезаем лишнее, оставляя в сообщении issue суть проблемы.

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

# 2. Fork

Когда вы поняли какую проблемы вы решаете и убедились, что это реально проблема, можно переходить к её решению. Для этого стоит для начала сделать fork репозитория. Это будет, как ценным подспорьем для вас если вы, например, будете тестировать CI или просто сильно опережать оригинальный репозиторий, так и позволит отправлять pull request-ы, ведь вы, скорее всего, не имеете прав для внесения изменений в оригинальный репозиторий:

gh repo fork <OWNER>/<REPO>

Клонировав fork локально вносите изменения в отдельной ветке, которую будет удобнее назвать номером issue, который вы пытаетесь закрыть. Почему? Потому что в коротком лаконичном названии ветки далеко не всегда удастся выразить суть проблемы, на которую, возможно, ушло несколько месяцев обсуждения в тиките. Поэтому гораздо удобнее просто на него сослаться, через номер issue:

git switch -c 42

В GitHub flow мы не создаем сложную структуру из веток, где у каждой есть свое значение. Вместо этого у нас есть master-ветка в которую попадают только прошедшие все проверки изменения. А попадают они туда из множества, так называемых feature-веток, которые мы предлагаем тут привязывать к конкретным issue. А раз в какое-то время мы на master ветке выпускаем релиз. В итоге получается вполне лакончиная структура:

  %%{init: {
  "gitGraph": {
    "tagLabelColor": "#ffffff",
    "tagLabelBackground": "#d73a49"
  }
}}%%
gitGraph
    commit
    commit
    branch "42"
    checkout "42"
    commit
    commit
    checkout main
    merge "42"
    commit tag: "🚩 v1.1.23"

    branch "44"
    checkout "44"
    commit
    commit
    commit
    checkout main
    merge "44"
    commit tag: "🚩 v1.2.0"

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

gh repo sync <your-username>/<fork-repo> --branch main

# 3. Pull request

Когда изменения внесены и закоммичены, то можно отправлять pull request. Удобнее всего просто остаться на вашей ветке и выполнить команду ниже. gh сам сформирует подходящий pull request:

gh pr create

После создания PR могут автоматически запуститься проверки, если в репозитории настроен CI. И это отлично. Потому что проверки упрощают и ускоряют процесс ревью. Вы сразу можете увидеть, что в вашем коде например не проходят проверки стилей, или, что вы не написали тесты на свой код и из-за этого упал code coverage. Не игнорируйте это, а делайте новой коммиты в той же ветки и после пуша они автоматически добавятся в PR и проверки будут перезапущены. Мейнтейнер репозитория даже не начнет ревью вашего PR, пока все проверки в нем не станут зелёными. Проверить статус pull request-а вы можете командой:

gh pr status

Так же старайтесь сделать аккуратную историю коммитов в pull request-е, чтобы упросить процесс review. В этом вам помогут squash коммиты.

Когда вы прорвались через все авто-проверки, не стесняйтесь обращаться к архитектору репозитория и просить его ревью. Он либо сам сделает ревью вашего PR, либо делегирует это кому-то из команды. На GitHub это делается просто через тег: @username. Часто уведомления о том, что пришёл новый pull request могут быть отключены, и тем более архитектор не узнает, когда вы внесете все правки, чтобы пройти CI. Поэтому скромность здесь может привести к тому, что ваш pull request просто никто не увидит. Тоже, кстати, касается и issue.

Если вы понимаете, что ваш pull request полностью закрывает тот issue, который вы решали, то в сообщениях PR можно указать Close \#49, тогда issue будет автоматически закрыт после слияния pull request-а.

# 4. Merge

Итак, когда вы прошли все авто-проверки и ручное ревью, то ваш код попадет в master-ветку репозитория и вы можете считать себя полноправным контрибьютором в этот проект. Так держать!

Обратите так же внимание на интересную практику, которая, на мой взгляд, очень профессиональна. Представим что вы обнаружили и доложили о каком-то баге в issue. Это уже вклад в репозиторий. Дальше предлагается создать pull request, в котором вы пишете тест, который воспроизводит этот баг. Тест конечно-же будет падать. Но вы присылать pull request, внося тем самым этот тест в состоянии disabled в кодовую базу. Так же можно оставить TODO метку. И это станет еще большим вкладом в репозиторий, поскольку вы добавили содержательный тест, а этом всегда очень полезно. И наконец вторым pull request-ом вы уже присылаете изменения, которые чинят код так, чтобы он проходил этот тест. И вновь увеличиваете ваш вклад. Таким образом вы оставили после себя массу артефактов в репозитории: issue, усиленная система тестов, и исправленный баг. Это будет отличным примером реализации TDD (Test Driven Development) подхода.

Таким образом мы с вами прошли полный цикл от проблемы до вклада в master-ветку:

  flowchart LR
    BUG["Find a bug / Need feature"] --> ISSUE["Create Issue"]
    ISSUE --> DISCUSS["Discussion / Planning"]
    DISCUSS --> PR["Open Pull Request"]
    PR --> CI["PR Checks with CI"]
    CI --> REVIEW["Reviewer Reviews PR"]
    REVIEW --> MERGE["Merge PR into main"]
    MERGE --> BUG

Вы можете проверить свои силы уже сейчас, найдя подходящий issue с помощью этих прекрасных сервисов:

• Good First Issue — Issue, которые отлично подходят для новичков.
• Awesome for Beginners — Подборка проектов для начинающих.
• Up For Grabs — Открытые для решения задачи по разным технологиям.
• First Contributions — Репозиторий с манулом с списком открытых проектов.
• First Timers Only — Больше подобных ресурсов.

Не забывайте, что вы и сами можете регистрировать свои проекты на этих ресурсах, чтобы привлекать к себе новых разработчиков!

GitHub CLI

Если вас заинтересовала продуктивная работа с GitHub из консоли с помощью утилиты gh, обратите внимание на её документацию. А так же на то, что gh поддерживает расширения, ознакомиться с которыми вы можете с помощью команды gh ext browse или написать своё!

Так же можно почитать по теме:

• Official GitHub guideline
• Pull Requests like a Pro, Navendu Pottekkat
• 10 Common Mistakes to Avoid When Contributing to Open Source Projects
• Open Source for Beginners