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

Вокруг тестов в 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

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

Дисперсия:

Как видите, для среднего нужна сумма: первая проблема — как получить сумму без всех чисел? А для дисперсии нужно среднее: вторая проблема — как узнать среднее без всех данных?

# Интуиция метода

Попробуем прочувствовать интуицию метода Уэлфорда. Представьте, у нас есть набор данных: $A = \{1, 2, 3\}$, среднее этого набора $\overline{x}_A = \frac{1 + 2 +3}{3} = 2$, и затем мы получили еще одно число: $6$. Чувствуете, что оно сдвинет наше среднее в сторону больших значений? Но насколько? Представьте похожий набор, но с большим количеством данных: $B = \{1, 1, 2, 2, 3, 3\}$, среднее также равно $2$, и мы также добавляем число $6$. Снова чувствуем, что сдвиг будет в сторону больших значений, но не такой сильный. Проверим нашу интуицию:

Наша интуиция была права! Осталось понять, как мы можем вычислить эту дельту, если у нас есть только предыдущее среднее $\overline{x}_{i - 1}$, новое число $x_i$ и количество наших чисел. Метод Уэлфорда гласит: каждое новое значение сдвигает среднее в свою сторону с весом $1/i$:

Проверим это для набора $B$. У нас есть среднее без нового числа $\overline{x}_{i - 1} = 2$ и новое число $x_i = 6$, и это седьмое число, $i = 7$. Цель — найти среднее $\overline{x}_i$ по формуле Уэлфорда:

Как видите, это абсолютно точное значение. Отлично!

# Дисперсия, корреляция, ковариация

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

Для дисперсии мы поддерживаем текущее среднее $\overline{x}$ и сумму квадратов разностей $S$. Для каждой новой точки данных $x_n$ на шаге $n$:

Дисперсию генеральной совокупности можно затем вычислить как $\sigma^2 = S_n/n$, а выборочную дисперсию как $s^2 = S_n/(n-1)$.

Этот подход красиво расширяется на ковариацию и корреляцию. Для двух переменных $X$ и $Y$ мы поддерживаем счетчики $n$, средние $\overline{x}$ и $\overline{y}$, и накопленные произведения $C_{xy}$:

Ковариация тогда равна $\text{cov}(X,Y) = \frac{C_{xy_n}}{(n-1)}$, а корреляция $\text{corr}(X,Y) = \frac{C_{xy_n}}{\sqrt{S_{x_n} S_{y_n}}}$.

# Реализация на C

Вот полная реализация алгоритма Уэлфорда на C для вычисления среднего и дисперсии:

#include <stdio.h>
#include <math.h>

typedef struct {
    long long n;
    double mean;
    double M2;
} welford_state;

void welford_update(welford_state *state, double x) {
    state->n++;
    double delta = x - state->mean;
    state->mean += delta / state->n;
    state->M2 += delta * (x - state->mean);
}

double welford_mean(const welford_state *state) {
    return state->mean;
}

double welford_variance(const welford_state *state) {
    return (state->n > 1) ? state->M2 / (state->n - 1) : 0.0;
}

double welford_stddev(const welford_state *state) {
    return sqrt(welford_variance(state));
}

int main() {
    welford_state state = {0, 0.0, 0.0};
    double test_data[] = {1.0, 2.0, 3.0, 6.0};
    size_t data_size = sizeof(test_data) / sizeof(test_data[0]);
    
    for (size_t i = 0; i < data_size; i++) {
        welford_update(&state, test_data[i]);
        printf("Added %.1f: mean=%.3f, variance=%.3f, stddev=%.3f\n",
               test_data[i], welford_mean(&state), 
               welford_variance(&state), welford_stddev(&state));
    }
    
    return 0;
}

Для ковариации и корреляции мы можем расширить этот подход:

typedef struct {
    long long n;
    double mean_x, mean_y;
    double C2;
} welford_cov_state;

void welford_cov_update(welford_cov_state *state, double x, double y) {
    state->n++;
    double delta_x = x - state->mean_x;
    double delta_y = y - state->mean_y;
    state->mean_x += delta_x / state->n;
    state->mean_y += delta_y / state->n;
    state->C2 += delta_x * (y - state->mean_y);
}

double welford_covariance(const welford_cov_state *state) {
    return (state->n > 1) ? state->C2 / (state->n - 1) : 0.0;
}

Мы, разработчики, живём в мире динамических значений. API-токены, временные URL от сервисов туннелирования, таких как ngrok или localtunnel, строки подключения к базам данных и флаги функций — это жизненная сила наших современных приложений. В компилируемых языках или средах вроде Node.js у нас есть богатая экосистема инструментов, таких как dotenv и библиотеки для работы с конфигурацией, чтобы управлять этой динамикой беспрепятственно. Они позволяют выносить конфигурацию наружу, подставляя значения из переменных окружения или менеджеров секретов во время выполнения.

Но что насчёт статических частей наших проектов? Представьте простой HTML-файл, которому нужно отобразить временный публичный URL, объект конфигурации JavaScript для лёгкого скрипта или статический конфигурационный файл для устаревшей системы. Они не обрабатываются сборщиком или фреймворком; это плоские файлы. Традиционное решение — ручное, подверженное ошибкам и разочаровывающее: запустить команду, посмотреть на её вывод, скопировать новое значение, открыть файл, найти нужную строку, вставить, сохранить, а затем повторить для каждого другого файла, которому нужно то же значение — скука. Этот процесс выбивает из состояния потока и полностью противоречит автоматизации, которую мы так ценим.

Я слишком часто сталкивался с этой проблемой. Постоянное переключение контекста между терминалом и редактором для обновления URL было назойливой неэффективностью. Я знал, что должен быть лучший способ — способ рассматривать эти статические файлы как динамические конечные точки для конфигурации. Это разочарование стало катализатором для Devsyringe, CLI-утилиты, написанной на Go, предназначенной для автоматизации именно этого рабочего процесса.

# Основная идея: Декларативное внедрение конфигурации

Мотивация к созданию Devsyringe заключалась не в том, чтобы создать ещё один движок шаблонов или сложную систему сборки. Цель была проще и более сфокусированной: создать инструмент, который может запустить команду, распарсить её вывод на предмет конкретного значения с помощью regex, а затем внедрить это значение в один или несколько целевых файлов. Всё поведение определяется декларативно в простом YAML-файле конфигурации, обычно называемом devsyringe.yaml.

Думайте об этом как об универсальном адаптере между динамическим выводом CLI-инструментов и статическим текстом ваших файлов. Он создан для сценариев, где более тяжёлые решения являются избыточными или просто не подходят. Настоящая магия заключается в автоматизации без участия рук; вы определяете правила один раз, и с этого момента одна команда поддерживает всё в синхронизации. Это клей позволяющий связывать между собой различные этапы любого пайплайна.

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

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

Классическая автоматизация туннеля.
При разработке веб-приложений вам часто нужно открывать ваш локальный сервер для интернета. Инструменты вроде localtunnel или serveo генерируют уникальные, случайные URL, которые должны быть настроены и в вашем frontend, и в backend коде. Вот как Devsyringe обрабатывает это автоматически:

serums:
  localtunnel:
    source: lt --port 8080
    mask: https://[a-z0-9\-]+\.loca\.lt
    targets:
      env_file:
        path: ./.env
        clues: ["API_BASE_URL"]
      frontend_config:
        path: ./src/config.js
        clues: ["API_URL", "const"]

Эта конфигурация определяет полный workflow: выполнить команду туннеля, извлечь URL с помощью regex и внедрить его как в .env файл, так и в JavaScript конфигурацию. Весь процесс сводится к одной команде: dsy inject.

Динамическая документация и автоматизация резюме.
Вот более сложный use case: поддержание технической документации или резюме, сгенерированных в LaTeX, в актуальном состоянии с live-статистикой. Представьте, что ваш файл résumé.tex содержит строку вроде: \newcommand{\githubstars}{427}

С Devsyringe вы можете автоматически заполнять это вашей текущей статистикой с GitHub:

serums:
  github_stats:
    source: curl -s "https://api.github.com/users/yourusername/repos" | jq 'reduce .[] as $repo (0; . + $repo.stargazers_count)'
    mask: "(\d+)"
    targets:
      resume:
        path: ./resume.tex
        clues: ["githubstars"]

Эта конфигурация вызывает псевдо GitHub API, извлекает общее количество звёзд и обновляет исходный файл LaTeX. Ваше резюме поддерживает точную, актуальную статистику без ручного вмешательства — идеально для заявок на работу или обновлений портфолио. А ведь затем можно настроить CI для регулярного обновления с каждым пушем, если вы используете репозиторий для резюме.

Продвинутое управление инфраструктурой.
Для более сложных setup’ов Devsyringe отлично подходит для автоматизации инфраструктуры. Рассмотрим эти сценарии:

• Получение свежих учётных данных БД из HashiCorp Vault и их внедрение в свойства приложения.
• Получение текущих endpoint’ов развёртывания из service discovery и обновление конфигураций API gateway.
• Получение IP-адресов инфраструктуры от облачных провайдеров и обновление правил security groups.
• Извлечение метаданных сборки из CI-систем и обновление манифестов развёртывания.

Паттерн остаётся такой же: команда  извлечение вывода  внедрение в файл. Эта простота делает его адаптируемым к бесчисленным сценариям автоматизации. Если вам нужно конкретное значение — нет проблем, используйте: echo '<my-value>' в качестве команды, devsyringe сделает всё остальное сам.

# Техническая архитектура и реализация

Хотя концепция Devsyringe проста, создание надёжного CLI-инструмента требует тщательной архитектуры. Проект использует сильные стороны Go для конкурентной обработки и кроссплатформенной совместимости, сохраняя простоту и надёжность.

Структура проекта и шаблоны проектирования.
Архитектурная элегантность devsyringe заключается в намеренном использовании Декоратора (Decorator Pattern), который отражает многослойную структуру “капусты” — каждый “лист” оборачивает ядро, добавляя функциональность, сохраняя целостность внутренних слоёв. Этот паттерн является основополагающим для дизайна инструмента: низкоуровневые компоненты остаются в блаженном неведении о слоях выше них, обеспечивая модульность и разделение ответственности.

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

Этот подход обеспечивает бесшовную интеграцию в любой workflow. Используете ли вы его локально для управления URL туннелей или в CI/CD для внедрения секретов времени сборки, devsyringe улучшает вашу среду, не изменяя её фундаментальное поведение. Ваши конфигурационные файлы остаются валидными, ваши процессы сборки неизменными, и ваша ментальная модель неизменной — всё это при получении мощности внедрения динамических значений.

Кодовая база devsyringe следует стандартным соглашениям Go с чётким разделением ответственности:

│── cmd
│   └── dsy
│       └── main.go
└── internal
    ├── cli
    │   ├── commands.go
    │   └── tui
    │       └── tui.go
    ├── config
    │   └── config.go
    ├── process
    │   ├── process.go
    │   └── procmanager.go
    └── utils
        └── utils.go

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

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

Фреймворк Cobra CLI обеспечивает профессиональную структуру команд, автоматическую генерацию справки и завершение shell. TUI интерфейс, предлагает мониторинг процессов в реальном времени, запущенных devsyringe:
Система управления процессами использует goroutines и channels для конкурентного выполнения команд и захвата вывода. Внедрение в файлы использует простое pattern matching вместо сложного парсинга, делая его универсально применимым к любому текстовому формату.

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

# Дистрибуция и кроссплатформенная совместимость

Инструмент полезен только если его легко установить. Devsyringe использует современные инструменты Go для предоставления бесшовной установки на всех основных платформах.

Автоматизированные сборки с Goreleaser.
Проект использует Goreleaser для автоматизации процесса релиза, генерируя: Кроссплатформенные бинарники для macOS и Linux, Поддержку пакетных менеджеров (Homebrew, AUR), Пакеты Debian и RPM в GitHub releases с контрольными суммами и подписями. Поддержка Windows уже в бэклоге.

Простота установки. Пользователи могут установить через несколько каналов. Для Go-разработчиков:

go install github.com/alchemmist/devsyringe/cmd/dsy@latest

Для пользователей macOS:

brew install devsyringe

Для пользователей Arch Linux:

paru -S devsyringe

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

# Почему devsyringe изменит ваш workflow

Ценность devsyringe проявляется после первого раза, когда вы используете его по-настоящему. Тот момент, когда вы понимаете, что больше никогда не будете вручную обновлять URL туннеля в нескольких файлах. Когда ваша документация автоматически остаётся актуальной с версиями вашего API. Когда ваше резюме обновляется само с вашими последними достижениями.

Дело не только в сэкономленном времени — хотя оно накапливается удивительно быстро. Дело в поддержании состояния потока и устранении маленьких раздражений, которые накапливаются в течение сессии разработки. Вы можете быстро “заткнуть” любое значение через devsyringe, чтобы продолжить разработку, не отвлекаясь на лишнее.

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

# Начало работы и следующие шаги

Готовы устранить ручное обновление файлов из вашего workflow? Установка проста:

go install github.com/alchemmist/devsyringe/cmd/dsy@latest

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

Подумайте, где в вашем workflow вы всё ещё копируете значения между терминалом и редактором. Это ваша отправная точка. Будь то URL туннелей, API-ключи, номера версий или статистика — devsyringe, вероятно, может это автоматизировать.

Далее мы настроим удобный рабочий процесс для такого случая. Однако эта настройка будет использовать новую функцию, встроенную в Hyprland и, скорее всего, отсутствующую в других DE/композиторах. Я продемонстрирую нашу конечную цель. Например, мой режим демонстрации экрана может выглядеть так:

Если вам нравятся мои обои, вы можете найти эти и много других отличных материалов в моём репозитории dotfiles на GitHub. Не забывайте: я обожаю ваши звёзды!

Разберём всё по шагам. Во-первых, вспомним, что в релизе Hyprland версии 0.50.0 было добавлено новое правило windowrulev2 с опцией noscreenshare. Это свежий релиз, и сейчас оно управляется только из конфигурационного файла, вот так:

windowrulev2 = noscreenshare, class:^(org.telegram.desktop|obsidian|discord)$

Эта опция предписывает Hyprland рисовать чёрный прямоугольник вместо содержимого окна (даже если это окно не в фокусе или на заднем плане). Это работает идеально и защищает нашу приватность. Но я обнаружил два неудобных случая: 1. Когда мы хотим сделать скриншот (в моём случае, с помощью flameshot), Hyprland интерпретирует это как попытку поделиться экраном и скрывает все приватные окна. 2. Иногда я хочу показать что-то из моего Obsidian, например, и лезть в конфиги в этот момент — не очень хорошо.

# Управление опцией noscreenshare через CLI

Чтобы исправить этот опыт, напишем скрипт для управления правилом окна в конфиге. Если у вас нет времени, полная версия скрипта здесь. Скрипт будет комментировать или раскомментировать строку в конфигурационном файле с правилом и сохранять информацию о текущем состоянии правила в файле-маркере ~/.config/hypr/.screenshare_rule_disabled. Скрипт можно запустить с командой toggle, чтобы изменить состояние на противоположное:

#!/bin/bash

CONFIG_FILE="$HOME/.config/hypr/hyprland.conf"
STATE_FILE="$HOME/.config/hypr/.screenshare_rule_disabled"

toggle_rule() {
	# TODO
}

case ${1} in
    "toggle")
        toggle_rule
        ;;
esac

Напишем функцию toggle_rule. Мы будем использовать утилиту Linux sed (Stream Editor). Это один из самых мощных инструментов для обработки текста в Linux и Unix-системах. Он обычно используется для таких задач, как поиск и замена, преобразование текста и потоковое редактирование. Синтаксис sed, в общем виде, выглядит так:

sed [options] "script" [file...]

Нам нужна опция -i для редактирования файла на месте. Затем пишем скрипт. Сначала нам нужно найти строку с правилом noscreenshare, как в regex:

"/windowrolev2.*noscreenshare.*"

Мы начинаем с "/" для написания поискового запроса, нам нужно, чтобы строка начиналась с "windowrolev2", после чего ".*" для любого количества любых символов, между которыми "noscreenshare". Затем мы используем "/" для завершения поискового запроса и "s/" (substitute) для замены:

"/windowrulev2.*noscreenshare.*/s/^#//"

Наконец, мы используем регулярное выражение "^#" для поиска решётки в начале строки и заменяем её на ничто: "//". Полная команда выглядит так:

sed -i '/windowrulev2.*noscreenshare.*/s/^#//' "$CONFIG_FILE"

Затем используем sed для добавления решётки в начало строки аналогичным образом, в зависимости от наличия файла-маркера:

toggle_rule() {
    if [ -f "$STATE_FILE" ]; then
        sed -i '/windowrulev2.*noscreenshare.*/s/^#//' "$CONFIG_FILE"
        rm -f "$STATE_FILE"
        CLASS="on"
    else
        sed -i '/windowrulev2.*noscreenshare.*/s/^/#/' "$CONFIG_FILE"
        touch "$STATE_FILE"
        CLASS="of"
    fi
}

На последнем шаге скрипта мы вызываем эту функцию, если была дана опция toggle, и возвращаем json-подобную строку для waybar. Полный скрипт:

#!/bin/bash

CONFIG_FILE="$HOME/.config/hypr/hyprland.conf"
STATE_FILE="$HOME/.config/hypr/.screenshare_rule_disabled"

toggle_rule() {
    if [ -f "$STATE_FILE" ]; then
        sed -i '/windowrulev2.*noscreenshare.*/s/^#//' "$CONFIG_FILE"
        rm -f "$STATE_FILE"
        CLASS="on"
    else
        sed -i '/windowrulev2.*noscreenshare.*/s/^/#/' "$CONFIG_FILE"
        touch "$STATE_FILE"
        CLASS="off"
    fi
}

case ${1} in
    "toggle")
        toggle_rule
        ;;
    *)
        if [ -f "$STATE_FILE" ]; then
            CLASS="off"
        else
            CLASS="on"
        fi
        ;;
esac

echo "{\"class\": \"$CLASS\", \"alt\": \"$CLASS\"}"

# Модуль Waybar

Чтобы использовать это удобно и мгновенно определять текущее состояние приватности, напишем модуль waybar:

"custom/noscreenshare": {
  "exec": "~/scripts/toggle_noscreenshare.sh",
  "on-click": "~/scripts/toggle_noscreenshare.sh toggle && pkill -SIGRTMIN+4 waybar",
  "signal": 4,
  "interval": "once",
  "return-type": "json",
  "format": "{icon}",
  "format-icons": {
    "off": "",
    "on": "󰗹"
  },
  "tooltip": false
},

Опишем, что здесь происходит. Чтобы получить значение для этого модуля, мы используем поле exec и указываем наш скрипт. Затем мы определяем, что произойдёт при клике на модуль в опции on-click: запуск скрипта с опцией toggle и отправка системного сигнала waybar. Это позволяет не перезагружать весь процесс waybar, а только этот модуль. Здесь очень важно синхронизировать значение signal и число в команде pkill -SIGRTMIN+4 waybar, и сделать это значение уникальным только для этого модуля waybar. Затем мы настраиваем однократный запуск нашего скрипта при старте waybar и определяем формат отображения (tooltip: false для отключения текста при наведении курсора). Я использую эти иконки nerdfonts для этого, но они не одинакового размера. Поэтому я тонко настраиваю отступы и добавляю некоторые стили:

#custom-noscreenshare {
  background: #1e1e2e;
  opacity: 0.7;
  padding: 0px 10px;
  margin: 5px 5px 3px 0px;
  border: 0px solid #181825;
  border-radius: 10px;
}

#custom-noscreenshare.on {
  font-size: 18px; 
  padding-right: 14px;
}

#custom-noscreenshare.off {
  font-size: 16px;
  padding-right: 16px;
  padding-left: 9px
}

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

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

# Находим значение деградации батареи

Сначала получим список всех устройств питания:

upower -e

Затем найдём батарею в этом списке:

upower -e | grep BAT

# For example:
# /org/freedesktop/UPower/devices/battery_BATT

Затем получим детальную информацию об этом устройстве:

upower -i $(upower -e | grep BAT)

Мы получим что-то вроде этого:

  native-path:          BATT
  vendor:               DESAY
  model:                BASE-BAT
  serial:               1
  power supply:         yes
  updated:              Fri Jul 11 11:37:00 2025 (7 seconds ago)
  has history:          yes
  has statistics:       yes
  battery
    present:             yes
    rechargeable:        yes
    state:               charging
    warning-level:       none
    energy:              25.514 Wh
    energy-empty:        0 Wh
    energy-full:         47.5052 Wh
    energy-full-design:  59.4247 Wh
    energy-rate:         11.1573 W
    voltage:             11.972 V
    charge-cycles:       650
    time to full:        2.0 hours
    percentage:          53%
    capacity:            79.9417%
    technology:          lithium-ion
    charge-start-threshold:        75%
    charge-end-threshold:          80%
    charge-threshold-supported:    yes
    icon-name:          'battery-good-charging-symbolic'
  History (charge):
    1752222927	53.000	charging
  History (rate):
    1752223020	11.157	charging
    1752222990	11.123	charging
    1752222987	11.192	charging
    1752222957	10.822	charging
    1752222927	10.857	charging

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

• energy-full-design — изначальный полный объём батареи
• energy-full — текущий объём батареи

Разница между этими параметрами и есть деградация батареи:

Теперь посчитаем этот показатель в процентах.

Сначала найдём эти параметры и разделим их:

upower -i $(upower -e | grep BAT) | awk '\
	/energy-full:/ {ef=$2}\
	/energy-full-design:/ {efd=$2}\
	END {print ef/efd}'

Затем посчитаем процентное значение:

echo "(1 - $(upower -i $(upower -e | grep BAT) | awk '\
        /energy-full:/ {ef=$2}\
        /energy-full-design:/ {efd=$2}\
        END {print ef/efd}')) * 100 + 0.5" \
	| bc

# Output example:
# 20.558200

На последнем шаге нам нужно округлить значение:

echo "(1 - $(upower -i $(upower -e | grep BAT) | awk '\
        /energy-full:/ {ef=$2}\
        /energy-full-design:/ {efd=$2}\
        END {print ef/efd}')) * 100 + 0.5" \
	| bc \
	| cut -d'.' -f1

# Output example:
# 20

# Модуль для Waybar

В моём конфиге waybar ~/.config/waybar/config.json я добавил два модуля в правую секцию, но вы можете сделать как вам удобно. В итоге я получил это:

Если вам нравятся мои обои, вы можете найти их и другие классные штуки в моём репозитории dotfiles на GitHub. Не забывайте: я люблю ваши звёзды!

Посмотрим:

{
  ...
  "modules-left": [...],
  "modules-center": [...],
  "modules-right": [
    "battery",
    "custom/battery-degradation",
	...
  ],
  ...

Первый модуль — стандартный battery, у меня он отлично работает на hyprland. Здесь мы определяем уровни хорошего, предупреждающего и критического уровня заряда, задаём nerd-иконки для разных состояний батареи:

"battery": {
  "states": {
    "good": 90,
    "warning": 25,
    "critical": 10
  },
  "format": "{icon} {capacity}%",
  "format-charging": " {capacity}%",
  "format-plugged": " {capacity}%",
  "format-icons": ["󰂎", "󰁺", "󰁻", "󰁼", "󰁽", "󰁾", "󰁿", "󰂀", "󰂁", "󰂂", "󰁹"],
  "tooltip": "{time}",
  "style": "{capacity < 10 ? 'color: red;' : 'color: normal;'}"
},

Второй модуль — тема сегодняшнего разговора:

"custom/battery-degradation": {
  "format": " {}%",
  "interval": "once",
  "exec": "~/scripts/battery-degradation.sh",
  "tooltip": false
},

Я поместил нашу команду в скрипт — так удобнее. Вы можете сделать так же, не забудьте добавить shebang #!/bin/bash и:

chmod +x ~/scripts/battery-degradation.sh

В модуле мы определяем формат с nerd-иконкой и процентом, отключаем подсказку и устанавливаем однократный запуск при старте waybar.

И завершаем эти модули CSS-стилем:

#battery,
#custom-battery-degradation {
  background: #1e1e2e;
  opacity: 0.7;
  padding: 0px 10px;
  margin: 3px 0px;
  margin-top: 5px;
  border: 0px solid #181825;
}

#battery {
  padding-right: 10px;
  border-radius: 10px 0px 0px 10px;
  min-width: 50px;
}

#custom-battery-degradation {
  border-radius: 0px 10px 10px 0px;
  margin-right: 5px;
  min-width: 35px;
}

#battery.critical {
  color: red;
}

Готово! В результате:

Имеем исходные векторы $v_1, v_2, \dots, v_n$, и нам нужно получить ортогональные векторы $u_1, u_2, \dots, u_n$. Общая схема метода: 0. Удаляем все нулевые векторы.

1. Берём первый вектор без изменений: $u_1 = v_1$.
2. Следующий вектор находим из $v_2$ и проекций на предыдущие векторы: $u_2 = v_2 - \text{Proj}_{u_1}{v_2}$.
3. Повторяем: $u_3 = v_3 - \text{Proj}_{u_1}{v_3} - \text{Proj}_{u_2}{v_3}$.
4. Продолжаем до вектора $u_n$: $u_n = v_n - \sum_{i=1}^{n-1}\text{Proj}_{u_i}{v_n}$. Напомним формулу проекции: $\text{Proj}_{u}{v} = \frac{\langle u, v\rangle}{||u||^2}u$. Для получения ортонормированного базиса нормируем векторы: $e_i = \frac{u_i}{||u_i||}$.

Рассмотрим пример: $v_1 = \begin{pmatrix}1 \\ 1\end{pmatrix}, \ v_2 = \begin{pmatrix}1 \\ 0\end{pmatrix}$. Сначала задаём $u_1 = v_1$, затем: $u_2 = v_2 - \text{Proj}_{u_1}{v_2} = \begin{pmatrix}1 \\ 0\end{pmatrix} - \begin{pmatrix}0.5 \\ 0.5\end{pmatrix} = \begin{pmatrix}0.5 \\ -0.5\end{pmatrix}$. В итоге получаем ортогональные векторы: $u_1 = \begin{pmatrix}1 \\ 0\end{pmatrix}$, $u_2 = \begin{pmatrix}0.5 \\ -0.5\end{pmatrix}$.

Пример: $f(x, y, z) = x^2 + y^2 - 4x - 4y + z^4 - 4z^2$. Градиент:

Приравниваем к нулю: $\nabla f = 0$, получаем систему:

Стационарные точки: $(2, 2, 0), \ (2, 2, \sqrt{2}), \ (2, 2, -\sqrt{2})$.

Для дальнейшего анализа используйте матрицу Гессе.

Для задач с ограничениями применяем метод множителей Лагранжа. Пример: $f(x, y) = x^2 + y^2$ при условии $x + y = 1$. Перепишем ограничение как $g(x, y) = x + y - 1 = 0$. Градиенты:

Уравнения Лагранжа в общем виде:

Для нашего случая:

Стационарная точка: $\left(\frac{1}{2}, \frac{1}{2} \right)$. Итог: без ограничений решаем $\nabla f = 0$, с ограничениями — метод Лагранжа.```

Как найти стационарные точки, читайте в статье: “Стационарные точки и метод Лагранжа”

Разберём на примере. Функция и стационарные точки:

Сначала построим матрицу Гессе. В общем виде она выглядит так:

Для нашей функции: $H = \begin{bmatrix}6x & -3 \\-3 & 6y\end{bmatrix}$. Подставим точки в матрицу и найдём собственные значения:

Применяем правила:

• Если все собственные значения положительны — локальный минимум
• Если все отрицательны — локальный максимум
• Если знаки разные — седловая точка

Результат: точка $A$ — седловая, точка $B$ — локальный минимум.```

Рассмотрим плоскость $\pi$ в пространстве $\mathbb{R}^3$, проходящую через начало координат. Возьмём два неколлинеарных вектора $u$ и $v$ из этой плоскости. Тогда любую точку $x \in \pi$ можно представить как: $x = \alpha u + \beta v$.

Хорошо, это означает, что мы можем определить плоскость $\pi$ как:

Обобщим понятие плоскости, проходящей через начало координат, на пространство произвольной размерности: Линейной оболочкой векторов $v_1, v_2, \dots, v_k \ \in \ \mathbb{R}^n$ называется множество векторов, представимых в виде суммы векторов $v_1, v_2, \dots, v_k$ с произвольными коэффициентами:

Выражение $\alpha_1 v_1 + \alpha_2 v_2 + \dots + \alpha_k v_k$ будем называть линейной комбинацией векторов $v_1, v_2, \dots, v_k$.

Сформулируем ключевое определение: линейным подпространством $\mathbb{R}^n$ называется линейная оболочка конечного числа векторов $v_1, v_2, \dots v_k \ \in \mathbb{R}^n$:

Понятия линейной оболочки и линейного подпространства эквивалентны. Любая линейная оболочка и любое подпространство содержат $0$, поскольку мы можем положить все коэффициенты $\alpha_1, \alpha_2, \dots, \alpha_k$ равными нулю.

Почему линейные подпространства важны? Вот пример:

Возьмём чёрно-белое цифровое фото размером 512 на 512 пикселей. В памяти компьютера это фото может быть представлено как $512 \times 512 = 262144$ чисел — каждое представляет интенсивность соответствующего пикселя от 0 (полностью чёрный) до 1 (полностью белый). Таким образом, фото может быть представлено вектором $x$ в пространстве размерности $d=262144$.

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

Мы говорили, что подпространство должно содержать ноль. Это означает, что прямая $y = 2x$ является подпространством, а прямая $y = x + 2$ — нет. Но многие свойства подпространств сохраняются, даже когда они не содержат ноль. Такие подпространства называются аффинными подпространствами. Аффинным подпространством $\mathbb{R}^n$ называется множество векторов $A$ вида $a + v$, где $a \in \mathbb{R}^n$ — фиксированный вектор, а вектор $v$ принадлежит линейному подпространству $V$. Пусть линейное подпространство $V$ — это линейная оболочка векторов $v_1, v_2, \dots, v_k$. Тогда аффинное подпространство — это множество:

Пусть $V$ — подпространство в $\mathbb{R}^n$. Размерностью этого подпространства называется минимальное количество векторов $v_1, v_2, \dots, v_k \in \mathbb{R}^n$, необходимых для определения подпространства $V$:

Размерность обозначается как: $\dim{(V)}$. Подумаем об этом. Например, у нас есть два неколлинеарных вектора $u, v \in \mathbb{R}^{100}$ и подпространство $V = \text{span}(u, v)$. Мы знаем, что каждый вектор $x \in V$ имеет 100 координат, но по определению подпространства: $x = \alpha u + \beta v$. Это означает, что любой вектор $x$ определяется всего двумя параметрами $\alpha$ и $\beta$, следовательно $\dim{(V)} = 2$. Для определения точки в $\mathbb{R}^n$ нам нужно $n$ параметров, для определения точки в $V$ нам нужно $\dim{(V)}$ параметров.

Существует подпространство, определяемое только одним вектором $0$: $V = \text{span}(0)$. Мы называем это подпространство тривиальным и считаем $\dim{(V)} = 0$.

Если у нас есть подпространство $V = \text{span}(v_1, v_2, \dots, v_k)$, может ли $\dim{(V)}$ быть меньше $k$? Да, если и только если один из векторов может быть выражен как линейная комбинация остальных векторов, например: $v_1 = \gamma_2v_2 + \gamma_3v_3 + \dots + \gamma_kv_k$.

Набор векторов называется линейно независимым, если равенство:

выполняется только при $\alpha_1 = \alpha_2 = \dots = \alpha_k = 0$. Если равенство может выполняться при ненулевых коэффициентах, векторы линейно зависимы.

Рассмотрим пространство $\mathbb{R}^n$ и заданный ненулевой вектор $w \in \mathbb{R}^n$. Тогда множество векторов $P$, перпендикулярных $w$:

является линейным подпространством с $\dim{(P)} = n - 1$

# Прямая на плоскости и в пространстве

Как задать прямую на плоскости? Конечно, через две точки. Но это не всё. Существуют ещё три метода:

1. Параметрическое уравнение
   Пусть прямая $l$ задана двумя точками $r_0 = (x_0; y_0)$ и $r_1 = (x_1;y_1)$. Заметим, что вектор $a = r_0 - r_1$ направлен вдоль $l$. Следовательно, любая точка на $l$ может быть определена как $r = r_0 + ta$, где $t \in \mathbb{R}$, а вся прямая $l$ задаётся при $-\infty < t < \infty$. Это выражение мы называем параметрическим уравнением:
   

   $$ l = \{r: r = r_o + at, \ t \in \mathbb{R} \} $$

2. Линейное уравнение
   Запишем параметрическое уравнение через координаты:
   

   $$ \begin{bmatrix}x \\ y\end{bmatrix} = \begin{bmatrix}x_0\\y_0\end{bmatrix} + \begin{bmatrix}t \cdot a_1 \\ t \cdot a_2\end{bmatrix} \Rightarrow \begin{cases}x = x_0 + ta_1 \\ y = y_0 + ta_2\end{cases} $$

   Предположим, что $a_1 \neq 0$ и $a_2 \neq 0$, и выразим $t$ из каждого уравнения: $\frac{x - x_0}{a_1} = \frac{y - y_0}{a_2} \Rightarrow a_2x - a_1y + (a_1y_0 - a_2x_0) = 0$. Поскольку $a_1, a_2, x_0, x_1$ — числа, это означает, что мы можем определить его как линейное уравнение:
   

   $$ Ax + By + C = 0 $$

   где $A = a_2$, $B = -a_1$, $C = (a_1y_0 - a_2x_0)$

3. Нормаль и точка
   Последний метод. Выберем произвольную точку на прямой $l$ с радиус-вектором $r_0$. Проведём вектор $n$ из точки $r_0$, перпендикулярный прямой $l$. Тогда для любой точки $r$ на прямой $l$ векторы $r - r_0$ и $n$ будут перпендикулярны. Перепишем это через скалярное произведение:
   

   $$ l = \{ r: \langle r - r_0;n\rangle = 0\} $$

   Разумеется, $r_0$ может быть любой точкой на прямой $l$, а нормальный вектор $n$ — любым вектором, перпендикулярным прямой $l$. Чтобы найти нормаль к прямой, нам нужен направляющий вектор $a = \begin{pmatrix}a_1 \\ a_2\end{pmatrix}$ из параметрического уравнения, тогда нормальный вектор будет: $n = \begin{bmatrix}-a_2\\ a_1\end{bmatrix}$ или $n’ = -n = \begin{bmatrix} a_2 \\ -a_1\end{bmatrix}$

Подведём итог и посмотрим на взаимосвязь между этими методами. Если прямая проходит через две точки $r_0 = (x_0; y_0)$ и $r_1 = (x_1; y_1)$, то её можно определить любым из трёх методов:

• Параметрическое уравнение:
  $$ r = r_0 + ta = \begin{bmatrix}x_0\\y_0\end{bmatrix} + t \cdot \begin{bmatrix}x_1 - x_0 \\ y_1 - y_0\end{bmatrix} = \begin{bmatrix}x_0\\y_0\end{bmatrix} + \begin{bmatrix}t \cdot a_1 \\ t \cdot a_2\end{bmatrix} $$
• Линейное уравнение:
  $$ Ax + By + C = \underbrace{a_2}_{A} x + \underbrace{(-a_1)}_{B} y + \underbrace{(a_1 y_0 - a_2 x_0)}_{C} = 0; $$
• Нормаль и точка:
  $$ \langle r - r_0; n\rangle = \left\langle \begin{bmatrix}x - x_0\\y - y_0\end{bmatrix}; \begin{bmatrix}a_1 \\ -a_1\end{bmatrix}\right\rangle = \left\langle\begin{bmatrix}x - x_0 \\ y - y_0\end{bmatrix}; \begin{bmatrix}A \\ B\end{bmatrix} \right\rangle $$

Как насчёт прямой в пространстве? Параметрическое уравнение не меняется, векторы становятся длиннее. Линейное уравнение изменится: теперь это не одно уравнение, а система двух уравнений:

Метод с нормалью и точкой не работает в пространстве!

Дополнение: рассмотрим расстояние от точки до прямой:

Мы можем определить, где находится точка относительно прямой: группа точек с одной стороны, для которых верно $Ax +By + C > 0$; группа с другой стороны, для которых верно $Ax +By + C < 0$.

# Плоскость в пространстве

Снова этот вопрос. Как задать плоскость в пространстве? Конечно, через три неколлинеарные точки, не лежащие на одной прямой. Коллинеарные точки лежат на одной прямой. И снова рассмотрим три метода:

1. Параметрическое уравнение:
   $$ \pi = \{r: r = r_0 + t_1v_1 + t_2v_2, \quad t_1, t_2 \in \mathbb{R}\} $$
2. Нормаль и точка: такой же, как для прямой: $\langle r - r_0; n\rangle = 0$
3. Линейное уравнение: начнём от нормали и точки и развернём его:
   $$ \langle r - r_0; n\rangle = 0 \quad \Rightarrow \quad \underbrace{n_1}_{A} x\ + \ \underbrace{n_2}_{B} y\ + \ \underbrace{n_3}_{C} z \ \underbrace{- \langle r_0 ;n\rangle}_{D} = 0. \ \Rightarrow \ Ax + By + Cz + D = 0 $$

Посмотрим на взаимосвязь между этими методами:

• Чтобы переписать параметрическое уравнение в нормаль и точку, нужно найти нормальный вектор из системы уравнений: $\begin{cases}\langle n; v_1\rangle = 0 \\ \langle n; v_2\rangle = 0\end{cases}$
• Чтобы переписать форму нормали и точки в линейное уравнение, мы можем использовать: $A = n_1$, $B = n_2$, $C = n_3$, $D = -\langle n ;r_0\rangle$
• Если у нас есть три точки, определяющие плоскость, мы можем перейти к параметрическому уравнению: $\begin{array}a v_1 = r_1 - r_0\\ v_2 = r_2 - r_0\end{array}$

Проекцией точки $P$ на плоскость $\pi$ называется точка $P_\pi \in \pi$, ближайшая к точке $P$: $P_\pi = \arg{\min{||P - X||}}, \ X \in \pi$. Тогда расстояние от точки $P$ до плоскости $\pi$ будет $d(P, \pi)$ — расстояние между точкой $P$ и её проекцией $P_\pi$:

Определение расположения точки относительно плоскости такое же, как для прямой.

# Базовые операции с векторами

1. Сумма векторов — сумма соответствующих координат: $$ v + w = \begin{pmatrix}v_1 \\ v_2 \\ \ldots \\ v_n \end{pmatrix} + \begin{pmatrix}w_1 \\ w_2 \\ \ldots \\ w_n \end{pmatrix} = \begin{pmatrix}v_1 + w_1 \\ v_2 + w_2 \\ \ldots \\ v_n + w_n \end{pmatrix} $$ Складывать можно только векторы одинаковой размерности.
2. Умножение вектора на скаляр: $$ \lambda v = \lambda \cdot \begin{pmatrix}v_1 \\ v_2 \\ \ldots \\ v_n \end{pmatrix} = \begin{pmatrix}\lambda v_1 \\ \lambda v_2 \\ \ldots \\ \lambda v_n \end{pmatrix} $$
3. Разность векторов — сумма векторов, где один умножен на скаляр $-1$.
4. Скалярное произведение векторов: $$ x \cdot y = \langle x;y\rangle = x_1 y_1 + x_2 y_2 + \ldots + x_n y_n = \sum \limits_{i = 1}^{n}x_i y_i $$ Свойства скалярного произведения:

• Коммутативность: $\langle v; w\rangle = \langle w; v\rangle$
• Дистрибутивность: $\langle x; (v + w)\rangle = \langle x; v\rangle + \langle x; w \rangle$
• Совместимость со скалярным умножением: $\langle v; \lambda w\rangle = \lambda \langle v;w\rangle$
• Если скалярное произведение равно нулю, векторы называются ортогональными

# Геометрическая интерпретация

В геометрии вектор — направленный отрезок.

Длина вектора вычисляется по теореме Пифагора: ФОРМУЛА_4. Вектор единичной длины называется единичным вектором. Ненормированный вектор можно нормировать умножением на $\lambda = \frac{1}{||v||}$. Расстояние между векторами: $d = ||v - w|| = \sqrt{\sum\limits_{i = 1}^{n}{(v_i - w_i)^2}}$ Угол между векторами:

Проекция вектора $u$ на $w$:

Неравенство Коши-Буняковского:

Неравенство треугольника: $||v + w|| \leqslant ||v|| + ||w||$
Для ортогональных векторов выполняется теорема Пифагора: $||a + b||^2 = ||a||^2 + ||b||^2$.```

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

Автоматизируем этот процесс. Начнём с подключения. Обычно это выглядит так:

ssh root@192.168.0.1 -i ~/.ssh/id_rsa25519

Нам нужны три компонента для доступа:

1. IP-адрес сервера
2. Имя пользователя
3. Приватный SSH-ключ Для “чистого” развертывания автоматизируем все шаги. Чтобы GitHub Actions мог подключиться к серверу, передадим данные через секреты.

В репозитории GitHub зайдите в Settings → Security → Secrets and Variables → Actions. Добавьте три секрета: SSH_USER, SSH_HOST, SSH_KEY. Не забудьте добавить публичный ключ в ~/.ssh/authorized_keys на сервере. Первый шаг завершён.

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

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Сгенерируйте SSH-ключи на сервере:

ssh-keygen -C github -t ed25519

Добавьте публичный ключ в Deploy keys в настройках репозитория GitHub. Создайте секрет SSH_PROJECT_PATH для пути к проекту.

Финальный шаг — GitHub Actions. Создайте файл .gitub/workflows/deploy.yaml (имя не важно):

name: Deploy
on:
  push:
    branches:
      - main
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Pull repo
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd ${{ secrets.SSH_PROJECT_PATH }}
            git pull origin main --rebase
      - name: Compose down
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd ${{ secrets.SSH_PROJECT_PATH }}
            docker compose down
      - name: Compose up
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd ${{ secrets.SSH_PROJECT_PATH }}
            docker compose up -d

В этом примере я использую Docker для перезапуска сервисов. Выберите свой подход!```

docker system prune

# 1. Очистка пакетов

Советы для Arch-систем:

Поиск самых тяжёлых пакетов (топ-20):

pacman -Qi | awk '/^Name/{name=$3} /^Installed Size/{print $4 $5, name}' | sort -hr | head -n 20

Поиск неиспользуемых зависимостей:

pacman -Qdtq

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

Удаление неиспользуемых зависимостей (если уверены):

sudo pacman -Rns $(pacman -Qdtq)

Поиск забытых пакетов (топ-20 давно неиспользуемых):

expac --timefmt='%Y-%m-%d %T' '%l %n' | sort | head -n 20

Очистка кэша pacman (сохраняет текущую и предыдущую версии пакетов):

sudo paccache -r

Полная очистка кэша (оставляет только установленные версии):

sudo paccache -r -k 0

Помните: после этого вы не сможете откатить пакеты без интернета.

# 2. Очистка файлов

Топ-15 самых тяжёлых директорий в домашнем каталоге:

du -h ~/ --max-depth=1 | sort -hr | head -n 15

Топ-20 самых тяжёлых файлов в домашнем каталоге:

find ~/ -type f -exec du -Sh {} + | sort -rh | head -n 20

Этих двух команд обычно достаточно для поиска точек очистки. Можно перейти в тяжёлую директорию и повторить команду внутри неё.```