7.4 KiB
Как внести свой вклад
Внесение своего вклада в этот проект ничем не отличается внесения в других open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых стоит знать и помнить.
Все необходимые пакеты для разработки есть в requirements-dev.txt
.
Установить их можно с помощью следующей команды:
pip install -r requirements-dev.txt
Основные типы вклада:
- добавление новых полей к существующим классам;
- добавление новых классов;
- установка опциональности какого-то поля;
- добавление нового метода в
Client
(новый запрос на API); - добавление примера использование в папку examples.
Ваш вклад может быть более грандиозным. Так, например, можно написать
интеграционные тесты для класса Client
и всех методов-сокращений в моделях.
Написать тесты для класса запросов. Написать генератор кода для быстрого добавления
новых полей.
Pull Requests
PR'ы должны быть сделаны в dev
ветку. Определённого шаблона оформления
нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым
словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все
проверки GitHub Actions (тесты, проверка стиля кода).
Тесты
Для тестирования используется pytest
. На данный момент отсутствуют
интеграционные тесты. Поэтому всё что сейчас
требутеся — это юнит тесты классов-обёрток и их дополнительных методов
(если имеются), которые не являются сокращениями для методов клиента.
Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию только обязательных полей, десериализацию всех полей, сравнение объектов модели, десериализацию пустого словаря. По необходимости десериализацию списка объектов.
Примеры доступны в папке tests.
Документация
Для документации используется Sphinx
. Документация ведется в google style.
К каждому классу и методу должна быть написана документация на русском языке.
Типы каждого значения. По возможности описано предназначение поля. Если
невозможно логически понять из названия — ставим TODO
. Обязательно отмечаем
какие поля являются опциональными. Пишем заметки по известным значениям полей,
чтобы из контекста догадываться о предназначении.
Если добавлен новый файл, то не забудьте сгенерировать .rst
файл
выполнив команду make gen
в папке docs
и добавить его в GIT.
Чтобы собрать документацию выполните make html
в папке docs
.
Форматирование кода (стиль написания)
В проекте используется black
. Не забывайте перед публикацией
отформатировать код и проверить его на работоспособность.
Используются одинарные кавычки. Запускайте black
с конфигом из основной директории:
black --config=black.toml yandex_music
Создание новых моделей
Исходите из логики при помещении модели в определённый пакет.
Добавьте свою модель для короткого импорта в одну из секций __init__.py
файла
и пропишите название в __all__
. Обязательно следите за тем, какие поля
присутствуют всегда, а какие нет. По возможности минимизируйте количество
опциональных полей. Не забывайте перечислить поля, по которым можно отличить
один объект от другого в _id_attrs
(метод __post_init__
). Экземпляр класса
Client
передаётся в каждую модель для возможности написания методов-сокращений.
При наличии дополнительных методов у модели не забудьте создать асинхронную версию
метода добавив в название суффикс _async
. Кроме этого, если у вашей модели
есть метод, например, download_async()
, то такому методу следует создать
camel case псевдоним (downloadAsync()
). Для создания псевдонимов существует
генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер:
# camelCase псевдонимы
(пример)
После чего запустить генератор:
python generate_camel_case_aliases.py
Создание новых методов клиента
Если ваша задача включает добавление нового API метода, то не забудьте сгенерировать асинхронную версию клиента. Сделать это можно следующей командой:
python generate_async_version.py
Ни в коем случае не редактируйте файл client_async.py
и request_async.py
руками!
Для разработчиков на macOS и Linux
Для упрощения жизни в корне проекта существует Makefile.
Команда
make all
Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную версию клиента, сгенерирует camel case псевдонимы.