diff --git a/docs/conf.py b/docs/conf.py index ab72a642..4ce5377d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -12,17 +12,13 @@ # 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 sys +import copy, sys import sphinx_rtd_theme from os.path import abspath, dirname, join from recommonmark.parser import CommonMarkParser - sys.path.insert(0, join(dirname(abspath('.')), 'plexapi')) import plexapi -# 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.viewcode', @@ -30,8 +26,17 @@ extensions = [ 'sphinxcontrib.napoleon', ] +# -- Monkey-patch docstring to not auto-link :ivars ------------------------ +from sphinx.domains.python import PythonDomain +print('Monkey-patching PythonDomain.resolve_xref()') +old_resolve_xref = copy.deepcopy(PythonDomain.resolve_xref) +def new_resolve_xref(*args): + if '.' not in args[5]: # target + return None + return old_resolve_xref(*args) +PythonDomain.resolve_xref = new_resolve_xref -# -- Napoleon Settings ------------------------------------------------ +# -- Napoleon Settings ----------------------------------------------------- napoleon_google_docstring = True napoleon_numpy_docstring = False napoleon_include_init_with_doc = False diff --git a/plexapi/audio.py b/plexapi/audio.py index d3bbae48..ac09bc1c 100644 --- a/plexapi/audio.py +++ b/plexapi/audio.py @@ -11,7 +11,7 @@ class Audio(PlexPartialObject): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). Attributes: @@ -73,7 +73,7 @@ class Artist(Audio): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). Attributes: @@ -100,12 +100,12 @@ class Artist(Audio): self.similar = [media.Similar(self.server, e) for e in data if e.tag == media.Similar.TYPE] def albums(self): - """ Returns a list of :class:`plexapi.audio.Album` objects by this artist. """ + """ Returns a list of :class:`~plexapi.audio.Album` objects by this artist. """ path = '%s/children' % self.key return utils.listItems(self.server, path, Album.TYPE) def album(self, title): - """ Returns the :class:`plexapi.audio.Album` that matches the specified title. + """ Returns the :class:`~plexapi.audio.Album` that matches the specified title. Parameters: title (str): Title of the album to return. @@ -114,12 +114,12 @@ class Artist(Audio): return utils.findItem(self.server, path, title) def tracks(self): - """ Returns a list of :class:`plexapi.audio.Track` objects by this artist. """ + """ Returns a list of :class:`~plexapi.audio.Track` objects by this artist. """ path = '%s/allLeaves' % self.key return utils.listItems(self.server, path) def track(self, title): - """ Returns the :class:`plexapi.audio.Track` that matches the specified title. + """ Returns the :class:`~plexapi.audio.Track` that matches the specified title. Parameters: title (str): Title of the track to return. @@ -138,7 +138,7 @@ class Album(Audio): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). Attributes: @@ -171,12 +171,12 @@ class Album(Audio): self.genres = [media.Genre(self.server, e) for e in data if e.tag == media.Genre.TYPE] def tracks(self): - """ Returns a list of :class:`plexapi.audio.Track` objects in this album. """ + """ Returns a list of :class:`~plexapi.audio.Track` objects in this album. """ path = '%s/children' % self.key return utils.listItems(self.server, path) def track(self, title): - """ Returns the :class:`plexapi.audio.Track` that matches the specified title. + """ Returns the :class:`~plexapi.audio.Track` that matches the specified title. Parameters: title (str): Title of the track to return. @@ -199,7 +199,7 @@ class Track(Audio, Playable): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) - data (:class:`ElementTree`): XML response from PlexServer used to build this object (optional). + data (ElementTree): XML response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). Attributes: diff --git a/plexapi/client.py b/plexapi/client.py index 77c20076..0478597b 100644 --- a/plexapi/client.py +++ b/plexapi/client.py @@ -17,7 +17,7 @@ class PlexClient(object): token (str): X-Plex-Token used for authenication (optional). session (:class:`~requests.Session`): requests.Session object if you want more control (optional). server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). Attributes: baseurl (str): HTTP address of the client @@ -104,7 +104,7 @@ class PlexClient(object): self._proxyThroughServer = value def query(self, path, method=None, headers=None, **kwargs): - """ Returns an :class:`ElementTree` object containing the response + """ Returns an ElementTree object containing the response from the specified request path. Parameters: @@ -129,7 +129,7 @@ class PlexClient(object): def sendCommand(self, command, proxy=None, **params): """ Convenience wrapper around :func:`~plexapi.client.PlexClient.query()` to more easily - send simple commands to the client. Returns an :class:`ElementTree` object containing + send simple commands to the client. Returns an ElementTree object containing the response. Parameters: diff --git a/plexapi/library.py b/plexapi/library.py index 366a27b4..60739589 100644 --- a/plexapi/library.py +++ b/plexapi/library.py @@ -156,7 +156,7 @@ class LibrarySection(object): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer object this library section is from. - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). Attributes: diff --git a/plexapi/media.py b/plexapi/media.py index 9b1804fc..b4f049b4 100644 --- a/plexapi/media.py +++ b/plexapi/media.py @@ -1,7 +1,4 @@ # -*- coding: utf-8 -*- -""" -PlexAPI Media -""" from plexapi.utils import cast diff --git a/plexapi/photo.py b/plexapi/photo.py index cb387ee4..16f71b04 100644 --- a/plexapi/photo.py +++ b/plexapi/photo.py @@ -1,10 +1,4 @@ # -*- coding: utf-8 -*- -""" -PlexPhoto - -Attributes: - NA (TYPE): Description -""" from plexapi import media, utils from plexapi.utils import PlexPartialObject NA = utils.NA @@ -12,46 +6,36 @@ NA = utils.NA @utils.register_libtype class Photoalbum(PlexPartialObject): - """Summary + """ Represents a photoalbum (collection of photos). - Attributes: - addedAt (TYPE): Description - art (TYPE): Description - composite (TYPE): Description - guid (TYPE): Description - index (TYPE): Description - key (TYPE): Description - librarySectionID (TYPE): Description - listType (str): Description - ratingKey (TYPE): Description - summary (TYPE): Description - thumb (TYPE): Description - title (TYPE): Description - TYPE (str): Description - type (TYPE): Description - updatedAt (TYPE): Description + Parameters: + server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) + data (ElementTree): Response from PlexServer used to build this object (optional). + initpath (str): Relative path requested when retrieving specified `data` (optional). + + Attributes: + addedAt (datetime): Datetime this item was added to the library. + art (str): Photo art (/library/metadata//art/) + composite (str): Unknown + guid (str): Unknown (unique ID) + index (sting): Index number of this album. + key (str): API URL (/library/metadata/). + librarySectionID (int): :class:`~plexapi.library.LibrarySection` ID. + listType (str): Hardcoded as 'photo' (useful for search filters). + ratingKey (int): Unique key identifying this item. + summary (str): Summary of the photoalbum. + thumb (str): URL to thumbnail image. + title (str): Photoalbum title. (Trip to Disney World) + type (str): Unknown + updatedAt (datatime): Datetime this item was updated. """ TYPE = 'photoalbum' def __init__(self, server, data, initpath): - """Summary - - Args: - server (TYPE): Description - data (TYPE): Description - initpath (TYPE): Description - """ super(Photoalbum, self).__init__(data, initpath, server) def _loadData(self, data): - """Summary - - Args: - data (TYPE): Description - - Returns: - TYPE: Description - """ + """ Load attribute values from Plex XML response. """ self.listType = 'photo' self.addedAt = utils.toDatetime(data.attrib.get('addedAt', NA)) self.art = data.attrib.get('art', NA) @@ -68,78 +52,53 @@ class Photoalbum(PlexPartialObject): self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt', NA)) def photos(self): - """Summary - - Returns: - TYPE: Description - """ + """ Returns a list of :class:`~plexapi.photo.Photo` objects in this album. """ path = '/library/metadata/%s/children' % self.ratingKey return utils.listItems(self.server, path, Photo.TYPE) def photo(self, title): - """Summary - - Args: - title (TYPE): Description - - Returns: - TYPE: Description - """ + """ Returns the :class:`~plexapi.photo.Photo` that matches the specified title. """ path = '/library/metadata/%s/children' % self.ratingKey return utils.findItem(self.server, path, title) def section(self): - """Summary - - Returns: - TYPE: Description - """ + """ Returns the :class:`~plexapi.library.LibrarySection` this item belongs to. """ return self.server.library.sectionByID(self.librarySectionID) @utils.register_libtype class Photo(PlexPartialObject): - """Summary + """ Represents a single photo. - Attributes: - addedAt (TYPE): Description - index (TYPE): Description - key (TYPE): Description - listType (str): Description - media (TYPE): Description - originallyAvailableAt (TYPE): Description - parentKey (TYPE): Description - parentRatingKey (TYPE): Description - ratingKey (TYPE): Description - summary (TYPE): Description - thumb (TYPE): Description - title (TYPE): Description - TYPE (str): Description - type (TYPE): Description - updatedAt (TYPE): Description - year (TYPE): Description + Parameters: + server (:class:`~plexapi.server.PlexServer`): PlexServer this client is connected to (optional) + data (ElementTree): Response from PlexServer used to build this object (optional). + initpath (str): Relative path requested when retrieving specified `data` (optional). + + Attributes: + addedAt (datetime): Datetime this item was added to the library. + index (sting): Index number of this photo. + key (str): API URL (/library/metadata/). + listType (str): Hardcoded as 'photo' (useful for search filters). + media (TYPE): Unknown + originallyAvailableAt (datetime): Datetime this photo was added to Plex. + parentKey (str): Photoalbum API URL. + parentRatingKey (int): Unique key identifying the photoalbum. + ratingKey (int): Unique key identifying this item. + summary (str): Summary of the photo. + thumb (str): URL to thumbnail image. + title (str): Photo title. + type (str): Unknown + updatedAt (datatime): Datetime this item was updated. + year (int): Year this photo was taken. """ TYPE = 'photo' def __init__(self, server, data, initpath): - """Summary - - Args: - server (TYPE): Description - data (TYPE): Description - initpath (TYPE): Description - """ super(Photo, self).__init__(data, initpath, server) def _loadData(self, data): - """Summary - - Args: - data (TYPE): Description - - Returns: - TYPE: Description - """ + """ Load attribute values from Plex XML response. """ self.listType = 'photo' self.addedAt = utils.toDatetime(data.attrib.get('addedAt', NA)) self.index = utils.cast(int, data.attrib.get('index', NA)) @@ -157,20 +116,12 @@ class Photo(PlexPartialObject): self.year = utils.cast(int, data.attrib.get('year', NA)) if self.isFullObject(): self.media = [media.Media(self.server, e, self.initpath, self) - for e in data if e.tag == media.Media.TYPE] + for e in data if e.tag == media.Media.TYPE] def photoalbum(self): - """Summary - - Returns: - TYPE: Description - """ + """ Return this photo's :class:`~plexapi.photo.Photoalbum`. """ return utils.listItems(self.server, self.parentKey)[0] def section(self): - """Summary - - Returns: - TYPE: Description - """ + """ Returns the :class:`~plexapi.library.LibrarySection` this item belongs to. """ return self.server.library.sectionByID(self.photoalbum().librarySectionID) diff --git a/plexapi/playlist.py b/plexapi/playlist.py index 36fa5ddf..6b70c3d4 100644 --- a/plexapi/playlist.py +++ b/plexapi/playlist.py @@ -1,7 +1,4 @@ # -*- coding: utf-8 -*- -""" -PlexPlaylist -""" from plexapi import utils from plexapi.exceptions import BadRequest from plexapi.utils import cast, toDatetime diff --git a/plexapi/playqueue.py b/plexapi/playqueue.py index c238e31b..5b3e084a 100644 --- a/plexapi/playqueue.py +++ b/plexapi/playqueue.py @@ -1,6 +1,4 @@ # -*- coding: utf-8 -*- - - import plexapi import requests from plexapi import utils diff --git a/plexapi/sync.py b/plexapi/sync.py index 5d615292..7a43cd6d 100644 --- a/plexapi/sync.py +++ b/plexapi/sync.py @@ -1,5 +1,4 @@ # -*- coding: utf-8 -*- - import requests from plexapi import utils from plexapi.exceptions import NotFound diff --git a/plexapi/utils.py b/plexapi/utils.py index a5f27b3f..3051f862 100644 --- a/plexapi/utils.py +++ b/plexapi/utils.py @@ -1,5 +1,4 @@ # -*- coding: utf-8 -*- - import logging, re from datetime import datetime from plexapi.compat import quote, urlencode, string_type @@ -66,7 +65,7 @@ class PlexPartialObject(object): automatically and update itself. Attributes: - data (:class:`ElementTree`): Response from PlexServer used to build this object (optional). + data (ElementTree): Response from PlexServer used to build this object (optional). initpath (str): Relative path requested when retrieving specified `data` (optional). server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from. """ @@ -287,7 +286,7 @@ def findPlayer(server, data): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from. - data (:class:`ElementTree`): XML data to find Player in. + data (ElementTree): XML data to find Player in. """ elem = data.find('Player') if elem is not None: @@ -319,7 +318,7 @@ def findTranscodeSession(server, data): Parameters: server (:class:`~plexapi.server.PlexServer`): PlexServer object this is from. - data (:class:`ElementTree`): XML data to find TranscodeSession in. + data (ElementTree): XML data to find TranscodeSession in. """ elem = data.find('TranscodeSession') @@ -333,7 +332,7 @@ def findUsername(data): """ Returns the username if found in the specified XML data. Returns None if not found. Parameters: - data (:class:`ElementTree`): XML data to find username in. + data (ElementTree): XML data to find username in. """ elem = data.find('User') if elem is not None: @@ -452,12 +451,12 @@ def searchType(libtype): def threaded(callback, listargs): - """ Returns the result of for each set of *args in listargs. Each call + """ Returns the result of for each set of \*args in listargs. Each call to