From ff3b1fae02eaa209c32207f2808a69c537f9d642 Mon Sep 17 00:00:00 2001 From: Marshal Date: Tue, 4 Jun 2019 16:30:33 +0300 Subject: [PATCH] Project documentation started using sphinx generator Fixed imports --- .gitignore | 125 +++++++++++++ README.rst | 2 + docs/Makefile | 20 +++ docs/make.bat | 35 ++++ docs/requirements-docs.txt | 2 + docs/source/conf.py | 54 ++++++ docs/source/index.rst | 10 ++ docs/source/readme.rst | 1 + docs/source/yandex_music.client.rst | 6 + docs/source/yandex_music.rst | 6 + .../yandex_music.utils.request.request.rst | 6 + yandex_music/__init__.py | 168 +++++++++--------- yandex_music/client.py | 13 ++ yandex_music/utils/request.py | 10 ++ 14 files changed, 375 insertions(+), 83 deletions(-) create mode 100644 .gitignore create mode 100644 README.rst create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/requirements-docs.txt create mode 100644 docs/source/conf.py create mode 100644 docs/source/index.rst create mode 100644 docs/source/readme.rst create mode 100644 docs/source/yandex_music.client.rst create mode 100644 docs/source/yandex_music.rst create mode 100644 docs/source/yandex_music.utils.request.request.rst diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9062899 --- /dev/null +++ b/.gitignore @@ -0,0 +1,125 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +pip-wheel-metadata/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version + +# pipenv +# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. +# However, in case of collaboration, if having platform-specific dependencies or dependencies +# having no cross-platform support, pipenv may install dependencies that don't work, or not +# install all needed dependencies. +#Pipfile.lock + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +venvLP/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ \ No newline at end of file diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..281d553 --- /dev/null +++ b/README.rst @@ -0,0 +1,2 @@ +Welcome to Yandex Music API library +=================================== \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..9534b01 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/requirements-docs.txt b/docs/requirements-docs.txt new file mode 100644 index 0000000..856b3f4 --- /dev/null +++ b/docs/requirements-docs.txt @@ -0,0 +1,2 @@ +sphinx +sphinx_rtd_theme \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d64666a --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,54 @@ +# 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 + +# -- 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 +sys.path.insert(0, os.path.abspath('../..')) + + +# -- Project information ----------------------------------------------------- + +project = 'Yandex Music API' +copyright = '2019, Marshal' +author = 'Marshal' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..ffa30c2 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,10 @@ +.. yandex-music-api documentation master file, created by + sphinx-quickstart on Tue Jun 4 13:45:53 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Yandex Music API's documentation! +============================================ + +.. toctree:: + yandex_music diff --git a/docs/source/readme.rst b/docs/source/readme.rst new file mode 100644 index 0000000..38ba804 --- /dev/null +++ b/docs/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst \ No newline at end of file diff --git a/docs/source/yandex_music.client.rst b/docs/source/yandex_music.client.rst new file mode 100644 index 0000000..8552e87 --- /dev/null +++ b/docs/source/yandex_music.client.rst @@ -0,0 +1,6 @@ +yandex_music.Client +=================== + +.. autoclass:: yandex_music.Client + :members: + :show-inheritance: diff --git a/docs/source/yandex_music.rst b/docs/source/yandex_music.rst new file mode 100644 index 0000000..fab6c0d --- /dev/null +++ b/docs/source/yandex_music.rst @@ -0,0 +1,6 @@ +yandex_music package +==================== + +.. toctree:: + yandex_music.client + yandex_music.utils.request.request diff --git a/docs/source/yandex_music.utils.request.request.rst b/docs/source/yandex_music.utils.request.request.rst new file mode 100644 index 0000000..597887a --- /dev/null +++ b/docs/source/yandex_music.utils.request.request.rst @@ -0,0 +1,6 @@ +yandex_music.utils.request.Request +================================== + +.. autoclass:: yandex_music.utils.request.Request + :members: + :show-inheritance: diff --git a/yandex_music/__init__.py b/yandex_music/__init__.py index fbae51b..f7cc49e 100644 --- a/yandex_music/__init__.py +++ b/yandex_music/__init__.py @@ -10,97 +10,99 @@ from .promo_code_status import PromoCodeStatus from .download_info import DownloadInfo from .icon import Icon -from status.account import Account -from status.plus import Plus -from status.subscription import Subscription -from status.price import Price -from status.product import Product -from status.auto_renewable import AutoRenewable -from status.passport_phone import PassportPhone -from status.permissions import Permissions -from status.status import Status +from .status.account import Account +from .status.plus import Plus +from .status.subscription import Subscription +from .status.price import Price +from .status.product import Product +from .status.auto_renewable import AutoRenewable +from .status.passport_phone import PassportPhone +from .status.permissions import Permissions +from .status.status import Status -from track.major import Major -from track.normalization import Normalization -from track.track import Track +from .track.major import Major +from .track.normalization import Normalization +from .track.track import Track -from playlist.case_forms import CaseForms -from playlist.made_for import MadeFor -from playlist.user import User -from playlist.play_counter import PlayCounter -from playlist.playlist import Playlist +from .playlist.case_forms import CaseForms +from .playlist.made_for import MadeFor +from .playlist.user import User +from .playlist.play_counter import PlayCounter +from .playlist.playlist import Playlist -from artist.link import Link -from artist.counts import Counts -from artist.ratings import Ratings -from artist.artist import Artist +from .artist.link import Link +from .artist.counts import Counts +from .artist.ratings import Ratings +from .artist.artist import Artist -from album.label import Label -from album.track_position import TrackPosition -from album.album import Album +from .album.label import Label +from .album.track_position import TrackPosition +from .album.album import Album -from feed.generated_playlist import GeneratedPlaylist -from feed.album_event import AlbumEvent -from feed.artist_event import ArtistEvent -from feed.track_with_ads import TrackWithAds -from feed.day import Day -from feed.event import Event -from feed.feed import Feed +from .feed.generated_playlist import GeneratedPlaylist +from .feed.album_event import AlbumEvent +from .feed.artist_event import ArtistEvent +from .feed.track_with_ads import TrackWithAds +from .feed.day import Day +from .feed.event import Event +from .feed.feed import Feed -from likes.albums_likes import AlbumsLikes -from likes.artists_likes import ArtistsLikes -from likes.playlists_likes import PlaylistsLikes -from likes.tracks_likes import TracksLikes +from .likes.albums_likes import AlbumsLikes +from .likes.artists_likes import ArtistsLikes +from .likes.playlists_likes import PlaylistsLikes +from .likes.tracks_likes import TracksLikes -from search.video import Video -from search.best import Best -from search.search import Search -from search.suggestions import Suggestions -from search.search_result import SearchResult -from search.album_search_result import AlbumSearchResult -from search.artist_search_result import ArtistSearchResult -from search.playlist_search_result import PlaylistSearchResult -from search.track_search_result import TrackSearchResult -from search.video_search_result import VideoSearchResult +from .search.video import Video +from .search.best import Best +from .search.search import Search +from .search.suggestions import Suggestions +from .search.search_result import SearchResult +from .search.album_search_result import AlbumSearchResult +from .search.artist_search_result import ArtistSearchResult +from .search.playlist_search_result import PlaylistSearchResult +from .search.track_search_result import TrackSearchResult +from .search.video_search_result import VideoSearchResult -from landing.chart_item import ChartItem -from landing.play_context import PlayContext -from landing.track_short_old import TrackShortOld -from landing.mix_link import MixLink -from landing.promotion import Promotion -from landing.block_entity import BlockEntity -from landing.landing import Landing -from landing.block import Block -from landing.track_id import TrackId -from landing.chart import Chart -from landing.play_contexts_data import PlayContextsData -from landing.personal_playlists_data import PersonalPlaylistsData +from .landing.chart_item import ChartItem +from .landing.play_context import PlayContext +from .landing.track_short_old import TrackShortOld +from .landing.mix_link import MixLink +from .landing.promotion import Promotion +from .landing.block_entity import BlockEntity +from .landing.landing import Landing +from .landing.block import Block +from .landing.track_id import TrackId +from .landing.chart import Chart +from .landing.play_contexts_data import PlayContextsData +from .landing.personal_playlists_data import PersonalPlaylistsData -from genre.title import Title -from genre.images import Images -from genre.genre import Genre +from .genre.title import Title +from .genre.images import Images +from .genre.genre import Genre -from rotor.id import Id -from rotor.value import Value -from rotor.enum import Enum -from rotor.sequence import Sequence -from rotor.discrete_scale import DiscreteScale -from rotor.ad_params import AdParams -from rotor.restrictions import Restrictions -from rotor.rotor_settings import RotorSettings -from rotor.station import Station -from rotor.station_tracks_result import StationTracksResult -from rotor.station_result import StationResult -from rotor.dashboard import Dashboard +from .rotor.id import Id +from .rotor.value import Value +from .rotor.enum import Enum +from .rotor.sequence import Sequence +from .rotor.discrete_scale import DiscreteScale +from .rotor.ad_params import AdParams +from .rotor.restrictions import Restrictions +from .rotor.rotor_settings import RotorSettings +from .rotor.station import Station +from .rotor.station_tracks_result import StationTracksResult +from .rotor.station_result import StationResult +from .rotor.dashboard import Dashboard -__all__ = ['YandexMusicObject', 'Account', 'PassportPhone', 'InvocationInfo', 'Permissions', 'Plus', 'Subscription', - 'Status', 'Price', 'Product', 'AutoRenewable', 'Settings', 'PermissionAlerts', 'Experiments', 'Cover', - 'Ratings', 'Counts', 'Link', 'Artist', 'User', 'CaseForms', 'MadeFor', 'Label', 'Album', 'PlayCounter', - 'Playlist', 'TrackShort', 'TracksLikes', 'Major', 'Normalization', 'TrackPosition', 'Track', 'AlbumsLikes', - 'ArtistsLikes', 'PlaylistsLikes', 'GeneratedPlaylist', 'TrackWithAds', 'Day', 'ArtistEvent', 'AlbumEvent', - 'Feed', 'Event', 'PromoCodeStatus', 'DownloadInfo', 'Video', 'SearchResult', 'AlbumSearchResult', 'Best', - 'ArtistSearchResult', 'PlaylistSearchResult', 'TrackSearchResult', 'VideoSearchResult', 'Search', - 'Suggestions', 'MixLink', 'BlockEntity', 'Block', 'PlayContextsData', 'TrackId', 'TrackShortOld', - 'PersonalPlaylistsData', 'Promotion', 'Landing', 'Chart', 'ChartItem', 'PlayContext', 'Title', 'Genre', - 'Icon', 'Images', 'Id', 'Station', 'Dashboard', 'RotorSettings', 'AdParams', 'Restrictions', 'Value', 'Enum', - 'DiscreteScale', 'StationResult', 'Sequence', 'StationTracksResult'] +from .client import Client + +__all__ = ['YandexMusicObject', 'Client', 'Account', 'PassportPhone', 'InvocationInfo', 'Permissions', 'Plus', + 'Subscription', 'Status', 'Price', 'Product', 'AutoRenewable', 'Settings', 'PermissionAlerts', 'Experiments', + 'Cover', 'Ratings', 'Counts', 'Link', 'Artist', 'User', 'CaseForms', 'MadeFor', 'Label', 'Album', + 'PlayCounter', 'Playlist', 'TrackShort', 'TracksLikes', 'Major', 'Normalization', 'TrackPosition', 'Track', + 'AlbumsLikes', 'ArtistsLikes', 'PlaylistsLikes', 'GeneratedPlaylist', 'TrackWithAds', 'Day', 'ArtistEvent', + 'AlbumEvent', 'Feed', 'Event', 'PromoCodeStatus', 'DownloadInfo', 'Video', 'SearchResult', + 'AlbumSearchResult', 'Best', 'ArtistSearchResult', 'PlaylistSearchResult', 'TrackSearchResult', + 'VideoSearchResult', 'Search', 'Suggestions', 'MixLink', 'BlockEntity', 'Block', 'PlayContextsData', + 'TrackId', 'TrackShortOld', 'PersonalPlaylistsData', 'Promotion', 'Landing', 'Chart', 'ChartItem', + 'PlayContext', 'Title', 'Genre', 'Icon', 'Images', 'Id', 'Station', 'Dashboard', 'RotorSettings', 'AdParams', + 'Restrictions', 'Value', 'Enum', 'DiscreteScale', 'StationResult', 'Sequence', 'StationTracksResult'] diff --git a/yandex_music/client.py b/yandex_music/client.py index 1d36049..59c5a08 100644 --- a/yandex_music/client.py +++ b/yandex_music/client.py @@ -14,6 +14,18 @@ CLIENT_SECRET = '53bc75238f0c4d08a118e51fe9203300' class Client(YandexMusicObject): + """This object represents a Yandex Music Client. + + Args: + username (:obj:`str`): Client's login. + password (:obj:`str`): Client's password. + token (:obj:`str`, optional): Client's unique authentication. + base_url (:obj:`str`, optional): Yandex Music API service URL. + oauth_url (:obj:`str`, optional): Yandex Music OAuth service URL. + request (:obj:`yandex_music.utils.request.Request`, optional): Pre initialized + :obj:`yandex_music.utils.request.Request`. + """ + def __init__(self, username, password, token=None, base_url=None, oauth_url=None, request=None): self.logger = logging.getLogger(__name__) self.token = token @@ -36,6 +48,7 @@ class Client(YandexMusicObject): @classmethod def from_token(cls, token): + """Shortcut, authorization by token.""" return cls(username=None, password=None, token=token) def _generate_token_by_username_and_password(self, username, password, grant_type='password', diff --git a/yandex_music/utils/request.py b/yandex_music/utils/request.py index f35b316..6545d61 100644 --- a/yandex_music/utils/request.py +++ b/yandex_music/utils/request.py @@ -18,6 +18,16 @@ HEADERS = { class Request(object): + """ + Helper class for yandex_music which provides methods to perform POST & GET towards + yandex servers. + + Args: + client (:obj:`yandex_music.Client`): Yandex Music Client. + headers (:obj:`dict`, optional): Headers transmitted with each request. + proxies (:obj:`dict`, optional): Proxies. + """ + def __init__(self, client, headers=None,