Improvements in tests process

.travis.yml

@@ -1,27 +1,72 @@
-language:
-- python
+language: python
+
+stages:
+  - test
+  - name: deploy
+    if: tag IS present
+
+sudo: required
+services:
+  - docker
+
 python:
-- '2.7'
-- '3.4'
-- '3.6'
+  - 2.7
+  - 3.4
+  - 3.6
+
+env:
+  global:
+    - PLEXAPI_AUTH_SERVER_BASEURL=http://127.0.0.1:32400
+  matrix:
+    - PLEX_CONTAINER_TAG=latest
+
 before_install:
-- pip install --upgrade pip
-- pip install --upgrade setuptools
-- pip install --upgrade pytest pytest-cov coveralls
+  - pip install --upgrade pip
+  - pip install --upgrade setuptools
+  - pip install --upgrade pytest pytest-cov coveralls
 install:
-- pip install -r requirements_dev.txt
+  - pip install -r requirements_dev.txt
+  - 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
+
 script:
-- if [ "$TRAVIS_PULL_REQUEST" = "false" ]; then py.test tests --tb=native --verbose
-  --cov-config .coveragerc --cov=plexapi; fi
-- flake8 plexapi --exclude=compat.py --max-line-length=120 --ignore=E128,E701,E702,E731,W293
+  - py.test tests -rxXs --ignore=tests/test_sync.py --tb=native --verbose --cov-config .coveragerc --cov=plexapi
+  - PLEXAPI_HEADER_PROVIDES='controller,sync-target' PLEXAPI_HEADER_PLATFORM=iOS PLEXAPI_HEADER_PLATFORM_VERSION=11.4.1
+    PLEXAPI_HEADER_DEVICE=iPhone py.test tests/test_sync.py -rxXs --tb=native --verbose --cov-config .coveragerc
+    --cov=plexapi --cov-append
+
 after_success:
-- coveralls
-matrix:
-  fast_finish: true
-deploy:
-  provider: pypi
-  user: mjs7231
-  password:
-    secure: UhuEN9GAp9zMEXdVTxSrbhfYf4HjTcj47l093Qh1HYKmZACxJM/+JkQCm7+oHPJpo7YDLk2we9oEsQ41maZBr9WgZI1lwR6m590M12vPhPI7NCVzINxJqebc0uZhCFsAFFKA3kzpRQbDfsBUG4yL/AzeMcvJMgIg3m07KRVhBywnnRhQ77trbBI0Io5MBzfW9PYDeGJqlNDBM7SbB4tK0udGZQT9wmFwvIoJODPDnM15Ry4vpkVNww/vVgyHklmnYlPzQgvhSMOXk0+MWlYtaKmu6uuLAiRccT1Fsmi1POKuFEq8S0Z7w4LmwxCVRaCvsZdNW5eXWgPDhZXNcLrKMwjgJt9Vj3VcD+NCywux/C1hTq7tecBocA13kzbgg4fd2sATOjQT5iaRPGrDtKm8e00hxr125n0StDxXdYGl2W5sH0LCkZE6Vq1GjXYjKFXZeTk3Fzav/3N8IxHBX3CliJB/vbloJ2mpz1kXL4UTORl9pghPyGOOq2yJPYSSWly/RsAD7UDrL1/lezaPSJGKbZJ0CMyfA83kd82/hgZflOuBuTcPHCZSU3zMCs0fsImZZxr6Qm1tbff+iyNS/ufoYgeVfsWhlEl9FoLv1g4HG6oA+uDHz+jKz9uSRHcGqD6P4JJK+H+yy0PeYfo7b6eSqFxgt8q8QfifUaCrVoCiY+c=
-  on:
-    tags: true
+  - coveralls
+
+after_script:
+  - PYTHONPATH="$PWD:$PYTHONPATH" python -u tools/plex-teardowntest.py
+
+jobs:
+  include:
+    - python: 3.6
+      env:
+        - PLEX_CONTAINER_TAG=1.3.2.3112-1751929
+        - TEST_ACCOUNT_ONCE=1
+    - python: 3.6
+      name: "Flake8"
+      install:
+        - pip install -r requirements_dev.txt
+      script: flake8 plexapi --exclude=compat.py --max-line-length=120 --ignore=E128,E701,E702,E731,W293
+      after_success: true
+      after_script: true
+      env:
+        - PLEX_CONTAINER_TAG=latest
+    - stage: deploy
+      name: "Deploy to PyPi"
+      python: 3.6
+      install: true
+      script: true
+      env:
+        - PLEX_CONTAINER_TAG=latest
+      deploy:
+        provider: pypi
+        user: mjs7231
+        password:
+          secure: UhuEN9GAp9zMEXdVTxSrbhfYf4HjTcj47l093Qh1HYKmZACxJM/+JkQCm7+oHPJpo7YDLk2we9oEsQ41maZBr9WgZI1lwR6m590M12vPhPI7NCVzINxJqebc0uZhCFsAFFKA3kzpRQbDfsBUG4yL/AzeMcvJMgIg3m07KRVhBywnnRhQ77trbBI0Io5MBzfW9PYDeGJqlNDBM7SbB4tK0udGZQT9wmFwvIoJODPDnM15Ry4vpkVNww/vVgyHklmnYlPzQgvhSMOXk0+MWlYtaKmu6uuLAiRccT1Fsmi1POKuFEq8S0Z7w4LmwxCVRaCvsZdNW5eXWgPDhZXNcLrKMwjgJt9Vj3VcD+NCywux/C1hTq7tecBocA13kzbgg4fd2sATOjQT5iaRPGrDtKm8e00hxr125n0StDxXdYGl2W5sH0LCkZE6Vq1GjXYjKFXZeTk3Fzav/3N8IxHBX3CliJB/vbloJ2mpz1kXL4UTORl9pghPyGOOq2yJPYSSWly/RsAD7UDrL1/lezaPSJGKbZJ0CMyfA83kd82/hgZflOuBuTcPHCZSU3zMCs0fsImZZxr6Qm1tbff+iyNS/ufoYgeVfsWhlEl9FoLv1g4HG6oA+uDHz+jKz9uSRHcGqD6P4JJK+H+yy0PeYfo7b6eSqFxgt8q8QfifUaCrVoCiY+c=
+        on:
+          tags: true

README.rst

@@ -131,6 +131,68 @@ Usage Examples
         print(playlist.title)
 
 
+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
+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.
+
+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
 ----------------
 

plexapi/alert.py

@@ -12,6 +12,18 @@ class AlertListener(threading.Thread):
         alerts you must call .start() on the object once it's created. When calling
         `PlexServer.startAlertListener()`, the thread will be started for you.
 
+        Known `state`-values for timeline entries, with identifier=`com.plexapp.plugins.library`:
+
+            :0: The item was created
+            :1: Reporting progress on item processing
+            :2: Matching the item
+            :3: Downloading the metadata
+            :4: Processing downloaded metadata
+            :5: The item processed
+            :9: The item deleted
+
+        When metadata agent is not set for the library processing ends with state=1.
+
         Parameters:
             server (:class:`~plexapi.server.PlexServer`): PlexServer this listener is connected to.
             callback (func): Callback function to call on recieved messages. The callback function

plexapi/library.py

@@ -470,8 +470,8 @@ def search(self, title=None, sort=None, maxresults=999999, libtype=None, **kwarg
                 libtype (str): Filter results to a spcifiec libtype (movie, show, episode, artist,
                     album, track; optional).
                 **kwargs (dict): Any of the available filters for the current library section. Partial string
-                        matches allowed. Multiple matches OR together. All inputs will be compared with the
-                        available options and a warning logged if the option does not appear valid.
+                        matches allowed. Multiple matches OR together. Negative filtering also possible, just add an
+                        exclamation mark to the end of filter name, e.g. `resolution!=1x1`.
 
                         * unwatched: Display or hide unwatched content (True, False). [all]
                         * duplicate: Display or hide duplicate items (True, False). [movie]
@@ -486,6 +486,9 @@ def search(self, title=None, sort=None, maxresults=999999, libtype=None, **kwarg
                         * resolution: List of video resolutions to search within ([resolution_or_key, ...]). [movie]
                         * studio: List of studios to search within ([studio_or_key, ...]). [music]
                         * year: List of years to search within ([yyyy, ...]). [all]
+
+            Raises:
+                :class:`plexapi.exceptions.BadRequest`: when applying unknown filter
         """
         # cleanup the core arguments
         args = {}
@@ -510,7 +513,10 @@ def search(self, title=None, sort=None, maxresults=999999, libtype=None, **kwarg
 
     def _cleanSearchFilter(self, category, value, libtype=None):
         # check a few things before we begin
-        if category not in self.ALLOWED_FILTERS:
+        if category.endswith('!'):
+            if category[:-1] not in self.ALLOWED_FILTERS:
+                raise BadRequest('Unknown filter category: %s' % category[:-1])
+        elif category not in self.ALLOWED_FILTERS:
             raise BadRequest('Unknown filter category: %s' % category)
         if category in self.BOOLEAN_FILTERS:
             return '1' if value else '0'
@@ -839,12 +845,12 @@ class PhotoSection(LibrarySection):
 
         Attributes:
             ALLOWED_FILTERS (list<str>): List of allowed search filters. ('all', 'iso',
-                'make', 'lens', 'aperture', 'exposure')
+                'make', 'lens', 'aperture', 'exposure', 'device', 'resolution')
             ALLOWED_SORT (list<str>): List of allowed sorting keys. ('addedAt')
             TAG (str): 'Directory'
             TYPE (str): 'photo'
     """
-    ALLOWED_FILTERS = ('all', 'iso', 'make', 'lens', 'aperture', 'exposure')
+    ALLOWED_FILTERS = ('all', 'iso', 'make', 'lens', 'aperture', 'exposure', 'device', 'resolution')
     ALLOWED_SORT = ('addedAt',)
     TAG = 'Directory'
     TYPE = 'photo'
@@ -853,13 +859,11 @@ class PhotoSection(LibrarySection):
 
     def searchAlbums(self, title, **kwargs):
         """ Search for an album. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
-        key = '/library/sections/%s/all?type=14' % self.key
-        return self.fetchItems(key, title=title)
+        return self.search(libtype='photoalbum', title=title, **kwargs)
 
     def searchPhotos(self, title, **kwargs):
         """ Search for a photo. See :func:`~plexapi.library.LibrarySection.search()` for usage. """
-        key = '/library/sections/%s/all?type=13' % self.key
-        return self.fetchItems(key, title=title)
+        return self.search(libtype='photo', title=title, **kwargs)
 
     def sync(self, resolution, limit=None, **kwargs):
         """ Add current Music library section as sync item for specified device.

plexapi/myplex.py

@@ -263,7 +263,7 @@ def updateFriend(self, user, server, sections=None, removeSections=False, allowS
         # Update friend servers
         response_filters = ''
         response_servers = ''
-        user = self.user(user.username if isinstance(user, MyPlexUser) else user)
+        user = user if isinstance(user, MyPlexUser) else self.user(user)
         machineId = server.machineIdentifier if isinstance(server, PlexServer) else server
         sectionIds = self._getSectionIds(machineId, sections)
         headers = {'Content-Type': 'application/json'}
@@ -278,7 +278,7 @@ def updateFriend(self, user, server, sections=None, removeSections=False, allowS
                 "invited_id": user.id}}
             url = self.FRIENDINVITE.format(machineId=machineId)
         # Remove share sections, add shares to user without shares, or update shares
-        if sectionIds:
+        if not user_servers or sectionIds:
             if removeSections is True:
                 response_servers = self.query(url, self._session.delete, json=params, headers=headers)
             elif 'invited_id' in params.get('shared_server', ''):
@@ -376,7 +376,8 @@ def deleteWebhook(self, url):
 
     def setWebhooks(self, urls):
         log.info('Setting webhooks: %s' % urls)
-        data = self.query(self.WEBHOOKS, self._session.post, data={'urls[]': urls})
+        data = {'urls[]': urls} if len(urls) else {'urls': ''}
+        data = self.query(self.WEBHOOKS, self._session.post, data=data)
         self._webhooks = self.listAttrs(data, 'url', etag='webhook')
         return self._webhooks
 
@@ -395,7 +396,7 @@ def optOut(self, playback=None, library=None):
         if library is not None:
             params['optOutLibraryStats'] = int(library)
         url = 'https://plex.tv/api/v2/user/privacy'
-        return self.query(url, method=self._session.put, params=params)
+        return self.query(url, method=self._session.put, data=params)
 
     def syncItems(self, client=None, clientId=None):
         """ Returns an instance of :class:`plexapi.sync.SyncList` for specified client.

plexapi/photo.py

@@ -154,7 +154,7 @@ def sync(self, resolution, client=None, clientId=None, limit=None, title=None):
         sync_item.metadataType = self.METADATA_TYPE
         sync_item.machineIdentifier = self._server.machineIdentifier
 
-        section = self._server.library.sectionByID(self.librarySectionID)
+        section = self.section()
 
         sync_item.location = 'library://%s/item/%s' % (section.uuid, quote_plus(self.key))
         sync_item.policy = Policy.create(limit)

plexapi/playlist.py

@@ -168,8 +168,8 @@ def sync(self, videoQuality=None, photoResolution=None, audioBitrate=None, clien
                                     :mod:`plexapi.sync` module. Used only when playlist contains video.
                 photoResolution (str): maximum allowed resolution for synchronized photos, see PHOTO_QUALITY_* values in
                                        the module :mod:`plexapi.sync`. Used only when playlist contains photos.
-                audioBitrate (int): maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values from the
-                                    module :mod:`plexapi.sync`. Used only when playlist contains audio.
+                audioBitrate (int): maximum bitrate for synchronized music, better use one of MUSIC_BITRATE_* values
+                                    from the module :mod:`plexapi.sync`. Used only when playlist contains audio.
                 client (:class:`plexapi.myplex.MyPlexDevice`): sync destination, see
                                                                :func:`plexapi.myplex.MyPlexAccount.sync`.
                 clientId (str): sync destination, see :func:`plexapi.myplex.MyPlexAccount.sync`.

plexapi/server.py

@@ -290,12 +290,14 @@ def check_for_update(self, force=True, download=False):
         part = '/updater/check?download=%s' % (1 if download else 0)
         if force:
             self.query(part, method=self._session.put)
-        return self.fetchItem('/updater/status')
+        releases = self.fetchItems('/updater/status')
+        if len(releases):
+            return releases[0]
 
     def isLatest(self):
         """ Check if the installed version of PMS is the latest. """
         release = self.check_for_update(force=True)
-        return bool(release.version == self.version)
+        return release is None
 
     def installUpdate(self):
         """ Install the newest version of Plex Media Server. """

plexapi/settings.py

@@ -99,7 +99,7 @@ class Setting(PlexObject):
             group (str): Group name this setting is categorized as.
             enumValues (list,dict): List or dictionary of valis values for this setting.
     """
-    _bool_cast = lambda x: True if x == 'true' else False
+    _bool_cast = lambda x: True if x == 'true' or x == '1' else False
     _bool_str = lambda x: str(x).lower()
     TYPES = {
         'bool': {'type': bool, 'cast': _bool_cast, 'tostr': _bool_str},

plexapi/utils.py

@@ -14,9 +14,9 @@
 
 # Search Types - Plex uses these to filter specific media types when searching.
 # Library Types - Populated at runtime
-SEARCHTYPES = {'movie': 1, 'show': 2, 'season': 3, 'episode': 4,
-               'artist': 8, 'album': 9, 'track': 10, 'photo': 14,
-               'collection': 18}
+SEARCHTYPES = {'movie': 1, 'show': 2, 'season': 3, 'episode': 4, 'trailer': 5, 'comic': 6, 'person': 7,
+               'artist': 8, 'album': 9, 'track': 10, 'picture': 11, 'clip': 12, 'photo': 13, 'photoalbum': 14,
+               'playlist': 15, 'playlistFolder': 16, 'collection': 18, 'userPlaylistItem': 1001}
 PLEXOBJECTS = {}
 
 

plexapi/video.py

@@ -323,7 +323,7 @@ def isWatched(self):
 
     def seasons(self, **kwargs):
         """ Returns a list of :class:`~plexapi.video.Season` objects. """
-        key = '/library/metadata/%s/children' % self.ratingKey
+        key = '/library/metadata/%s/children?excludeAllLeaves=1' % self.ratingKey
         return self.fetchItems(key, **kwargs)
 
     def season(self, title=None):

requirements_dev.txt

@@ -15,4 +15,4 @@ sphinx
 sphinx-rtd-theme
 sphinxcontrib-napoleon
 tqdm
-websocket-client
+websocket-client==0.48.0