Utils plexapi.utils

class plexapi.utils.SecretsFilter(secrets=None)

Bases: Filter

Logging filter to hide secrets.

filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

plexapi.utils.registerPlexObject(cls)

Registry of library types we may come across when parsing XML. This allows us to define a few helper functions to dynamically convert the XML into objects. See buildItem() below for an example.

plexapi.utils.getPlexObject(ehash, default)

Return the PlexObject class for the specified ehash. This recursively looks up the class with the highest specificity, falling back to the default class if not found.

plexapi.utils.cast(func, value)

Cast the specified value to the specified type (returned by func). Currently this only support str, int, float, bool. Should be extended if needed.

Parameters:

• func (func) – Callback function to used cast to type (int, bool, float).

• value (any) – value to be cast and returned.

plexapi.utils.joinArgs(args)

Returns a query string (uses for HTTP URLs) where only the value is URL encoded. Example return value: ‘?genre=action&type=1337’.

Parameters:

args (dict) – Arguments to include in query string.

plexapi.utils.rget(obj, attrstr, default=None, delim='.')

Returns the value at the specified attrstr location within a nested tree of dicts, lists, tuples, functions, classes, etc. The lookup is done recursively for each key in attrstr (split by by the delimiter) This function is heavily influenced by the lookups used in Django templates.

Parameters:

• obj (any) – Object to start the lookup in (dict, obj, list, tuple, etc).

• attrstr (str) – String to lookup (ex: ‘foo.bar.baz.value’)

• default (any) – Default value to return if not found.

• delim (str) – Delimiter separating keys in attrstr.

plexapi.utils.searchType(libtype)

Returns the integer value of the library string type.

Parameters:

libtype (str) – LibType to lookup (See SEARCHTYPES)

Raises:

NotFound – Unknown libtype

plexapi.utils.reverseSearchType(libtype)

Returns the string value of the library type.

Parameters:

libtype (int) – Integer value of the library type.

Raises:

NotFound – Unknown libtype

plexapi.utils.tagType(tag)

Returns the integer value of the library tag type.

Parameters:

tag (str) – Tag to lookup (See TAGTYPES)

Raises:

NotFound – Unknown tag

plexapi.utils.reverseTagType(tag)

Returns the string value of the library tag type.

Parameters:

tag (int) – Integer value of the library tag type.

Raises:

NotFound – Unknown tag

plexapi.utils.threaded(callback, listargs)

Returns the result of <callback> for each set of *args in listargs. Each call to <callback> is called concurrently in their own separate threads.

Parameters:

• callback (func) – Callback function to apply to each set of *args.

• listargs (list) – List of lists; *args to pass each thread.

plexapi.utils.toDatetime(value, format=None)

Returns a datetime object from the specified value.

Parameters:

• value (str) – value to return as a datetime

• format (str) – Format to pass strftime (optional; if value is a str).

plexapi.utils.millisecondToHumanstr(milliseconds)

Returns human readable time duration [D day[s], ]HH:MM:SS.UUU from milliseconds.

Parameters:

milliseconds (str, int) – time duration in milliseconds.

plexapi.utils.toList(value, itemcast=None, delim=',')

Returns a list of strings from the specified value.

Parameters:

• value (str) – comma delimited string to convert to list.

• itemcast (func) – Function to cast each list item to (default str).

• delim (str) – string delimiter (optional; default ‘,’).

plexapi.utils.downloadSessionImages(server, filename=None, height=150, width=150, opacity=100, saturation=100)

Helper to download a bif image or thumb.url from plex.server.sessions.

Parameters:

• filename (str) – default to None,

• height (int) – Height of the image.

• width (int) – width of the image.

• opacity (int) – Opacity of the resulting image (possibly deprecated).

• saturation (int) – Saturating of the resulting image.

Returns:

{‘filepath’: ‘<filepath>’, ‘url’: ‘http://<url>’}, {‘<username>’: {filepath, url}}, …

Return type:

{‘hellowlol’

plexapi.utils.download(url, token, filename=None, savepath=None, session=None, chunksize=4096, unpack=False, mocked=False, showstatus=False)

Helper to download a thumb, videofile or other media item. Returns the local

path to the downloaded file.

Parameters:

• url (str) – URL where the content be reached.

• token (str) – Plex auth token to include in headers.

• filename (str) – Filename of the downloaded file, default None.

• savepath (str) – Defaults to current working dir.

• chunksize (int) – What chunksize read/write at the time.

• mocked (bool) – Helper to do everything except write the file.

• unpack (bool) – Unpack the zip file.

• showstatus – Display a progressbar.

plexapi.utils.getMyPlexAccount(opts=None)

Helper function tries to get a MyPlex Account instance by checking the the following locations for a username and password. This is useful to create user-friendly command line tools. 1. command-line options (opts). 2. environment variables and config.ini 3. Prompt on the command line.

plexapi.utils.createMyPlexDevice(headers, account, timeout=10)

Helper function to create a new MyPlexDevice. Returns a new MyPlexDevice instance.

Parameters:

• headers (dict) – Provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required.

• account (MyPlexAccount) – The Plex account to create the device on.

• timeout (int) – Timeout in seconds to wait for device login.

plexapi.utils.plexOAuth(headers, forwardUrl=None, timeout=120)

Helper function for Plex OAuth login. Returns a new MyPlexAccount instance.

Parameters:

• headers (dict) – Provide the X-Plex- headers for the new device. A unique X-Plex-Client-Identifier is required.

• forwardUrl (str, optional) – The url to redirect the client to after login.

• timeout (int, optional) – Timeout in seconds to wait for device login. Default 120 seconds.

plexapi.utils.choose(msg, items, attr)

Command line helper to display a list of choices, asking the user to choose one of the options.

plexapi.utils.getAgentIdentifier(section, agent)

Return the full agent identifier from a short identifier, name, or confirm full identifier.

plexapi.utils.iterXMLBFS(root, tag=None)

Iterate through an XML tree using a breadth-first search. If tag is specified, only return nodes with that tag.

plexapi.utils.toJson(obj, **kwargs)

Convert an object to a JSON string.

Parameters:

• obj (object) – The object to convert.

• **kwargs (dict) – Keyword arguments to pass to json.dumps().

plexapi.utils.sha1hash(guid)

Return the SHA1 hash of a guid.