Merge pull request #1 from pkkid/master

Catch-up

Author: nwithan8

.coveragerc

@@ -1,3 +1,8 @@
+[run]
+omit = */site-packages/plexapi/*
+
+
+
 [report]
 exclude_lines =
     pragma: no cover

.flake8

@@ -0,0 +1,16 @@
+# Flake8 configuration
+# Copy or symlink this file to ~/.flake8
+# --------------------------------------
+# E128: continuation line under-indented for visual indent
+# E701: multiple statements on one line (colon)
+# E702: multiple statements on one line (semicolon)
+# E731: do not assign a lambda expression, use a def
+# W293: blank line contains whitespace
+# W503: line break before binary operator
+# W605: invalid escape sequence
+[flake8]
+ignore=E128,E701,E702,E731,W293,W503,W605
+exclude=compat.py
+max-complexity = -1
+max-line-length = 125
+show-source = True

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: bug_report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the issue**
+A clear and concise description of what the issue is.
+
+**Code snipppets**
+Add code snippet to help explain your problem.
+  - please use markdown [Code and Syntax Highlighting](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code-and-syntax-highlighting) for code snippet
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Enviroment (please complete the following information):**
+ - OS: [e.g. Linux, Windows, Docker]
+ - Plex version [eg. version 1.19.3.2852]
+ - Python Version [e.g. 2.7.15, 3.6]
+ - PlexAPI version [e.g. 3.6.0]
+
+**Additional context**
+Add any other context about the issue here.

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,23 @@
+## Description
+
+Please include a summary of the change and which issue is fixed.
+
+Fixes # (issue)
+
+## Type of change
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] This change requires a documentation update
+
+
+## Checklist:
+
+- [ ] My code follows the style guidelines of this project
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have added or updated the docstring for new or existing methods
+- [ ] I have added tests when applicable

.gitignore

@@ -18,8 +18,10 @@ config.ini
 ipython_config.py
 dist
 docs/_build/
+docs/src/
 htmlcov
 include/
 lib/
 pip-selfcheck.json
-pyvenv.cfg
+pyvenv.cfg
+MANIFEST

.readthedocs.yml

@@ -0,0 +1,21 @@
+# .readthedocs.yml
+
+version: 2
+
+build:
+  image: latest
+
+sphinx:
+  configuration: docs/conf.py
+
+formats: all
+
+python:
+   version: 3.7
+   install:
+      - requirements: requirements_dev.txt
+      - method: pip
+        path: .
+
+   system_packages: true
+

.travis.yml

@@ -2,16 +2,13 @@ language: python
 
 stages:
   - test
-  - name: deploy
-    if: tag = present
+  - deploy
 
 sudo: required
 services:
   - docker
 
 python:
-  - 2.7
-  - 3.4
   - 3.6
 
 env:
@@ -23,8 +20,10 @@ env:
 before_install:
   - pip install --upgrade pip
   - pip install --upgrade setuptools
-  - pip install --upgrade pytest pytest-cov coveralls
 install:
+  - pip install .
+  - python -c "import plexapi; print('installation ok')"
+  - pip install --upgrade pytest pytest-cov coveralls
   - pip install -r requirements_dev.txt
   - '[ -z "${PLEXAPI_AUTH_MYPLEX_USERNAME}" ] && PYTHONPATH="$PWD:$PYTHONPATH" python -u tools/plex-bootstraptest.py
      --destination plex --advertise-ip=127.0.0.1 --bootstrap-timeout 540 --docker-tag $PLEX_CONTAINER_TAG --unclaimed ||
@@ -43,6 +42,10 @@ after_success:
 after_script:
   - '[ -z "${PLEXAPI_AUTH_MYPLEX_USERNAME}" ] || PYTHONPATH="$PWD:$PYTHONPATH" python -u tools/plex-teardowntest.py'
 
+
+notifications:
+  webhooks: https://coveralls.io/webhook
+
 jobs:
   include:
     - python: 3.6
@@ -56,7 +59,7 @@ jobs:
     - stage: test
       python: 3.6
       env:
-        - PLEX_CONTAINER_TAG=1.10.1.4602-f54242b6b
+        - PLEX_CONTAINER_TAG=latest
         - TEST_ACCOUNT_ONCE=1
     - stage: test
       python: 3.6
@@ -73,8 +76,8 @@ jobs:
         - PLEX_CONTAINER_TAG=latest
       deploy:
         provider: pypi
-        user: mjs7231
+        user: hellowlol
         password:
-          secure: UhuEN9GAp9zMEXdVTxSrbhfYf4HjTcj47l093Qh1HYKmZACxJM/+JkQCm7+oHPJpo7YDLk2we9oEsQ41maZBr9WgZI1lwR6m590M12vPhPI7NCVzINxJqebc0uZhCFsAFFKA3kzpRQbDfsBUG4yL/AzeMcvJMgIg3m07KRVhBywnnRhQ77trbBI0Io5MBzfW9PYDeGJqlNDBM7SbB4tK0udGZQT9wmFwvIoJODPDnM15Ry4vpkVNww/vVgyHklmnYlPzQgvhSMOXk0+MWlYtaKmu6uuLAiRccT1Fsmi1POKuFEq8S0Z7w4LmwxCVRaCvsZdNW5eXWgPDhZXNcLrKMwjgJt9Vj3VcD+NCywux/C1hTq7tecBocA13kzbgg4fd2sATOjQT5iaRPGrDtKm8e00hxr125n0StDxXdYGl2W5sH0LCkZE6Vq1GjXYjKFXZeTk3Fzav/3N8IxHBX3CliJB/vbloJ2mpz1kXL4UTORl9pghPyGOOq2yJPYSSWly/RsAD7UDrL1/lezaPSJGKbZJ0CMyfA83kd82/hgZflOuBuTcPHCZSU3zMCs0fsImZZxr6Qm1tbff+iyNS/ufoYgeVfsWhlEl9FoLv1g4HG6oA+uDHz+jKz9uSRHcGqD6P4JJK+H+yy0PeYfo7b6eSqFxgt8q8QfifUaCrVoCiY+c=
+          secure: cwMf16s+PxIUjt6/pKE7KeQPsWg4Atf9JvipkLTjx1VrVBilSjrZ7fkSDDjglkz4sCynw5/fzQRkBWqLdyqPigwKICYbpc6QWwvR+WWQLfe04zl+d4AmDljN2rtNkThlpH2qKNaFX7Up3AAcTf+GtQ7weAAyjMyJaiWBTFcgc2eBMDgEkS3bhiF4qdbfdAYbHVurJwCWXfHjkIiBJxDHA15cQRhJpkqQGIYzAst6ZwEr/Aw9FwqfC3lvFM3uIQ7sfFa/UdIesQZ50IT//roI1bvTg2T4gAMRYMs09jFm1E5mnPn4qxvK2hzsiNNesw3wSXhCehJFym8cO5jX+EYnfNJuWJtappIZeJGKldVC2g2v3PNWhmqbbKnyc446rkPtjVQqrSSUjPNOhTG61n872JVnizopo8ISDAtceSoC/mySItzjRQnRDrelkhHdV33WSyOsJKTw0H2LzjZDQRxxTqABmmCwzn7h+ycQ2Xk2INu9gt0hgIOco6Lt6VeoDMXhD6wAGDAaD7XBQwD/JSbGZns3VIgoLMxyHda9S6UeDmwwoAWhHM0mbzt0L618R+7CK0E+3vQ2k2Ee23tKIOq7DvZMpmLLjUE3wlckoKCPDrgP7Tuf5nUoz6kWv3Hxsb0wZCuVO0npSCFx+JOSQ6/7ONU4eh3hvjnnb6vqAgKqQ80=
         on:
           tags: true

README.rst

@@ -6,6 +6,12 @@ Python-PlexAPI
     :target: https://travis-ci.org/pkkid/python-plexapi
 .. image:: https://coveralls.io/repos/github/pkkid/python-plexapi/badge.svg?branch=master
     :target: https://coveralls.io/github/pkkid/python-plexapi?branch=master
+.. 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
@@ -15,7 +21,7 @@ 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.
+* Remote control and play media on connected clients, including `Controlling Sonos speakers`_
 * Listen in on all Plex Server notifications.
 
 
@@ -118,48 +124,76 @@ Usage Examples
 
 .. code-block:: python
 
-    # Example 8: Get a URL to stream a movie or show in another client
-    die_hard = plex.library.section('Movies').get('Elephants Dream')
-    print('Run running the following command to play in VLC:')
-    print('vlc "%s"' % die_hard.getStreamURL(videoResolution='800x600'))
+    # Example 8: Get audio/video/all playlists
+    for playlist in plex.playlists():
+        print(playlist.title)
 
 
 .. code-block:: python
 
-    # Example 9: Get audio/video/all playlists
-    for playlist in plex.playlists():
-        print(playlist.title)
+    # 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
 --------------------------
 
-In order to test the PlexAPI library you have to prepare a Plex Server instance with following libraries:
-
-1. Movies section (agent `com.plexapp.agents.imdb`) containing both movies:
-    * Sintel - https://durian.blender.org/
-    * Elephants Dream - https://orange.blender.org/
-    * Sita Sings the Blues - http://www.sitasingstheblues.com/
-    * Big Buck Bunny - https://peach.blender.org/
-2. TV Show section (agent `com.plexapp.agents.thetvdb`) containing the shows:
-    * Game of Thrones (Season 1 and 2)
-    * The 100 (Seasons 1 and 2)
-    * (or symlink the above movies with proper names)
-3. Music section (agent `com.plexapp.agents.lastfm`) containing the albums:
-    * Infinite State - Unmastered Impulses - https://github.com/kennethreitz/unmastered-impulses
-    * Broke For Free - Layers - http://freemusicarchive.org/music/broke_for_free/Layers/
-4. A Photos section (any agent) containing the photoalbums (photoalbum is just a folder on your disk):
-    * `Cats`
-    * Within `Cats` album you need to place 3 photos (cute cat photos, of course)
-    * Within `Cats` album you should place 3 more photoalbums (one of them should be named `Cats in bed`,
-      names of others doesn't matter)
-    * Within `Cats in bed` you need to place 7 photos
-    * Within other 2 albums you should place 1 photo in each
-
-Instead of manual creation of the library you could use a script `tools/plex-boostraptest.py` with appropriate
+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 veriable `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-boostraptest.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

docs/conf.py

@@ -60,8 +60,8 @@ def new_resolve_xref(*args):
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
 # source_suffix = '.rst'
-source_parsers = {'.md': CommonMarkParser}
-source_suffix = ['.rst', '.md']
+# source_parsers = {'.md': CommonMarkParser}  # deprecated
+# source_suffix = ['.rst', '.md']  # deprecated
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'

docs/modules/gdm.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+Gdm :modname:`plexapi.gdm`
+--------------------------------
+.. automodule:: plexapi.gdm
+    :members:
+    :show-inheritance:

docs/modules/sonos.rst

@@ -0,0 +1,7 @@
+.. include:: ../global.rst
+
+Sonos :modname:`plexapi.sonos`
+--------------------------------
+.. automodule:: plexapi.sonos
+    :members:
+    :show-inheritance:

docs/toc.rst

@@ -17,6 +17,7 @@
    modules/client
    modules/config
    modules/exceptions
+   modules/gdm
    modules/library
    modules/media
    modules/myplex
@@ -25,6 +26,8 @@
    modules/playqueue
    modules/server
    modules/settings
+   modules/sonos
    modules/sync
    modules/utils
    modules/video
+

package.json

@@ -0,0 +1,5 @@
+{
+  "scripts": {
+    "pypi": "python setup.py sdist upload"
+  }
+}

plexapi/__init__.py

@@ -3,9 +3,10 @@
 import os
 from logging.handlers import RotatingFileHandler
 from platform import uname
+from uuid import getnode
+
 from plexapi.config import PlexConfig, reset_base_headers
 from plexapi.utils import SecretsFilter
-from uuid import getnode
 
 # Load User Defined Config
 DEFAULT_CONFIG_PATH = os.path.expanduser('~/.config/plexapi/config.ini')
@@ -14,7 +15,7 @@
 
 # PlexAPI Settings
 PROJECT = 'PlexAPI'
-VERSION = '3.1.0'
+VERSION = '4.0.0'
 TIMEOUT = CONFIG.get('plexapi.timeout', 30, int)
 X_PLEX_CONTAINER_SIZE = CONFIG.get('plexapi.container_size', 100, int)
 X_PLEX_ENABLE_FAST_CONNECT = CONFIG.get('plexapi.enable_fast_connect', False, bool)