mirror of
https://github.com/pkkid/python-plexapi
synced 2024-11-14 16:07:15 +00:00
368 lines
20 KiB
Python
368 lines
20 KiB
Python
# -*- coding: utf-8 -*-
|
||
import requests
|
||
from requests.status_codes import _codes as codes
|
||
from plexapi import BASE_HEADERS, CONFIG, TIMEOUT
|
||
from plexapi import log, logfilter, utils
|
||
from plexapi.client import PlexClient
|
||
from plexapi.compat import ElementTree, urlencode
|
||
from plexapi.exceptions import BadRequest, NotFound
|
||
from plexapi.library import Library
|
||
from plexapi.playlist import Playlist
|
||
from plexapi.playqueue import PlayQueue
|
||
from plexapi.utils import NA, cast
|
||
# import media to populate utils.LIBRARY_TYPES.
|
||
from plexapi import audio, video, photo, playlist as _pl
|
||
|
||
|
||
class PlexServer(object):
|
||
""" This is the main entry point to interacting with a Plex server. It allows you to
|
||
list connected clients, browse your library sections and perform actions such as
|
||
emptying trash. If you do not know the auth token required to access your Plex
|
||
server, or simply want to access your server with your username and password, you
|
||
can also create an PlexServer instance from :class:`~plexapi.myplex.MyPlexAccount`.
|
||
|
||
Parameters:
|
||
baseurl (str): Base url for to access the Plex Media Server (default: 'http://localhost:32400').
|
||
token (str): Required Plex authentication token to access the server.
|
||
session (requests.Session, optional): Use your own session object if you want to
|
||
cache the http responses from PMS
|
||
|
||
Attributes:
|
||
allowCameraUpload (bool): True if server allows camera upload.
|
||
allowChannelAccess (bool): True if server allows channel access (iTunes?).
|
||
allowMediaDeletion (bool): True is server allows media to be deleted.
|
||
allowSharing (bool): True is server allows sharing.
|
||
allowSync (bool): True is server allows sync.
|
||
backgroundProcessing (bool): Unknown
|
||
baseurl (str): Base url for the Plex Media Server to access.
|
||
certificate (bool): True if server has an HTTPS certificate.
|
||
companionProxy (bool): Unknown
|
||
diagnostics (bool): Unknown
|
||
eventStream (bool): Unknown
|
||
friendlyName (str): Human friendly name for this server.
|
||
hubSearch (bool): True if `Hub Search <https://www.plex.tv/blog
|
||
/seek-plex-shall-find-leveling-web-app/>`_ is enabled. I believe this
|
||
is enabled for everyone
|
||
machineIdentifier (str): Unique ID for this server (looks like an md5).
|
||
multiuser (bool): True if `multiusers <https://support.plex.tv/hc/en-us/articles
|
||
/200250367-Multi-User-Support>`_ are enabled.
|
||
myPlex (bool): Unknown (True if logged into myPlex?).
|
||
myPlexMappingState (str): Unknown (ex: mapped).
|
||
myPlexSigninState (str): Unknown (ex: ok).
|
||
myPlexSubscription (str): True if you have a myPlex subscription.
|
||
myPlexUsername (str): Email address if signed into myPlex (user@example.com)
|
||
ownerFeatures (bool): List of features allowed by the server owner. This may be based
|
||
on your PlexPass subscription. Features include: camera_upload, cloudsync,
|
||
content_filter, dvr, hardware_transcoding, home, lyrics, music_videos, pass,
|
||
photo_autotags, premium_music_metadata, session_bandwidth_restrictions, sync,
|
||
trailers, webhooks (and maybe more).
|
||
photoAutoTag (bool): True if photo `auto-tagging <https://support.plex.tv/hc/en-us
|
||
/articles/234976627-Auto-Tagging-of-Photos>`_ is enabled.
|
||
platform (str): Platform the server is hosted on (ex: Linux)
|
||
platformVersion (str): Platform version (ex: '6.1 (Build 7601)', '4.4.0-59-generic').
|
||
pluginHost (bool): Unknown
|
||
readOnlyLibraries (bool): Unknown
|
||
requestParametersInCookie (bool): Unknown
|
||
session (Session): Requests session used for object caching.
|
||
streamingBrainVersion (bool): Current `Streaming Brain <https://www.plex.tv/blog
|
||
/mcstreamy-brain-take-world-two-easy-steps/>`_ version.
|
||
sync (bool): True if `syncing to a device <https://support.plex.tv/hc/en-us/articles
|
||
/201053678-Sync-Media-to-a-Device>`_ is enabled.
|
||
token (str): Plex authentication token to access the server.
|
||
transcoderActiveVideoSessions (int): Number of active video transcoding sessions.
|
||
transcoderAudio (bool): True if audio transcoding audio is available.
|
||
transcoderLyrics (bool): True if audio transcoding lyrics is available.
|
||
transcoderPhoto (bool): True if audio transcoding photos is available.
|
||
transcoderSubtitles (bool): True if audio transcoding subtitles is available.
|
||
transcoderVideo (bool): True if audio transcoding video is available.
|
||
transcoderVideoBitrates (bool): List of video bitrates.
|
||
transcoderVideoQualities (bool): List of video qualities.
|
||
transcoderVideoResolutions (bool): List of video resolutions.
|
||
updatedAt (int): Datetime the server was updated.
|
||
updater (bool): Unknown
|
||
version (str): Current Plex version (ex: 1.3.2.3112-1751929)
|
||
voiceSearch (bool): True if voice search is enabled. (is this Google Voice search?)
|
||
"""
|
||
def __init__(self, baseurl='http://localhost:32400', token=None, session=None):
|
||
self.baseurl = baseurl or CONFIG.get('authentication.baseurl')
|
||
self.token = token or CONFIG.get('authentication.token')
|
||
if self.token:
|
||
logfilter.add_secret(self.token)
|
||
self.session = session or requests.Session()
|
||
self._library = None # cached library
|
||
self.reload()
|
||
|
||
def _loadData(self, data):
|
||
""" Load attribute values from Plex XML response. """
|
||
self._data = data
|
||
self.allowCameraUpload = cast(bool, data.attrib.get('allowCameraUpload'))
|
||
self.allowChannelAccess = cast(bool, data.attrib.get('allowChannelAccess'))
|
||
self.allowMediaDeletion = cast(bool, data.attrib.get('allowMediaDeletion'))
|
||
self.allowSharing = cast(bool, data.attrib.get('allowSharing'))
|
||
self.allowSync = cast(bool, data.attrib.get('allowSync'))
|
||
self.backgroundProcessing = cast(bool, data.attrib.get('backgroundProcessing'))
|
||
self.certificate = cast(bool, data.attrib.get('certificate'))
|
||
self.companionProxy = cast(bool, data.attrib.get('companionProxy'))
|
||
self.diagnostics = utils.toList(data.attrib.get('diagnostics'))
|
||
self.eventStream = cast(bool, data.attrib.get('eventStream'))
|
||
self.friendlyName = data.attrib.get('friendlyName')
|
||
self.hubSearch = cast(bool, data.attrib.get('hubSearch'))
|
||
self.machineIdentifier = data.attrib.get('machineIdentifier')
|
||
self.multiuser = cast(bool, data.attrib.get('multiuser'))
|
||
self.myPlex = cast(bool, data.attrib.get('myPlex'))
|
||
self.myPlexMappingState = data.attrib.get('myPlexMappingState')
|
||
self.myPlexSigninState = data.attrib.get('myPlexSigninState')
|
||
self.myPlexSubscription = data.attrib.get('myPlexSubscription')
|
||
self.myPlexUsername = data.attrib.get('myPlexUsername')
|
||
self.ownerFeatures = utils.toList(data.attrib.get('ownerFeatures'))
|
||
self.photoAutoTag = cast(bool, data.attrib.get('photoAutoTag'))
|
||
self.platform = data.attrib.get('platform')
|
||
self.platformVersion = data.attrib.get('platformVersion')
|
||
self.pluginHost = cast(bool, data.attrib.get('pluginHost'))
|
||
self.readOnlyLibraries = cast(int, data.attrib.get('readOnlyLibraries'))
|
||
self.requestParametersInCookie = cast(bool, data.attrib.get('requestParametersInCookie'))
|
||
self.streamingBrainVersion = data.attrib.get('streamingBrainVersion')
|
||
self.sync = cast(bool, data.attrib.get('sync'))
|
||
self.transcoderActiveVideoSessions = int(data.attrib.get('transcoderActiveVideoSessions', 0))
|
||
self.transcoderAudio = cast(bool, data.attrib.get('transcoderAudio'))
|
||
self.transcoderLyrics = cast(bool, data.attrib.get('transcoderLyrics'))
|
||
self.transcoderPhoto = cast(bool, data.attrib.get('transcoderPhoto'))
|
||
self.transcoderSubtitles = cast(bool, data.attrib.get('transcoderSubtitles'))
|
||
self.transcoderVideo = cast(bool, data.attrib.get('transcoderVideo'))
|
||
self.transcoderVideoBitrates = utils.toList(data.attrib.get('transcoderVideoBitrates'))
|
||
self.transcoderVideoQualities = utils.toList(data.attrib.get('transcoderVideoQualities'))
|
||
self.transcoderVideoResolutions = utils.toList(data.attrib.get('transcoderVideoResolutions'))
|
||
self.updatedAt = utils.toDatetime(data.attrib.get('updatedAt', NA))
|
||
self.updater = cast(bool, data.attrib.get('updater'))
|
||
self.version = data.attrib.get('version')
|
||
self.voiceSearch = cast(bool, data.attrib.get('voiceSearch'))
|
||
|
||
def __repr__(self):
|
||
return '<%s:%s>' % (self.__class__.__name__, self.baseurl)
|
||
|
||
@property
|
||
def library(self):
|
||
""" Library to browse or search your media. """
|
||
if not self._library:
|
||
self._library = Library(self, self.query('/library/'))
|
||
return self._library
|
||
|
||
def account(self):
|
||
""" Returns the :class:`~plexapi.server.Account` object this server belongs to. """
|
||
data = self.query('/myplex/account')
|
||
return Account(self, data)
|
||
|
||
def clients(self):
|
||
""" Returns a list of all :class:`~plexapi.client.PlexClient` objects
|
||
connected to this server.
|
||
"""
|
||
items = []
|
||
for elem in self.query('/clients'):
|
||
baseurl = 'http://%s:%s' % (elem.attrib['host'], elem.attrib['port'])
|
||
items.append(PlexClient(baseurl, server=self, data=elem))
|
||
return items
|
||
|
||
def client(self, name):
|
||
""" Returns the :class:`~plexapi.client.PlexClient` that matches the specified name.
|
||
|
||
Parameters:
|
||
name (str): Name of the client to return.
|
||
|
||
Raises:
|
||
:class:`~plexapi.exceptions.NotFound`: Unknown client name
|
||
"""
|
||
for elem in self.query('/clients'):
|
||
if elem.attrib.get('name').lower() == name.lower():
|
||
baseurl = 'http://%s:%s' % (elem.attrib['host'], elem.attrib['port'])
|
||
return PlexClient(baseurl, server=self, data=elem)
|
||
raise NotFound('Unknown client name: %s' % name)
|
||
|
||
def createPlaylist(self, title, items):
|
||
""" Creates and returns a new :class:`~plexapi.playlist.Playlist`.
|
||
|
||
Parameters:
|
||
title (str): Title of the playlist to be created.
|
||
items (list<Media>): List of media items to include in the playlist.
|
||
"""
|
||
return Playlist.create(self, title, items)
|
||
|
||
def createPlayQueue(self, item):
|
||
""" Creates and returns a new :class:`~plexapi.playqueue.PlayQueue`.
|
||
|
||
Parameters:
|
||
item (Media or Playlist): Media or playlist to add to PlayQueue.
|
||
"""
|
||
return PlayQueue.create(self, item)
|
||
|
||
def headers(self):
|
||
""" Returns a dict containing base headers to include in all requests to the server. """
|
||
headers = BASE_HEADERS
|
||
if self.token:
|
||
headers['X-Plex-Token'] = self.token
|
||
return headers
|
||
|
||
def history(self):
|
||
""" Returns a list of media items from watched history. """
|
||
return utils.listItems(self, '/status/sessions/history/all')
|
||
|
||
def playlists(self):
|
||
""" Returns a list of all :class:`~plexapi.playlist.Playlist` objects saved on the server. """
|
||
# TODO: Add sort and type options?
|
||
# /playlists/all?type=15&sort=titleSort%3Aasc&playlistType=video&smart=0
|
||
return utils.listItems(self, '/playlists')
|
||
|
||
def playlist(self, title):
|
||
""" Returns the :class:`~plexapi.client.Playlist` that matches the specified title.
|
||
|
||
Parameters:
|
||
title (str): Title of the playlist to return.
|
||
|
||
Raises:
|
||
:class:`~plexapi.exceptions.NotFound`: Invalid playlist title
|
||
"""
|
||
for item in self.playlists():
|
||
if item.title == title:
|
||
return item
|
||
raise NotFound('Invalid playlist title: %s' % title)
|
||
|
||
def query(self, path, method=None, headers=None, **kwargs):
|
||
""" Main method used to handle HTTPS requests to the Plex server. This method helps
|
||
by encoding the response to utf-8 and parsing the returned XML into and
|
||
ElementTree object. Returns None if no data exists in the response.
|
||
|
||
Parameters:
|
||
path (str): Relative path to query on the server api (ex: '/search?query=HELLO')
|
||
method (func): requests.method to use for this query (request.get or
|
||
requests.put; defaults to get)
|
||
headers (dict): Optionally include additional headers for this request.
|
||
**kwargs (dict): Optionally include additional kwargs for in the specified
|
||
reuqest method. These kwargs are simply passed through to method().
|
||
|
||
Raises:
|
||
:class:`~plexapi.exceptions.BadRequest`: Raised when response is not in (200, 201).
|
||
"""
|
||
url = self.url(path)
|
||
method = method or self.session.get
|
||
log.info('%s %s', method.__name__.upper(), url)
|
||
h = self.headers().copy()
|
||
if headers:
|
||
h.update(headers)
|
||
response = method(url, headers=h, timeout=TIMEOUT, **kwargs)
|
||
#print(response.url)
|
||
if response.status_code not in [200, 201]: # pragma: no cover
|
||
codename = codes.get(response.status_code)[0]
|
||
raise BadRequest('(%s) %s %s' % (response.status_code, codename, response.url))
|
||
data = response.text.encode('utf8')
|
||
return ElementTree.fromstring(data) if data else None
|
||
|
||
def reload(self):
|
||
""" Reload attribute values from Plex XML response. """
|
||
try:
|
||
data = self.query('/')
|
||
self._loadData(data)
|
||
except Exception as err:
|
||
log.error('%s: %s', self.baseurl, err)
|
||
raise NotFound('No server found at: %s' % self.baseurl)
|
||
|
||
def search(self, query, mediatype=None, limit=None):
|
||
""" Returns a list of media items or filter categories from the resulting
|
||
`Hub Search <https://www.plex.tv/blog/seek-plex-shall-find-leveling-web-app/>`_
|
||
against all items in your Plex library. This searches genres, actors, directors,
|
||
playlists, as well as all the obvious media titles. It performs spell-checking
|
||
against your search terms (because KUROSAWA is hard to spell). It also provides
|
||
contextual search results. So for example, if you search for 'Pernice', it’ll
|
||
return 'Pernice Brothers' as the artist result, but we’ll also go ahead and
|
||
return your most-listened to albums and tracks from the artist. If you type
|
||
'Arnold' you’ll get a result for the actor, but also the most recently added
|
||
movies he’s in.
|
||
|
||
Parameters:
|
||
query (str): Query to use when searching your library.
|
||
mediatype (str): Optionally limit your search to the specified media type.
|
||
limit (int): Optionally limit to the specified number of results per Hub.
|
||
"""
|
||
results = []
|
||
params = {'query': query}
|
||
if mediatype:
|
||
params['section'] = utils.SEARCHTYPES[mediatype]
|
||
if limit:
|
||
params['limit'] = limit
|
||
url = '/hubs/search?%s' % urlencode(params)
|
||
for hub in utils.listItems(self, url, bytag=True):
|
||
results += hub.items
|
||
return results
|
||
|
||
def sessions(self):
|
||
""" Returns a list of all active session (currently playing) media objects. """
|
||
return utils.listItems(self, '/status/sessions')
|
||
|
||
def url(self, path):
|
||
""" Utility function to help build proper URL strings as well as always include
|
||
the requred authentication token for all api requests to the server.
|
||
"""
|
||
if self.token:
|
||
delim = '&' if '?' in path else '?'
|
||
return '%s%s%sX-Plex-Token=%s' % (self.baseurl, path, delim, self.token)
|
||
return '%s%s' % (self.baseurl, path)
|
||
|
||
def transcodeImage(self, media, height, width, opacity=100, saturation=100):
|
||
""" Returns the URL for a transcoded image from the specified media object.
|
||
Returns None if no media specified (needed to prevent transcoding NA, or
|
||
user tries to pass thumb, or art directly).
|
||
|
||
Parameters:
|
||
height (int): Height to transcode the image to.
|
||
width (int): Width to transcode the image to.
|
||
opacity (int): Opacity of the resulting image (possibly deprecated).
|
||
saturation (int): Saturating of the resulting image.
|
||
"""
|
||
if media:
|
||
transcode_url = '/photo/:/transcode?height=%s&width=%s&opacity=%s&saturation=%s&url=%s' % (
|
||
height, width, opacity, saturation, media)
|
||
return self.url(transcode_url)
|
||
|
||
|
||
class Account(object):
|
||
""" Contains the locally cached MyPlex account information. The properties provided don't
|
||
match the :class:`~plexapi.myplex.MyPlexAccount` object very well. I believe this exists
|
||
because access to myplex is not required to get basic plex information. I can't imagine
|
||
object is terribly useful except unless you were needed this information while offline.
|
||
|
||
Parameters:
|
||
server (:class:`~plexapi.server.PlexServer`): PlexServer this account is connected to (optional)
|
||
data (ElementTree): Response from PlexServer used to build this object (optional).
|
||
|
||
Attributes:
|
||
authToken (str): Plex authentication token to access the server.
|
||
mappingError (str): Unknown
|
||
mappingErrorMessage (str): Unknown
|
||
mappingState (str): Unknown
|
||
privateAddress (str): Local IP address of the Plex server.
|
||
privatePort (str): Local port of the Plex server.
|
||
publicAddress (str): Public IP address of the Plex server.
|
||
publicPort (str): Public port of the Plex server.
|
||
signInState (str): Signin state for this account (ex: ok).
|
||
subscriptionActive (str): True if the account subscription is active.
|
||
subscriptionFeatures (str): List of features allowed by the server for this account.
|
||
This may be based on your PlexPass subscription. Features include: camera_upload,
|
||
cloudsync, content_filter, dvr, hardware_transcoding, home, lyrics, music_videos,
|
||
pass, photo_autotags, premium_music_metadata, session_bandwidth_restrictions,
|
||
sync, trailers, webhooks' (and maybe more).
|
||
subscriptionState (str): 'Active' if this subscription is active.
|
||
username (str): Plex account username (user@example.com).
|
||
"""
|
||
def __init__(self, server, data):
|
||
self._data = data
|
||
self.authToken = data.attrib.get('authToken')
|
||
self.username = data.attrib.get('username')
|
||
self.mappingState = data.attrib.get('mappingState')
|
||
self.mappingError = data.attrib.get('mappingError')
|
||
self.mappingErrorMessage = data.attrib.get('mappingErrorMessage')
|
||
self.signInState = data.attrib.get('signInState')
|
||
self.publicAddress = data.attrib.get('publicAddress')
|
||
self.publicPort = data.attrib.get('publicPort')
|
||
self.privateAddress = data.attrib.get('privateAddress')
|
||
self.privatePort = data.attrib.get('privatePort')
|
||
self.subscriptionFeatures = utils.toList(data.attrib.get('subscriptionFeatures'))
|
||
self.subscriptionActive = cast(bool, data.attrib.get('subscriptionActive'))
|
||
self.subscriptionState = data.attrib.get('subscriptionState')
|