Включены правила pydocstyle (#632)

MarshalX · Dec 24, 2023 · 210f375 · 210f375
1 parent 8aafa15
commit 210f375
Show file tree

Hide file tree

Showing 21 changed files with 393 additions and 267 deletions.
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 [![Поддерживаемые Python версии](https://img.shields.io/badge/python-3.7+-blue.svg)](https://pypi.org/project/yandex-music/)
 [![Покрытие кода тестами](https://codecov.io/gh/MarshalX/yandex-music-api/branch/main/graph/badge.svg)](https://codecov.io/gh/MarshalX/yandex-music-api)
 [![Качество кода](https://api.codacy.com/project/badge/Grade/27011a5a8d9f4b278d1bfe2fe8725fed)](https://app.codacy.com/gh/MarshalX/yandex-music-api)
-[![Статус тестов](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/MarshalX/yandex-music-api/actions/workflows/pytest_full.yml)
+[![Статус тестов](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml/badge.svg)](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml)
 [![Статус документации](https://readthedocs.org/projects/yandex-music/badge/?version=latest)](https://yandex-music.readthedocs.io/en/latest/?badge=latest)
 [![Лицензия LGPLv3](https://img.shields.io/badge/license-LGPLv3-lightgrey.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
 

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,15 +1,15 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# This file only contains a selection of the most common options. For a full
-# list see the documentation:
-# http://www.sphinx-doc.org/en/master/config
+"""Configuration file for the Sphinx documentation builder.
 
-# -- Path setup --------------------------------------------------------------
+This file only contains a selection of the most common options. For a full
+list see the documentation:
+http://www.sphinx-doc.org/en/master/config
 
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+-- Path setup --------------------------------------------------------------
+
+If extensions (or modules to document with autodoc) are in another directory,
+add these directories to sys.path here. If the directory is relative to the
+documentation root, use os.path.abspath to make it absolute, like shown here.
+"""
 import os
 import sys
 

diff --git a/docs/source/readme.md b/docs/source/readme.md
@@ -11,7 +11,7 @@
 [![Поддерживаемые Python версии](https://img.shields.io/badge/python-3.7+-blue.svg)](https://pypi.org/project/yandex-music/)
 [![Покрытие кода тестами](https://codecov.io/gh/MarshalX/yandex-music-api/branch/main/graph/badge.svg)](https://codecov.io/gh/MarshalX/yandex-music-api)
 [![Качество кода](https://api.codacy.com/project/badge/Grade/27011a5a8d9f4b278d1bfe2fe8725fed)](https://app.codacy.com/gh/MarshalX/yandex-music-api)
-[![Статус тестов](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/MarshalX/yandex-music-api/actions/workflows/pytest_full.yml)
+[![Статус тестов](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml/badge.svg)](https://github.com/MarshalX/yandex-music-api/actions/workflows/test.yml)
 [![Статус документации](https://readthedocs.org/projects/yandex-music/badge/?version=latest)](https://yandex-music.readthedocs.io/en/latest/?badge=latest)
 [![Лицензия LGPLv3](https://img.shields.io/badge/license-LGPLv3-lightgrey.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)
 

diff --git a/generate_async_version.py b/generate_async_version.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+"""Generate async version of client.py and request.py."""
 import subprocess
 
 DISCLAIMER = "# THIS IS AUTO GENERATED COPY OF client.py. DON'T EDIT IN BY HANDS #"
@@ -8,6 +9,7 @@
 
 
 def gen_request(output_request_filename: str) -> None:
+    """Generate async version of request.py."""
     with open('yandex_music/utils/request.py', 'r', encoding='UTF-8') as f:
         code = f.read()
 
@@ -48,6 +50,7 @@ def gen_request(output_request_filename: str) -> None:
 
 
 def gen_client(output_client_filename: str) -> None:
+    """Generate async version of client.py."""
     with open('yandex_music/client.py', 'r', encoding='UTF-8') as f:
         code = f.read()
 

diff --git a/generate_camel_case_aliases.py b/generate_camel_case_aliases.py
@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+"""Generate camel case aliases for snake case functions."""
 import ast
 import os
 
@@ -28,6 +29,7 @@ def _validate_function_name(function_name: str) -> bool:
 
 
 def convert_snake_case_to_camel_case(string: str) -> str:
+    """Convert snake case string to camel case string."""
     camel_case = ''.join(word.title() for word in string.split('_'))
     return camel_case[0].lower() + camel_case[1:]
 
@@ -86,6 +88,7 @@ def _process_file(file: str) -> None:
 
 
 def main() -> None:
+    """Generate camel case aliases for snake case functions."""
     for root, _, files in os.walk(SOURCE_FOLDER):
         for file in files:
             if file.endswith('.py') and file != '__init__.py':

diff --git a/ruff.toml b/ruff.toml
@@ -3,6 +3,7 @@ extend-select = [
     "W",  # pycodestyle warnings
     "F",  # Pyflakes
     "I",  # isort
+    "D",  # pydocstyle
     "C90",  # flake8-comprehensions
     "B",  # flake8-bugbear
     "Q",  # flake8-quotes
@@ -29,22 +30,31 @@ extend-select = [
 line-length = 120
 target-version = "py37"
 ignore = [
+    "ISC001", # conftlics with format
     "PGH004", # use specific rule code with noqa; works bad with JetBrains IDE Warnings
     "ANN002", # Missing type annotation for `*args`
     "ANN003", # Missing type annotation for `**kwargs`
     "ANN101", # Missing type annotation for `self` in method
     "ANN102", # Missing type annotation for `cls` in classmethod
+    "D203", # we are not using blank line before class
+    "D213", # we are using first line for summary
+    "D406", "D407", # we are using google style docstring
 ]
 
 [per-file-ignores]
-"examples/*.py" = ["T201", "S311", "ERA001", "INP001", "S106", "BLE001", "S603", "ANN"]
-"docs/source/conf.py" = ["INP001"]
-"tests/*.py" = ["S101", "ANN"] # Use of assert
-"tests/__init__.py" = ["F401"] # Unused import
+"yandex_music/*.py" = [
+    "D105", "D104", "D100", "D107", "D103", "D415", # missing docstring
+    "D400", # first line should end with a period. TODO(MarshalX): We are using strange docsting style for methods-shortcuts
+]
 "yandex_music/__init__.py" = ["I001"] # Import sort
 "yandex_music/client*.py" = ["T201"] # print
+"yandex_music/utils/request*.py" = ["ANN"] # TODO(MarshalX): annotate and remove this ignore
+"tests/*.py" = ["S101", "ANN", "D"]
+"tests/__init__.py" = ["F401"] # Unused import
 "test.py" = ["S101", "ERA001", "T201", "E501", "F401", "F841"]
-"yandex_music/utils/request*.py" = ["ANN"]  # TODO(MarshalX): annotate and remove this ignore
+"docs/source/conf.py" = ["INP001"]
+"examples/*.py" = ["T201", "S311", "ERA001", "INP001", "S106", "BLE001", "S603", "ANN", "D"]
+
 
 [flake8-quotes]
 docstring-quotes = "double"

diff --git a/setup.py b/setup.py
@@ -1,3 +1,4 @@
+"""Setup script for yandex-music-api."""
 import re
 import sys
 
@@ -6,7 +7,10 @@
 
 
 class PyTest(test):
+    """PyTest test runner."""
+
     def run_tests(self) -> None:
+        """Run tests."""
         import pytest
 
         sys.exit(pytest.main(['tests']))

diff --git a/yandex_music/album/album.py b/yandex_music/album/album.py
@@ -281,7 +281,6 @@ def artists_name(self) -> List[str]:
         Returns:
               :obj:`list` из :obj:`str`: Имена исполнителей.
         """
-
         return [i.name for i in self.artists]
 
     @classmethod

diff --git a/yandex_music/album/deprecation.py b/yandex_music/album/deprecation.py
@@ -33,6 +33,7 @@ def de_json(cls, data: dict, client: 'Client') -> Optional['Deprecation']:
         Args:
             data (:obj:`dict`): Поля и значения десериализуемого объекта.
             client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music.
+
         Returns:
             :obj:`yandex_music.Deprecation`: TODO.
         """

diff --git a/yandex_music/album/label.py b/yandex_music/album/label.py
@@ -31,6 +31,7 @@ def de_json(cls, data: dict, client: 'Client') -> Optional['Label']:
         Args:
             data (:obj:`dict`): Поля и значения десериализуемого объекта.
             client (:obj:`yandex_music.Client`, optional): Клиент Yandex Music.
+
         Returns:
             :obj:`yandex_music.Label`: Лейбл.
         """

diff --git a/yandex_music/base.py b/yandex_music/base.py
@@ -22,6 +22,8 @@
 
 
 class YandexMusicObject:
+    """Базовый класс для всех объектов библиотеки."""
+
     __metaclass__ = ABCMeta
     _id_attrs: tuple = ()
 
@@ -36,6 +38,7 @@ def __getitem__(self, item: str) -> Any:  # noqa: ANN401
 
     @staticmethod
     def report_unknown_fields_callback(cls: type, unknown_fields: dict) -> None:
+        """Обратный вызов для обработки неизвестных полей."""
         logger.warning(
             f'Found unknown fields received from API! Please copy warn message '
             f'and send to {new_issue_by_template_url} (github issue), thank you!'
@@ -44,6 +47,15 @@ def report_unknown_fields_callback(cls: type, unknown_fields: dict) -> None:
 
     @staticmethod
     def is_valid_model_data(data: Any, *, array: bool = False) -> bool:  # noqa: ANN401
+        """Проверка на валидность данных.
+
+        Args:
+            data (:obj:`Any`): Данные для проверки.
+            array (:obj:`bool`, optional): Является ли объект массивом.
+
+        Returns:
+            :obj:`bool`: Валидны ли данные.
+        """
         if array:
             return data and isinstance(data, list) and all(isinstance(item, dict) for item in data)