Contributing¶

Спасибо за интерес к проекту aioyookassa! Ваш вклад поможет сделать библиотеку лучше.

Как внести вклад¶

Сообщение об ошибках¶

Перед созданием issue: 1. Проверьте, что ошибка не была уже сообщена 2. Убедитесь, что используете последнюю версию 3. Проверьте документацию

Создание issue: 1. Перейдите в GitHub Issues 2. Выберите шаблон “Bug Report” 3. Заполните все необходимые поля

Шаблон для бага:

**Описание бага**
Краткое описание проблемы.

**Шаги для воспроизведения**
1. Перейдите к '...'
2. Нажмите на '...'
3. Прокрутите до '...'
4. Увидите ошибку

**Ожидаемое поведение**
Что должно было произойти.

**Фактическое поведение**
Что произошло на самом деле.

**Скриншоты**
Если применимо, добавьте скриншоты.

**Окружение:**
- OS: [e.g. Ubuntu 20.04]
- Python: [e.g. 3.9.7]
- aioyookassa: [e.g. 0.1.6]

**Дополнительный контекст**
Любая другая информация о проблеме.

Предложения функций¶

Создание feature request: 1. Перейдите в GitHub Issues 2. Выберите шаблон “Feature Request” 3. Опишите предлагаемую функцию

Шаблон для предложения:

**Описание функции**
Краткое описание предлагаемой функции.

**Проблема, которую решает**
Какая проблема решается этой функцией?

**Предлагаемое решение**
Опишите, как должна работать функция.

**Альтернативы**
Рассматривали ли вы альтернативные решения?

**Дополнительный контекст**
Любая другая информация о предложении.

Разработка¶

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

Форкните репозиторий: - Перейдите на GitHub - Нажмите “Fork”
Клонируйте форк: .. code-block:: bash

git clone https://github.com/your-username/aioyookassa.git cd aioyookassa
Установите зависимости: .. code-block:: bash

# Используя Poetry (рекомендуется) poetry install

# Или используя pip pip install -e “.[dev]”
Установите pre-commit хуки: .. code-block:: bash

pre-commit install

Структура проекта¶

aioyookassa/
├── aioyookassa/           # Основной код библиотеки
│   ├── core/             # Ядро библиотеки
│   ├── types/            # Pydantic модели
│   ├── exceptions/       # Исключения
│   └── __init__.py
├── tests/                # Тесты
├── docs/                 # Документация
├── examples/             # Примеры использования
├── pyproject.toml        # Конфигурация Poetry
├── pytest.ini           # Конфигурация pytest
└── README.md

Создание Pull Request¶

Создайте ветку: .. code-block:: bash

git checkout -b feature/your-feature-name # или git checkout -b fix/your-bug-fix
Внесите изменения: - Реализуйте функцию или исправьте баг - Добавьте тесты - Обновите документацию
Запустите тесты: .. code-block:: bash

# Все тесты poetry run pytest

# С покрытием poetry run pytest –cov=aioyookassa –cov-report=html

# Конкретный тест poetry run pytest tests/core/test_client.py::TestYooKassa::test_yookassa_initialization
Проверьте код: .. code-block:: bash

# Форматирование poetry run black aioyookassa tests

# Линтинг poetry run flake8 aioyookassa tests

# Типы poetry run mypy aioyookassa
Закоммитьте изменения: .. code-block:: bash

git add . git commit -m “feat: add new feature” # или git commit -m “fix: resolve bug in payment processing”
Отправьте PR: .. code-block:: bash

git push origin feature/your-feature-name

Стандарты кода¶

Форматирование¶

Используем Black для форматирования:

poetry run black aioyookassa tests

Настройки Black: - Длина строки: 88 символов - Кавычки: двойные - Отступы: 4 пробела

Линтинг¶

Используем Flake8 для проверки стиля:

poetry run flake8 aioyookassa tests

Настройки Flake8: - Максимальная длина строки: 88 - Максимальная сложность: 10 - Игнорируем: E203, W503

Типизация¶

Используем mypy для проверки типов:

poetry run mypy aioyookassa

Требования: - Все публичные функции должны иметь аннотации типов - Используйте typing модуль для сложных типов - Избегайте Any где это возможно

Документация¶

Docstrings: Используйте Google стиль:

def create_payment(self, amount: PaymentAmount, description: str) -> Payment:
    """
    Создание нового платежа.

    Args:
        amount: Сумма платежа
        description: Описание платежа

    Returns:
        Созданный платеж

    Raises:
        APIError: При ошибке API
        InvalidRequestError: При неверном запросе

    Example:
        >>> from aioyookassa.types.enum import Currency
        >>> payment = await client.payments.create_payment(
        ...     amount=PaymentAmount(value=100, currency=Currency.RUB),
        ...     description="Test payment"
        ... )
    """
    pass

Комментарии: - Объясняйте сложную логику - Избегайте очевидных комментариев - Используйте русский язык для комментариев

Тестирование¶

Структура тестов¶

tests/
├── conftest.py              # Общие фикстуры
├── core/                    # Тесты core модулей
├── types/                   # Тесты типов данных
├── exceptions/              # Тесты исключений
└── fixtures/                # Тестовые данные

Покрытие кода¶

Требования: - Минимальное покрытие: 90% - Новые функции: 100% покрытие - Критический код: 100% покрытие

Проверка покрытия: .. code-block:: bash

poetry run pytest –cov=aioyookassa –cov-report=html –cov-report=term-missing

Исключения из покрытия: - if __name__ == “__main__”: блоки - Исключения в тестах - Документационные примеры

Типы тестов¶

Unit тесты: - Тестируют отдельные функции/методы - Изолированы от внешних зависимостей - Быстрые (< 1ms)

Integration тесты: - Тестируют взаимодействие компонентов - Могут использовать моки - Средняя скорость (< 100ms)

Пример unit теста: .. code-block:: python

import pytest from aioyookassa.types.payment import PaymentAmount from aioyookassa.types.enum import Currency

def test_payment_amount_creation():
“””Test PaymentAmount creation with valid data.””” amount = PaymentAmount(value=100.50, currency=Currency.RUB)

assert amount.value == 100.50 assert amount.currency == Currency.RUB

Пример integration теста: .. code-block:: python

import pytest from unittest.mock import AsyncMock, patch from aioyookassa import YooKassa

@pytest.mark.asyncio async def test_create_payment_integration():

“””Test payment creation with mocked API.””” with patch(‘aioyookassa.core.api.payments.PaymentsAPI.create_payment’) as mock_create:

mock_create.return_value = AsyncMock() mock_create.return_value.id = “test_payment_id”

from aioyookassa.types.enum import Currency

client = YooKassa(api_key=”test”, shop_id=12345) payment = await client.payments.create_payment(

amount=PaymentAmount(value=100, currency=Currency.RUB), description=”Test”

)

assert payment.id == “test_payment_id” mock_create.assert_called_once()

Фикстуры¶

Общие фикстуры в conftest.py: .. code-block:: python

import pytest from aioyookassa import YooKassa from aioyookassa.types.payment import PaymentAmount

@pytest.fixture def client():

“””Test client fixture.””” return YooKassa(api_key=”test_key”, shop_id=12345)

@pytest.fixture def sample_payment_data():

“””Sample payment data for tests.””” return {

“id”: “test_payment_id”, “status”: “succeeded”, “amount”: {“value”: “100.00”, “currency”: “RUB”}, “description”: “Test payment”

}

Релизный процесс¶

Версионирование¶

Используем Semantic Versioning:

MAJOR: Несовместимые изменения API
MINOR: Новая функциональность (обратно совместимая)
PATCH: Исправления багов (обратно совместимые)

Примеры: - 1.0.0 → 1.0.1 (исправление бага) - 1.0.1 → 1.1.0 (новая функция) - 1.1.0 → 2.0.0 (breaking change)

Подготовка релиза¶

Обновите версию: - В pyproject.toml - В docs/conf.py - В aioyookassa/__init__.py
Обновите changelog: - Добавьте записи в docs/changelog.rst - Опишите все изменения
Запустите тесты: .. code-block:: bash

poetry run pytest poetry run black aioyookassa tests poetry run flake8 aioyookassa tests poetry run mypy aioyookassa
Создайте тег: .. code-block:: bash

git tag v0.1.7 git push origin v0.1.7
Создайте релиз на GitHub: - Перейдите в Releases - Нажмите “Create a new release” - Выберите тег - Заполните описание

Публикация¶

PyPI: .. code-block:: bash

poetry build poetry publish

GitHub: - Автоматически через GitHub Actions - При создании тега

Кодекс поведения¶

Наши обязательства¶

Мы обязуемся сделать участие в нашем проекте комфортным для всех, независимо от:

Возраста
Размера тела
Инвалидности
Этнической принадлежности
Половых характеристик
Гендерной идентичности и выражения
Уровня опыта
Образования
Социально-экономического статуса
Национальности
Внешности
Расы
Религии
Сексуальной идентичности и ориентации

Наши стандарты¶

Примеры поведения, которое способствует созданию позитивной среды:

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

Примеры неприемлемого поведения:

Использование сексуализированного языка или образов
Троллинг, оскорбительные/уничижительные комментарии
Публичные или частные домогательства
Публикация личной информации без разрешения
Другое поведение, которое может считаться неуместным в профессиональной среде

Применение¶

Случаи оскорбительного, домогательского или иного неприемлемого поведения могут быть сообщены, обратившись к ответственному за проект по адресу masaasibaata@telegram.

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

Контакты¶

Основной разработчик: - Telegram: @masaasibaata

Поддержка проекта: - Tribute

Репозиторий: - GitHub

Документация: - Read the Docs

Пакет: - PyPI