From 1bf09cb86362367f5d12cdbb9bfbb36b8c67c7a0 Mon Sep 17 00:00:00 2001 From: Michael Shepanski Date: Mon, 20 Feb 2017 14:50:02 -0500 Subject: [PATCH] Convert README to rst to allow import into docs --- README.md | 126 ---------------------------------- README.rst | 152 ++++++++++++++++++++++++++++++++++++++++++ docs/introduction.rst | 146 +--------------------------------------- setup.py | 34 +++++----- tests/test_misc.py | 8 +-- 5 files changed, 175 insertions(+), 291 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 56b33f7b..00000000 --- a/README.md +++ /dev/null @@ -1,126 +0,0 @@ -## PlexAPI ## - - - - Coverage Status - - - - Documentation Status -Python bindings for the Plex API. - -* Navigate local or remote shared libraries. -* Mark shows watched or unwatched. -* Request rescan, analyze, empty trash. -* Play media on connected clients. -* Get URL to stream stream h264/aac video (playable in VLC,MPV,etc). -* Plex Sync Support. -* Plex Audio Support. - -#### Install ### - - pip install plexapi - - -#### 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. - -```python -from plexapi.myplex import MyPlexAccount -account = MyPlexAccount('', '') -plex = account.resource('').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, but passing in -the baseurl and auth token directly. - -```python -from plexapi.server import PlexServer -baseurl = 'http://plexserver:32400' -token = '2ffLuB84dqLswk9skLos' -plex = PlexServer(baseurl, token) -``` - - -#### Usage Examples #### - -```python -# Example 1: List all unwatched movies. -movies = plex.library.section('Movies') -for video in movies.search(unwatched=True): - print(video.title) -``` -```python -# Example 2: Mark all Game of Thrones episodes watched. -plex.library.section('TV Shows').get('Game of Thrones').markWatched() -``` -```python -# Example 3: List all clients connected to the Server. -for client in plex.clients(): - print(client.title) -``` -```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) -``` -```python -# Example 5: List all content with the word 'Game' in the title. -for video in plex.search('Game'): - print('%s (%s)' % (video.title, video.TYPE)) -``` -```python -# Example 6: List all movies directed by the same person as Die Hard. -movies = plex.library.section('Movies') -die_hard = movies.get('Die Hard') -director = die_hard.directors[0] -for movie in movies.search(None, director=director): - print(movie.title) -``` -```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) -``` -```python -# Example 8: Get a URL to stream a movie or show in another client -die_hard = plex.library.section('Movies').get('Die Hard') -print('Run running the following command to play in VLC:') -print('vlc "%s"' % die_hard.getStreamURL(videoResolution='800x600')) -``` -```python -# Example 9: Get audio/video/all playlists -for playlist in plex.playlists(): - print(playlist.title) -``` - -#### FAQs #### - -**Q. Why are you using camelCase and not following PEP8 guidelines?** - -A. 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. - - -**Q. Why don't you offer feature XYZ?** - -A. 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 offerered in the -XML pages, please let us know! -- Adding additional features beyond that -should be done outside the scope of this library. - -**Q. 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 diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..1ad95aca --- /dev/null +++ b/README.rst @@ -0,0 +1,152 @@ +Python-PlexAPI +============== +.. image:: https://readthedocs.org/projects/python-plexapi/badge/?version=latest + :target: http://python-plexapi.readthedocs.io/en/latest/?badge=latest +.. image:: https://travis-ci.org/pkkid/python-plexapi.svg?branch=3.0.0 + :target: https://travis-ci.org/pkkid/python-plexapi +.. image:: https://coveralls.io/repos/github/pkkid/python-plexapi/badge.svg?branch=3.0.0 + :target: https://coveralls.io/github/pkkid/python-plexapi?branch=3.0.0 + + +Overview +-------- +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. +* Listen in on all Plex Server notifications. + + +Installation +------------ + +.. code-block:: python + + pip install plexapi + + +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('', '') + plex = account.resource('').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, but 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 watched. + plex.library.section('TV Shows').get('Game of Thrones').markWatched() + + +.. 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('%s (%s)' % (video.title, video.TYPE)) + + +.. code-block:: python + + # Example 6: List all movies directed by the same person as Die Hard. + movies = plex.library.section('Movies') + die_hard = movies.get('Die Hard') + director = die_hard.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 a URL to stream a movie or show in another client + die_hard = plex.library.section('Movies').get('Die Hard') + print('Run running the following command to play in VLC:') + print('vlc "%s"' % die_hard.getStreamURL(videoResolution='800x600')) + + +.. code-block:: python + + # Example 9: Get audio/video/all playlists + for playlist in plex.playlists(): + print(playlist.title) + + +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 offerered 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 diff --git a/docs/introduction.rst b/docs/introduction.rst index b0654424..6b2b3ec6 100644 --- a/docs/introduction.rst +++ b/docs/introduction.rst @@ -1,145 +1 @@ -Getting Started -=============== - -.. |br| raw:: html - -
- -Python bindings for the Plex API. - -* Navigate local or remote shared libraries. -* Mark shows watched or unwatched. -* Request rescan, analyze, empty trash. -* Play media on connected clients. -* Get URL to stream stream h264/aac video (playable in VLC,MPV,etc). -* Plex Sync Support. -* Plex Audio Support. - -Installation ------------- - -.. code-block:: python - - pip install plexapi - - -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.signin('', '') - plex = account.resource('').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, but 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 Conan episodes watched. - plex.library.get('Conan (2010)').markWatched() - - -.. 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 Avatar on another client. - # Note: Client must be on same network as server. - avatar = plex.library.section('Movies').get('Avatar') - client = plex.client("Michael's iPhone") - client.playMedia(avatar) - - -.. code-block:: python - - # Example 5: List all content with the word 'Game' in the title. - for video in plex.search('Game'): - print('%s (%s)' % (video.title, video.TYPE)) - - -.. code-block:: python - - # Example 6: List all movies directed by the same person as Jurassic Park. - movies = plex.library.section('Movies') - jurassic_park = movies.get('Jurassic Park') - director = jurassic_park.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 Friends. - thelastone = plex.library.get('Friends').episodes()[-1] - for part in thelastone.iterParts(): - print(part.file) - - -.. code-block:: python - - # Example 8: Get a URL to stream a movie or show in another client - jurassic_park = plex.library.section('Movies').get('Jurassic Park') - print 'Run running the following command to play in VLC:' - print 'vlc "%s"' % jurassic_park.getStreamUrl(videoResolution='800x600') - - -.. code-block:: python - - # Example 9: Get audio/video/all playlists - for playlist in self.plex.playlists(): - print(playlist.title) - - -FAQs ----- - -**Q. Why are you using camelCase and not following PEP8 guidelines?** |br| -A. 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. - - -**Q. Why don't you offer feature XYZ?** |br| -A. 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 offerered in the -XML pages, please let us know! -- Adding additional features beyond that -should be done outside the scope of this library. - - -**Q. What are some helpful links if trying to understand the raw Plex API?** |br| -https://github.com/plexinc/plex-media-player/wiki/Remote-control-API |br| -https://forums.plex.tv/discussion/104353/pms-web-api-documentation |br| -https://github.com/Arcanemagus/plex-api/wiki |br| +.. include:: ../README.rst \ No newline at end of file diff --git a/setup.py b/setup.py index f1de49e7..734aac57 100644 --- a/setup.py +++ b/setup.py @@ -6,30 +6,32 @@ Install PlexAPI import re from distutils.core import setup -# Convert markdown readme to rst -try: - from pypandoc import convert - read_md = lambda f: convert(f, 'rst') -except ImportError: - print("Warn: pypandoc not found, not converting Markdown to RST") - read_md = lambda f: open(f, 'r').read() - - -# Fetch the current version +# Get the current version with open('plexapi/__init__.py') as handle: for line in handle.readlines(): if line.startswith('VERSION'): - VERSION = re.findall("'([0-9\.]+?)'", line)[0] + version = re.findall("'([0-9\.]+?)'", line)[0] + +# Get README.rst contents +readme = open('README.rst', 'r').read() + +# Get requirments +requirements = [] +with open('requirements.txt') as handle: + for line in handle.readlines(): + if not line.startswith('#'): + package = line.strip().split('=', 1)[0] + requirements.append(package) setup( name='PlexAPI', - version=VERSION, + version=version, description='Python bindings for the Plex API.', author='Michael Shepanski', - author_email='mjs7231@gmail.com', - url='https://github.com/mjs7231/plexapi', + author_email='michael.shepanski@gmail.com', + url='https://github.com/pkkid/plexapi', packages=['plexapi'], - install_requires=['requests'], - long_description=read_md('README.md'), + install_requires=requirements, + long_description=readme, keywords=['plex', 'api'], ) diff --git a/tests/test_misc.py b/tests/test_misc.py index 5c7fc133..31a34141 100644 --- a/tests/test_misc.py +++ b/tests/test_misc.py @@ -3,7 +3,6 @@ import os import pytest import shlex import subprocess -from collections import defaultdict from os.path import abspath, dirname, join SKIP_EXAMPLES = ['Example 4'] @@ -21,7 +20,7 @@ def test_build_documentation(): def test_readme_examples(pms): failed = 0 examples = _fetch_examples(pms) - assert len(examples), 'No examples found in README.md' + assert len(examples), 'No examples found in README' for title, example in examples: if _check_run_example(title): try: @@ -36,14 +35,15 @@ def test_readme_examples(pms): def _fetch_examples(pms): parsing = False examples = [] - filepath = join(dirname(dirname(abspath(__file__))), 'README.md') + filepath = join(dirname(dirname(abspath(__file__))), 'README.rst') with open(filepath, 'r') as handle: for line in handle.read().split('\n'): + line = line[4:] if line.startswith('# Example '): parsing = True title = line.lstrip('# ') examples.append([title, ['plex = pms']]) - elif parsing and line == '```': + elif parsing and line == '': parsing = False elif parsing: examples[-1][1].append(line)