Merge pull request #575 from MarshalX/dev

2.1.0

.github/workflows/pytest_full.yml

@@ -16,7 +16,7 @@ jobs:
     strategy:
       matrix:
         os: [macos-latest, ubuntu-latest, windows-latest]
-        python-version: [3.7, 3.8, 3.9, "3.10"]
+        python-version: [3.7, 3.8, 3.9, "3.10", "3.11"]
 
     steps:
       - name: Checkout repository.

.readthedocs.yaml

@@ -3,9 +3,16 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+
 sphinx:
   configuration: docs/source/conf.py
+
 python:
-  version: "3.7"
   install:
     - requirements: docs/requirements.txt
+    - requirements: requirements-dev.txt

CONTRIBUTING.md

@@ -1,73 +1,97 @@
 # Как внести свой вклад
 
-Внесение своего вклада в этот проект ничем не отличается внесения в других 
-open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых
-стоит знать и помнить.
+Внесение своего вклада в этот проект ничем не отличается внесения в других open source проекты на GitHub'e, но есть несколько ключевых моментов, о которых стоит знать и помнить.
 
-Все необходимые пакеты для разработки есть в `requirements-dev.txt`.
-Установить их можно с помощью следующей команды:
-```
+Все необходимые пакеты для разработки есть в `requirements-dev.txt`. Установить их можно с помощью следующей команды:
+```shell
 pip install -r requirements-dev.txt
 ```
 
 Основные типы вклада:
-- добавление новых полей к существующим классам;
-- добавление новых классов;
+- добавление новых полей к существующим моделям;
+- добавление новых моделей;
 - установка опциональности какого-то поля;
 - добавление нового метода в `Client` (новый запрос на API);
+- добавление нового метода-сокращения в модель;
 - добавление примера использование в папку [examples](examples).
 
-Ваш вклад может быть более грандиозным. Так, например, можно написать 
-интеграционные тесты для класса `Client` и всех методов-сокращений в моделях.
-Написать тесты для класса запросов. Написать генератор кода для быстрого добавления
-новых полей.
+Ваш вклад может быть более грандиозным. Так, например, можно написать интеграционные тесты для класса `Client` и всех методов-сокращений в моделях. Написать тесты для класса запросов. Написать генератор кода для быстрого добавления новых полей.
 
 ## Pull Requests
 
-PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления
-нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым
-словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все
-проверки GitHub Actions (тесты, проверка стиля кода).
+PR'ы должны быть сделаны в `dev` ветку. Определённого шаблона оформления нет. Если это закрывает какое-то issue, то стоит сослаться на него с ключевым словом "close". Например, "close #123". Обращайте внимание прошёл ли Ваш PR все проверки GitHub Actions (тесты, проверка стиля кода).
 
 ## Тесты
 
-Для тестирования используется `pytest`. На данный момент отсутствуют 
-интеграционные тесты. Поэтому всё что сейчас 
-требутеся — это юнит тесты классов-обёрток и их дополнительных методов 
-(если имеются), которые не являются сокращениями для методов клиента.
+Для тестирования используется `pytest`. На данный момент отсутствуют интеграционные тесты. Поэтому всё что сейчас требуется — это модульные тесты классов-обёрток и их дополнительных методов (если имеются), которые не являются сокращениями для методов клиента.
 
-Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию 
-только обязательных полей, десериализацию всех полей, сравнение
-объектов модели, десериализацию пустого словаря. По необходимости десериализацию
-списка объектов.
+Тесты модели должны покрывать 5 основных вещей: конструктор, десериализацию только обязательных полей, десериализацию всех полей, сравнение объектов модели, десериализацию пустого словаря. По необходимости десериализацию списка объектов.
 
 Примеры доступны в папке [tests](tests).
 
 ## Документация
 
-Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html).
-К каждому классу и методу должна быть написана документация на русском языке. 
-Типы каждого значения. По возможности описано предназначение поля. Если 
-невозможно логически понять из названия — ставим `TODO`. Обязательно отмечаем 
-какие поля являются опциональными. Пишем заметки по известным значениям полей, 
-чтобы из контекста догадываться о предназначении.
+Для документации используется `Sphinx`. Документация ведется в [google style](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). К каждому классу и методу должна быть написана документация на русском языке. Указаны типы каждого значения. По возможности описано предназначение поля. Если невозможно логически понять из названия или данных — ставим `TODO`. Обязательно отмечаем какие поля являются опциональными. Пишем заметки по известным значениям полей, чтобы из контекста догадываться о предназначении.
 
-Если добавлен новый файл, то не забудьте сгенерировать `.rst` файл
-выполнив команду `make gen` в папке `docs` и добавить его в GIT.
+Если добавлен новый класс или функция, то не забудьте сгенерировать `.rst` файл выполнив команду `make gen` в папке `docs` и добавить его в GIT.
 
-Чтобы собрать документацию выполните `make html` в папке `docs`.
+Чтобы собрать документацию выполните `make html` в папке `docs`. Для отчистки используйте `make clean`.
 
 ## Форматирование кода (стиль написания)
 
-В проекте используется `black`. Не забывайте перед публикацией
-отформатировать код и проверить его на работоспособность.
+В проекте используется `black`. Не забывайте перед публикацией отформатировать код и проверить его на работоспособность. Используются одинарные кавычки. Запускайте `black` с конфигом из основной директории:
+
+```shell
+black --config=black.toml yandex_music
+```
+
+или
+
+```shell
+make black
+```
 
 ## Создание новых моделей
 
-Исходите из логики при помещении модели в определённый пакет.
-Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла
-и пропишите название в `__all__`. Обязательно следите за тем, какие поля
-присутствуют всегда, а какие нет. По возможности минимизируйте количество
-опциональных полей. Не забывайте перечислить поля, по которым можно отличить
-один объект от другого в `_id_attrs` (метод `__post_init__`). Экземпляр класса 
-`Client` передаётся в каждую модель для возможности написания методов-сокращений. 
+Исходите из логики при помещении модели в определённый пакет. Добавьте свою модель для короткого импорта в одну из секций `__init__.py` файла и пропишите название в `__all__`. 
+
+Обязательно следите за тем, какие поля присутствуют всегда, а какие нет. По возможности минимизируйте количество опциональных полей. 
+
+Не забывайте перечислить поля, по которым можно отличить один объект от другого в `_id_attrs` (метод `__post_init__`).
+
+Экземпляр класса `Client` передаётся в каждую модель для возможности написания методов-сокращений. При наличии дополнительных методов у модели не забудьте создать асинхронную версию метода добавив в название суффикс `_async`. 
+
+Кроме этого, если у вашей модели есть метод, например, `download_async()`, то такому методу следует создать camel case псевдоним (`downloadAsync()`). Для создания псевдонимов существует генератор. Всё что вам надо сделать это поместить в конце файла с моделью маркер:
+
+```
+# camelCase псевдонимы
+```
+([пример](https://github.com/MarshalX/yandex-music-api/blob/a30082f4929e56381c870cb03103777ae29bcc6b/yandex_music/tracks_list.py#L80))
+
+После чего запустить генератор:
+```shell
+python generate_camel_case_aliases.py
+```
+
+### Создание новых методов клиента
+
+Если ваша задача включает добавление нового API метода, то не забудьте сгенерировать асинхронную версию клиента. Сделать это можно следующей командой:
+
+```shell
+python generate_async_version.py
+```
+
+Ни в коем случае не редактируйте файл `client_async.py` и `request_async.py` руками!
+
+## Makefile
+
+_Используйте WSL если вы на Windows._
+
+Для упрощения жизни в корне проекта существует [Makefile](Makefile). 
+
+Команда
+```shell
+make all
+```
+
+Выполнит за вас black для основного модуля и тестов, сгенерирует асинхронную версию клиента, сгенерирует camel case псевдонимы.

MANIFEST.in

@@ -1 +1 @@
-include LICENSE CHANGES.rst
+include LICENSE CHANGES.md

Makefile

@@ -0,0 +1,31 @@
+# makefile for Yandex Music project
+
+black:
+	black --config=black.toml yandex_music
+
+black_test:
+	black --config=black.toml tests
+
+gen_async:
+	python generate_async_version.py
+
+gen_alias:
+	python generate_camel_case_aliases.py
+
+gen:
+	make gen_async && make gen_alias
+
+b:
+	make black
+
+bt:
+	make black_test
+
+g:
+	make gen
+
+all:
+	make g && make b && make bt
+
+a:
+	make all