Python-PlexAPI
==============
.. image:: https://github.com/pkkid/python-plexapi/workflows/CI/badge.svg
:target: https://github.com/pkkid/python-plexapi/actions?query=workflow%3ACI
.. image:: https://readthedocs.org/projects/python-plexapi/badge/?version=latest
:target: http://python-plexapi.readthedocs.io/en/latest/?badge=latest
.. image:: https://codecov.io/gh/pkkid/python-plexapi/branch/master/graph/badge.svg?token=fOECznuMtw
:target: https://codecov.io/gh/pkkid/python-plexapi
.. image:: https://img.shields.io/github/tag/pkkid/python-plexapi.svg?label=github+release
:target: https://github.com/pkkid/python-plexapi/releases
.. image:: https://badge.fury.io/py/PlexAPI.svg
:target: https://badge.fury.io/py/PlexAPI
.. image:: https://img.shields.io/github/last-commit/pkkid/python-plexapi.svg
:target: https://img.shields.io/github/last-commit/pkkid/python-plexapi.svg
Overview
--------
Unofficial Python bindings for the Plex API. Our goal is to match all capabilities of the official
Plex Web Client. A few of the many features we currently support are:
* Navigate local or remote shared libraries.
* Perform library actions such as scan, analyze, empty trash.
* Remote control and play media on connected clients, including `Controlling Sonos speakers`_
* Listen in on all Plex Server notifications.
Installation & Documentation
----------------------------
.. code-block:: python
pip install plexapi
*Install extra features:*
.. code-block:: python
pip install plexapi[alert] # Install with dependencies required for plexapi.alert
Documentation_ can be found at Read the Docs.
.. _Documentation: http://python-plexapi.readthedocs.io/en/latest/
Join our Discord_ for support and discussion.
.. _Discord: https://discord.gg/GtAnnZAkuw
Getting a PlexServer Instance
-----------------------------
There are two types of authentication. If you are running on a separate network
or using Plex Users you can log into MyPlex to get a PlexServer instance. An
example of this is below. NOTE: Servername below is the name of the server (not
the hostname and port). If logged into Plex Web you can see the server name in
the top left above your available libraries.
.. code-block:: python
from plexapi.myplex import MyPlexAccount
account = MyPlexAccount('<USERNAME>', '<PASSWORD>')
plex = account.resource('<SERVERNAME>').connect() # returns a PlexServer instance
If you want to avoid logging into MyPlex and you already know your auth token
string, you can use the PlexServer object directly as above, by passing in
the baseurl and auth token directly.
.. code-block:: python
from plexapi.server import PlexServer
baseurl = 'http://plexserver:32400'
token = '2ffLuB84dqLswk9skLos'
plex = PlexServer(baseurl, token)
Usage Examples
--------------
.. code-block:: python
# Example 1: List all unwatched movies.
movies = plex.library.section('Movies')
for video in movies.search(unwatched=True):
print(video.title)
.. code-block:: python
# Example 2: Mark all Game of Thrones episodes as played.
plex.library.section('TV Shows').get('Game of Thrones').markPlayed()
.. code-block:: python
# Example 3: List all clients connected to the Server.
for client in plex.clients():
print(client.title)
.. code-block:: python
# Example 4: Play the movie Cars on another client.
# Note: Client must be on same network as server.
cars = plex.library.section('Movies').get('Cars')
client = plex.client("Michael's iPhone")
client.playMedia(cars)
.. code-block:: python
# Example 5: List all content with the word 'Game' in the title.
for video in plex.search('Game'):
print(f'{video.title} ({video.TYPE})')
.. code-block:: python
# Example 6: List all movies directed by the same person as Elephants Dream.
movies = plex.library.section('Movies')
elephants_dream = movies.get('Elephants Dream')
director = elephants_dream.directors[0]
for movie in movies.search(None, director=director):
print(movie.title)
.. code-block:: python
# Example 7: List files for the latest episode of The 100.
last_episode = plex.library.section('TV Shows').get('The 100').episodes()[-1]
for part in last_episode.iterParts():
print(part.file)
.. code-block:: python
# Example 8: Get audio/video/all playlists
for playlist in plex.playlists():
print(playlist.title)
.. code-block:: python
# Example 9: Rate the 100 four stars.
plex.library.section('TV Shows').get('The 100').rate(8.0)
Controlling Sonos speakers
--------------------------
To control Sonos speakers directly using Plex APIs, the following requirements must be met:
1. Active Plex Pass subscription
2. Sonos account linked to Plex account
3. Plex remote access enabled
Due to the design of Sonos music services, the API calls to control Sonos speakers route through https://sonos.plex.tv
and back via the Plex server's remote access. Actual media playback is local unless networking restrictions prevent the
Sonos speakers from connecting to the Plex server directly.
.. code-block:: python
from plexapi.myplex import MyPlexAccount
from plexapi.server import PlexServer
baseurl = 'http://plexserver:32400'
token = '2ffLuB84dqLswk9skLos'
account = MyPlexAccount(token)
server = PlexServer(baseurl, token)
# List available speakers/groups
for speaker in account.sonos_speakers():
print(speaker.title)
# Obtain PlexSonosPlayer instance
speaker = account.sonos_speaker("Kitchen")
album = server.library.section('Music').get('Stevie Wonder').album('Innervisions')
# Speaker control examples
speaker.playMedia(album)
speaker.pause()
speaker.setVolume(10)
speaker.skipNext()
Running tests over PlexAPI
--------------------------
Use:
.. code-block:: bash
tools/plex-boostraptest.py
with appropriate
arguments and add this new server to a shared user which username is defined in environment variable `SHARED_USERNAME`.
It uses `official docker image`_ to create a proper instance.
For skipping the docker and reuse a existing server use
.. code-block:: bash
python plex-bootstraptest.py --no-docker --username USERNAME --password PASSWORD --server-name NAME-OF-YOUR-SEVER
Also in order to run most of the tests you have to provide some environment variables:
* `PLEXAPI_AUTH_SERVER_BASEURL` containing an URL to your Plex instance, e.g. `http://127.0.0.1:32400` (without trailing
slash)
* `PLEXAPI_AUTH_MYPLEX_USERNAME` and `PLEXAPI_AUTH_MYPLEX_PASSWORD` with your MyPlex username and password accordingly
After this step you can run tests with following command:
.. code-block:: bash
py.test tests -rxXs --ignore=tests/test_sync.py
Some of the tests in main test-suite require a shared user in your account (e.g. `test_myplex_users`,
`test_myplex_updateFriend`, etc.), you need to provide a valid shared user's username to get them running you need to
provide the username of the shared user as an environment variable `SHARED_USERNAME`. You can enable a Guest account and
simply pass `Guest` as `SHARED_USERNAME` (or just create a user like `plexapitest` and play with it).
To be able to run tests over Mobile Sync api you have to some some more environment variables, to following values
exactly:
* PLEXAPI_HEADER_PROVIDES='controller,sync-target'
* PLEXAPI_HEADER_PLATFORM=iOS
* PLEXAPI_HEADER_PLATFORM_VERSION=11.4.1
* PLEXAPI_HEADER_DEVICE=iPhone
And finally run the sync-related tests:
.. code-block:: bash
py.test tests/test_sync.py -rxXs
.. _official docker image: https://hub.docker.com/r/plexinc/pms-docker/
Common Questions
----------------
**Why are you using camelCase and not following PEP8 guidelines?**
This API reads XML documents provided by MyPlex and the Plex Server.
We decided to conform to their style so that the API variable names directly
match with the provided XML documents.
**Why don't you offer feature XYZ?**
This library is meant to be a wrapper around the XML pages the Plex
server provides. If we are not providing an API that is offered in the
XML pages, please let us know! -- Adding additional features beyond that
should be done outside the scope of this library.
**What are some helpful links if trying to understand the raw Plex API?**
* https://github.com/plexinc/plex-media-player/wiki/Remote-control-API
* https://forums.plex.tv/discussion/104353/pms-web-api-documentation
* https://github.com/Arcanemagus/plex-api/wiki
Raw data
{
"_id": null,
"home_page": "https://github.com/pkkid/python-plexapi",
"name": "PlexAPI",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "plex, api",
"author": "Michael Shepanski",
"author_email": "michael.shepanski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ea/36/8c0f73b8a74cf7138ecf19ff65053892599bba1d2f771d2c33ad8dc690bd/PlexAPI-4.15.12.tar.gz",
"platform": null,
"description": "Python-PlexAPI\n==============\n.. image:: https://github.com/pkkid/python-plexapi/workflows/CI/badge.svg\n :target: https://github.com/pkkid/python-plexapi/actions?query=workflow%3ACI\n.. image:: https://readthedocs.org/projects/python-plexapi/badge/?version=latest\n :target: http://python-plexapi.readthedocs.io/en/latest/?badge=latest\n.. image:: https://codecov.io/gh/pkkid/python-plexapi/branch/master/graph/badge.svg?token=fOECznuMtw\n :target: https://codecov.io/gh/pkkid/python-plexapi\n.. image:: https://img.shields.io/github/tag/pkkid/python-plexapi.svg?label=github+release\n :target: https://github.com/pkkid/python-plexapi/releases\n.. image:: https://badge.fury.io/py/PlexAPI.svg\n :target: https://badge.fury.io/py/PlexAPI\n.. image:: https://img.shields.io/github/last-commit/pkkid/python-plexapi.svg\n :target: https://img.shields.io/github/last-commit/pkkid/python-plexapi.svg\n\n\nOverview\n--------\nUnofficial Python bindings for the Plex API. Our goal is to match all capabilities of the official\nPlex Web Client. A few of the many features we currently support are:\n\n* Navigate local or remote shared libraries.\n* Perform library actions such as scan, analyze, empty trash.\n* Remote control and play media on connected clients, including `Controlling Sonos speakers`_\n* Listen in on all Plex Server notifications.\n\n\nInstallation & Documentation\n----------------------------\n\n.. code-block:: python\n\n pip install plexapi\n\n*Install extra features:*\n\n.. code-block:: python\n\n pip install plexapi[alert] # Install with dependencies required for plexapi.alert\n\nDocumentation_ can be found at Read the Docs.\n\n.. _Documentation: http://python-plexapi.readthedocs.io/en/latest/\n\nJoin our Discord_ for support and discussion.\n\n.. _Discord: https://discord.gg/GtAnnZAkuw\n\n\nGetting a PlexServer Instance\n-----------------------------\n\nThere are two types of authentication. If you are running on a separate network\nor using Plex Users you can log into MyPlex to get a PlexServer instance. An\nexample of this is below. NOTE: Servername below is the name of the server (not\nthe hostname and port). If logged into Plex Web you can see the server name in\nthe top left above your available libraries.\n\n.. code-block:: python\n\n from plexapi.myplex import MyPlexAccount\n account = MyPlexAccount('<USERNAME>', '<PASSWORD>')\n plex = account.resource('<SERVERNAME>').connect() # returns a PlexServer instance\n\nIf you want to avoid logging into MyPlex and you already know your auth token\nstring, you can use the PlexServer object directly as above, by passing in\nthe baseurl and auth token directly.\n\n.. code-block:: python\n\n from plexapi.server import PlexServer\n baseurl = 'http://plexserver:32400'\n token = '2ffLuB84dqLswk9skLos'\n plex = PlexServer(baseurl, token)\n\n\nUsage Examples\n--------------\n\n.. code-block:: python\n\n # Example 1: List all unwatched movies.\n movies = plex.library.section('Movies')\n for video in movies.search(unwatched=True):\n print(video.title)\n\n\n.. code-block:: python\n\n # Example 2: Mark all Game of Thrones episodes as played.\n plex.library.section('TV Shows').get('Game of Thrones').markPlayed()\n\n\n.. code-block:: python\n\n # Example 3: List all clients connected to the Server.\n for client in plex.clients():\n print(client.title)\n\n\n.. code-block:: python\n\n # Example 4: Play the movie Cars on another client.\n # Note: Client must be on same network as server.\n cars = plex.library.section('Movies').get('Cars')\n client = plex.client(\"Michael's iPhone\")\n client.playMedia(cars)\n\n\n.. code-block:: python\n\n # Example 5: List all content with the word 'Game' in the title.\n for video in plex.search('Game'):\n print(f'{video.title} ({video.TYPE})')\n\n\n.. code-block:: python\n\n # Example 6: List all movies directed by the same person as Elephants Dream.\n movies = plex.library.section('Movies')\n elephants_dream = movies.get('Elephants Dream')\n director = elephants_dream.directors[0]\n for movie in movies.search(None, director=director):\n print(movie.title)\n\n\n.. code-block:: python\n\n # Example 7: List files for the latest episode of The 100.\n last_episode = plex.library.section('TV Shows').get('The 100').episodes()[-1]\n for part in last_episode.iterParts():\n print(part.file)\n\n\n.. code-block:: python\n\n # Example 8: Get audio/video/all playlists\n for playlist in plex.playlists():\n print(playlist.title)\n\n\n.. code-block:: python\n\n # Example 9: Rate the 100 four stars.\n plex.library.section('TV Shows').get('The 100').rate(8.0)\n\n\nControlling Sonos speakers\n--------------------------\n\nTo control Sonos speakers directly using Plex APIs, the following requirements must be met:\n\n1. Active Plex Pass subscription\n2. Sonos account linked to Plex account\n3. Plex remote access enabled\n\nDue to the design of Sonos music services, the API calls to control Sonos speakers route through https://sonos.plex.tv\nand back via the Plex server's remote access. Actual media playback is local unless networking restrictions prevent the\nSonos speakers from connecting to the Plex server directly.\n\n.. code-block:: python\n\n from plexapi.myplex import MyPlexAccount\n from plexapi.server import PlexServer\n\n baseurl = 'http://plexserver:32400'\n token = '2ffLuB84dqLswk9skLos'\n\n account = MyPlexAccount(token)\n server = PlexServer(baseurl, token)\n\n # List available speakers/groups\n for speaker in account.sonos_speakers():\n print(speaker.title)\n\n # Obtain PlexSonosPlayer instance\n speaker = account.sonos_speaker(\"Kitchen\")\n\n album = server.library.section('Music').get('Stevie Wonder').album('Innervisions')\n\n # Speaker control examples\n speaker.playMedia(album)\n speaker.pause()\n speaker.setVolume(10)\n speaker.skipNext()\n\n\nRunning tests over PlexAPI\n--------------------------\n\nUse:\n\n.. code-block:: bash\n\n tools/plex-boostraptest.py \n\nwith appropriate\narguments and add this new server to a shared user which username is defined in environment variable `SHARED_USERNAME`.\nIt uses `official docker image`_ to create a proper instance.\n\nFor skipping the docker and reuse a existing server use \n\n.. code-block:: bash\n\n python plex-bootstraptest.py --no-docker --username USERNAME --password PASSWORD --server-name NAME-OF-YOUR-SEVER\n\nAlso in order to run most of the tests you have to provide some environment variables:\n\n* `PLEXAPI_AUTH_SERVER_BASEURL` containing an URL to your Plex instance, e.g. `http://127.0.0.1:32400` (without trailing\n slash)\n* `PLEXAPI_AUTH_MYPLEX_USERNAME` and `PLEXAPI_AUTH_MYPLEX_PASSWORD` with your MyPlex username and password accordingly\n\nAfter this step you can run tests with following command:\n\n.. code-block:: bash\n\n py.test tests -rxXs --ignore=tests/test_sync.py\n\nSome of the tests in main test-suite require a shared user in your account (e.g. `test_myplex_users`,\n`test_myplex_updateFriend`, etc.), you need to provide a valid shared user's username to get them running you need to\nprovide the username of the shared user as an environment variable `SHARED_USERNAME`. You can enable a Guest account and\nsimply pass `Guest` as `SHARED_USERNAME` (or just create a user like `plexapitest` and play with it).\n\nTo be able to run tests over Mobile Sync api you have to some some more environment variables, to following values\nexactly:\n\n* PLEXAPI_HEADER_PROVIDES='controller,sync-target'\n* PLEXAPI_HEADER_PLATFORM=iOS\n* PLEXAPI_HEADER_PLATFORM_VERSION=11.4.1\n* PLEXAPI_HEADER_DEVICE=iPhone\n\nAnd finally run the sync-related tests:\n\n.. code-block:: bash\n\n py.test tests/test_sync.py -rxXs\n\n.. _official docker image: https://hub.docker.com/r/plexinc/pms-docker/\n\nCommon Questions\n----------------\n\n**Why are you using camelCase and not following PEP8 guidelines?**\n\nThis API reads XML documents provided by MyPlex and the Plex Server.\nWe decided to conform to their style so that the API variable names directly\nmatch with the provided XML documents.\n\n\n**Why don't you offer feature XYZ?**\n\nThis library is meant to be a wrapper around the XML pages the Plex\nserver provides. If we are not providing an API that is offered in the\nXML pages, please let us know! -- Adding additional features beyond that\nshould be done outside the scope of this library.\n\n\n**What are some helpful links if trying to understand the raw Plex API?**\n\n* https://github.com/plexinc/plex-media-player/wiki/Remote-control-API\n* https://forums.plex.tv/discussion/104353/pms-web-api-documentation\n* https://github.com/Arcanemagus/plex-api/wiki\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Python bindings for the Plex API.",
"version": "4.15.12",
"project_urls": {
"Homepage": "https://github.com/pkkid/python-plexapi"
},
"split_keywords": [
"plex",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2f7fa593ff122c1aee841a80f8b392e31e0932bbf7514e46595b29ec16ca5144",
"md5": "7b93511bb786d1075c9ff483bf20b734",
"sha256": "1babe7184cc30eb6695886ec192281d2cd859fde0cd72c8f3a3b2a50cb650fea"
},
"downloads": -1,
"filename": "PlexAPI-4.15.12-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b93511bb786d1075c9ff483bf20b734",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 163065,
"upload_time": "2024-04-19T20:25:27",
"upload_time_iso_8601": "2024-04-19T20:25:27.535595Z",
"url": "https://files.pythonhosted.org/packages/2f/7f/a593ff122c1aee841a80f8b392e31e0932bbf7514e46595b29ec16ca5144/PlexAPI-4.15.12-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea368c0f73b8a74cf7138ecf19ff65053892599bba1d2f771d2c33ad8dc690bd",
"md5": "a9dd2b39d72c8e7f5721228661588218",
"sha256": "9c254492a46ccefea6efc5ca2132d60c66de10fb3007c45d06a5fb6ee525f5f1"
},
"downloads": -1,
"filename": "PlexAPI-4.15.12.tar.gz",
"has_sig": false,
"md5_digest": "a9dd2b39d72c8e7f5721228661588218",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 151865,
"upload_time": "2024-04-19T20:25:30",
"upload_time_iso_8601": "2024-04-19T20:25:30.253203Z",
"url": "https://files.pythonhosted.org/packages/ea/36/8c0f73b8a74cf7138ecf19ff65053892599bba1d2f771d2c33ad8dc690bd/PlexAPI-4.15.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 20:25:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pkkid",
"github_project": "python-plexapi",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": []
}
],
"lcname": "plexapi"
}
JSON
