Update tmdbsimple 2.2.6 (310d933) → 2.6.6 (679e343).

CHANGES.md

@@ -14,6 +14,7 @@
 * Update Requests library 2.24.0 (1b41763) to 2.24.0 (967a05b)
 * Update soupsieve_py3 2.0.0.final (e66c311) to 2.0.2.dev (05086ef)
 * Update soupsieve_py2 backport
+* Update tmdbsimple 2.2.6 (310d933) to 2.6.6 (679e343)
 * Update urllib3 1.25.9 (a5a45dc) to 1.26.0.dev0 (41eae64)
 
 

lib/tmdbsimple/__init__.py

@@ -4,11 +4,11 @@
 tmdbsimple
 ~~~~~~~~~~
 
-*tmdbsimple* is a wrapper, written in Python, for The Movie Database (TMDb) 
+*tmdbsimple* is a wrapper, written in Python, for The Movie Database (TMDb)
-API v3.  By calling the functions available in *tmdbsimple* you can simplify 
+API v3.  By calling the functions available in *tmdbsimple* you can simplify
-your code and easily access a vast amount of movie, tv, and cast data.  To find 
+your code and easily access a vast amount of movie, tv, and cast data.  To find
-out more about The Movie Database API, check out the overview page 
+out more about The Movie Database API, check out the overview page
-http://www.themoviedb.org/documentation/api and documentation page 
+http://www.themoviedb.org/documentation/api and documentation page
 https://developers.themoviedb.org/3/getting-started
 https://www.themoviedb.org/documentation/api/status-codes
 
@@ -17,7 +17,7 @@ https://www.themoviedb.org/documentation/api/status-codes
 """
 
 __title__ = 'tmdbsimple'
-__version__ = '2.2.6'
+__version__ = '2.6.6'
 __author__ = 'Celia Oakley'
 __copyright__ = 'Copyright (c) 2013-2020 Celia Oakley'
 __license__ = 'GPLv3'
@@ -27,15 +27,27 @@ import os
 from .account import Account, Authentication, GuestSessions, Lists
 from .base import APIKeyError
 from .changes import Changes
-from .configuration import Configuration, Certifications, Timezones
+from .configuration import Configuration, Certifications
 from .discover import Discover
-from .find import Find
+from .find import Find, Trending
 from .genres import Genres
 from .movies import Movies, Collections, Companies, Keywords, Reviews
-from .people import People, Credits, Jobs
+from .people import People, Credits
 from .search import Search
-from .tv import TV, TV_Seasons, TV_Episodes, TV_Changes, Networks
+from .tv import TV, TV_Seasons, TV_Episodes, TV_Episode_Groups, TV_Changes, Networks
-
+
+__all__ = ['Account', 'Authentication', 'GuestSessions', 'Lists',
+           'APIKeyError',
+           'Changes',
+           'Configuration', 'Certifications',
+           'Discover',
+           'Find', 'Trending',
+           'Genres',
+           'Movies', 'Collections', 'Companies', 'Keywords', 'Reviews',
+           'People', 'Credits'
+           'Search',
+           'TV', 'TV_Seasons', 'TV_Episodes', 'TV_Episode_Groups', 'TV_Changes', 'Networks'
+           ]
 
 API_KEY = os.environ.get('TMDB_API_KEY', None)
 API_VERSION = '3'

lib/tmdbsimple/account.py

@@ -3,7 +3,7 @@
 """
 tmdbsimple.account
 ~~~~~~~~~~~~~~~~~~
-This module implements the Account, Authentication, and Lists functionality 
+This module implements the Account, Authentication, and Lists functionality
 of tmdbsimple.
 
 Created by Celia Oakley on 2013-10-31.
@@ -25,12 +25,13 @@ class Account(TMDB):
     BASE_PATH = 'account'
     URLS = {
         'info': '',
-        'lists': '/{id}/lists', 
+        'lists': '/{id}/lists',
         'favorite_movies': '/{id}/favorite/movies',
         'favorite_tv': '/{id}/favorite/tv',
         'favorite': '/{id}/favorite',
         'rated_movies': '/{id}/rated/movies',
         'rated_tv': '/{id}/rated/tv',
+        'rated_tv_episodes': '/{id}/rated/tv/episodes',
         'watchlist_movies': '/{id}/watchlist/movies',
         'watchlist_tv': '/{id}/watchlist/tv',
         'watchlist': '/{id}/watchlist',
@@ -42,9 +43,9 @@ class Account(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the basic information for an account.
+        Get your account details.
 
-        Call this method first, before calling other Account methods.
+        Args:
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -56,14 +57,15 @@ class Account(TMDB):
         self.id = response['id']
         self._set_attrs_to_values(response)
         return response
-        
+
     def lists(self, **kwargs):
         """
-        Get the lists that you have created and marked as a favorite.
+        Get all of the lists created by an account. Will include private lists
+        if you are the owner.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -77,12 +79,12 @@ class Account(TMDB):
 
     def favorite_movies(self, **kwargs):
         """
-        Get the list of favorite movies for an account.
+        Get the list of your favorite movies.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
             language: (optional) ISO 639-1 code.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -96,12 +98,12 @@ class Account(TMDB):
 
     def favorite_tv(self, **kwargs):
         """
-        Get the list of favorite TV series for an account.
+        Get the list of your favorite TV shows.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
             language: (optional) ISO 639-1 code.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -115,7 +117,7 @@ class Account(TMDB):
 
     def favorite(self, **kwargs):
         """
-        Add or remove a movie to an accounts favorite list.
+        This method allows you to mark a movie or TV show as a favorite item.
 
         Args:
             media_type: 'movie' | 'tv'
@@ -129,8 +131,8 @@ class Account(TMDB):
         kwargs.update({'session_id': self.session_id})
 
         payload = {
-            'media_type': kwargs.pop('media_type', None), 
+            'media_type': kwargs.pop('media_type', None),
-            'media_id': kwargs.pop('media_id', None), 
+            'media_id': kwargs.pop('media_id', None),
             'favorite': kwargs.pop('favorite', None),
         }
 
@@ -140,12 +142,12 @@ class Account(TMDB):
 
     def rated_movies(self, **kwargs):
         """
-        Get the list of rated movies (and associated rating) for an account.
+        Get a list of all the movies you have rated.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
+            language: (optional) ISO 639-1 value.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -159,12 +161,12 @@ class Account(TMDB):
 
     def rated_tv(self, **kwargs):
         """
-        Get the list of rated TV shows (and associated rating) for an account.
+        Get a list of all the TV shows you have rated.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
+            language: (optional) ISO 639-1 value.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -176,14 +178,33 @@ class Account(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def rated_tv_episodes(self, **kwargs):
+        """
+        Get a list of all the TV episodes you have rated.
+
+        Args:
+            language: (optional) ISO 639-1 value.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
+            page: (optional) Minimum 1, maximum 1000, default 1.
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_id_path('rated_tv_episodes')
+        kwargs.update({'session_id': self.session_id})
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
     def watchlist_movies(self, **kwargs):
         """
-        Get the list of movies on an account watchlist.
+        Get a list of all the movies you have added to your watchlist.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
+            language: (optional) ISO 639-1 value.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -197,12 +218,12 @@ class Account(TMDB):
 
     def watchlist_tv(self, **kwargs):
         """
-        Get the list of TV series on an account watchlist.
+        Get a list of all the TV shows you have added to your watchlist.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
+            language: (optional) ISO 639-1 value.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -216,7 +237,7 @@ class Account(TMDB):
 
     def watchlist(self, **kwargs):
         """
-        Add or remove a movie to an accounts watch list.
+        Add a movie or TV show to your watchlist.
 
         Args:
             media_type: 'movie' | 'tv'
@@ -230,8 +251,8 @@ class Account(TMDB):
         kwargs.update({'session_id': self.session_id})
 
         payload = {
-            'media_type': kwargs.pop('media_type', None), 
+            'media_type': kwargs.pop('media_type', None),
-            'media_id': kwargs.pop('media_id', None), 
+            'media_id': kwargs.pop('media_id', None),
             'watchlist': kwargs.pop('watchlist', None),
         }
 
@@ -239,6 +260,7 @@ class Account(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+
 class Authentication(TMDB):
     """
     Authentication functionality.
@@ -248,48 +270,53 @@ class Authentication(TMDB):
     """
     BASE_PATH = 'authentication'
     URLS = {
+        'guest_session_new': '/guest_session/new',
         'token_new': '/token/new',
+        'session_new': '/session/new',
         'token_validate_with_login': '/token/validate_with_login',
-        'session_new': '/session/new', 
+        'session_delete': '/session',
-        'guest_session_new': '/guest_session/new', 
     }
 
-    def token_new(self, **kwargs):
+    def guest_session_new(self, **kwargs):
         """
-        Generate a valid request token for user based authentication.
+        This method will let you create a new guest session. Guest sessions
+        are a type of session that will let a user rate movies and TV shows
+        but not require them to have a TMDb user account. More
+        information about user authentication can be found here
+        (https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id).
+
+        Please note, you should only generate a single guest session per
+        user (or device) as you will be able to attach the ratings to a
+        TMDb user account in the future. There is also IP limits in place
+        so you should always make sure it's the end user doing the guest
+        session actions.
 
-        A request token is required to ask the user for permission to
+        If a guest session is not used for the first time within 24 hours,
-        access their account.
+        it will be automatically deleted.
 
-        After obtaining the request_token, either:
+        Args:
-        (1) Direct your user to:
-                https://www.themoviedb.org/authenticate/REQUEST_TOKEN
-        or:
-        (2) Call token_validate_with_login() below.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('token_new')
+        path = self._get_path('guest_session_new')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def token_validate_with_login(self, **kwargs):
+    def token_new(self, **kwargs):
         """
-        Authenticate a user with a TMDb username and password.  The user
+        Create a temporary request token that can be used to validate a TMDb
-        must have a verified email address and be registered on TMDb.
+        user login. More details about how this works can be found here
+        (https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id).
 
         Args:
-            request_token: The token you generated for the user to approve.
-            username: The user's username on TMDb.
-            password: The user's password on TMDb.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('token_validate_with_login')
+        path = self._get_path('token_new')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
@@ -297,9 +324,10 @@ class Authentication(TMDB):
 
     def session_new(self, **kwargs):
         """
-        Generate a session id for user based authentication.
+        You can use this method to create a fully valid session ID once a user
-
+        has validated the request token. More information about how this works
-        A session id is required in order to use any of the write methods.
+        can be found here
+        (https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id).
 
         Args:
             request_token: The token you generated for the user to approve.
@@ -315,19 +343,56 @@ class Authentication(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def guest_session_new(self, **kwargs):
+    def token_validate_with_login(self, **kwargs):
         """
-        Generate a guest session id.
+        This method allows an application to validate a request token by entering
+        a username and password.
+
+        Not all applications have access to a web view so this can be used as a
+        substitute.
+
+        Please note, the preferred method of validating a request token is to
+        have a user authenticate the request via the TMDb website. You can read
+        about that method here
+        (https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id).
+
+        If you decide to use this method please use HTTPS.
+
+        Args:
+            username: The user's username on TMDb.
+            password: The user's password on TMDb.
+            request_token: The token you generated for the user to approve.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('guest_session_new')
+        path = self._get_path('token_validate_with_login')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
+    def session_delete(self, **kwargs):
+        """
+        If you would like to delete (or "logout") from a session, call this
+        method with a valid session ID.
+
+        Args:
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_path('session_delete')
+
+        payload = {
+            'session_id': kwargs.pop('session_id', None),
+        }
+
+        response = self._DELETE(path, kwargs, payload)
+        self._set_attrs_to_values(response)
+        return response
+
+
 class GuestSessions(TMDB):
     """
     Guest Sessions functionality.
@@ -336,7 +401,9 @@ class GuestSessions(TMDB):
     """
     BASE_PATH = 'guest_session'
     URLS = {
-        'rated_movies': '/{guest_session_id}/rated_movies',
+        'rated_movies': '/{guest_session_id}/rated/movies',
+        'rated_tv': '/{guest_session_id}/rated/tv',
+        'rated_tv_episodes': '/{guest_session_id}/rated/tv/episodes',
     }
 
     def __init__(self, guest_session_id=0):
@@ -345,12 +412,11 @@ class GuestSessions(TMDB):
 
     def rated_movies(self, **kwargs):
         """
-        Get a list of rated moview for a specific guest session id.
+        Get the rated movies for a guest session.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
-            sort_by: (optional) 'created_at.asc' | 'created_at.desc'
             language: (optional) ISO 639-1 code.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -360,7 +426,41 @@ class GuestSessions(TMDB):
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
-    
+
+    def rated_tv(self, **kwargs):
+        """
+        Get the rated TV shows for a guest session.
+
+        Args:
+            language: (optional) ISO 639-1 code.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_guest_session_id_path('rated_tv')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    def rated_tv_episodes(self, **kwargs):
+        """
+        Get the rated TV episodes for a guest session.
+
+        Args:
+            language: (optional) ISO 639-1 code.
+            sort_by: (optional) Allowed Values: created_at.asc, created_at.desc
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_guest_session_id_path('rated_tv_episodes')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
 
 class Lists(TMDB):
     """
@@ -371,11 +471,12 @@ class Lists(TMDB):
     BASE_PATH = 'list'
     URLS = {
         'info': '/{id}',
-        'item_status': '/{id}/item_status', 
+        'item_status': '/{id}/item_status',
-        'create_list': '',
+        'list_create': '',
         'add_item': '/{id}/add_item',
         'remove_item': '/{id}/remove_item',
-        'clear': '/{id}/clear',
+        'list_clear': '/{id}/clear',
+        'list_delete': '/{id}',
     }
 
     def __init__(self, id=0, session_id=0):
@@ -385,7 +486,10 @@ class Lists(TMDB):
 
     def info(self, **kwargs):
         """
-        Get a list by id.
+        Get the details of a list.
+
+        Args:
+            language: (optional) ISO 639-1 code.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -398,10 +502,11 @@ class Lists(TMDB):
 
     def item_status(self, **kwargs):
         """
-        Check to see if a movie id is already added to a list.
+        You can use this method to check if a movie has already been added to
+        the list.
 
         Args:
-            movie_id: The id of the movie.
+            movie_id: The id of the movie.  Minimum 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -412,11 +517,9 @@ class Lists(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def create_list(self, **kwargs):
+    def list_create(self, **kwargs):
         """
-        Create a new list.
+        Create a list.
-
-        A valid session id is required.
 
         Args:
             name: Name of the list.
@@ -426,28 +529,26 @@ class Lists(TMDB):
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('create_list')
+        path = self._get_path('list_create')
         kwargs.update({'session_id': self.session_id})
 
         payload = {
-            'name': kwargs.pop('name', None), 
+            'name': kwargs.pop('name', None),
             'description': kwargs.pop('description', None),
+            'language': kwargs.pop('language', None),
         }
-        if 'language' in kwargs:
-            payload['language'] = kwargs['language']
 
         response = self._POST(path, kwargs, payload)
         self._set_attrs_to_values(response)
+        self.id = self.list_id
         return response
 
     def add_item(self, **kwargs):
         """
-        Add new movies to a list that the user created.
+        Add a movie to a list.
-
-        A valid session id is required.
 
         Args:
-            media_id: A movie id.
+            media_id: A movie id.  Minimum 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -456,21 +557,19 @@ class Lists(TMDB):
         kwargs.update({'session_id': self.session_id})
 
         payload = {
-            'media_id': kwargs.pop('media_id', None), 
+            'media_id': kwargs.pop('media_id', None),
         }
 
         response = self._POST(path, kwargs, payload)
         self._set_attrs_to_values(response)
         return response
-        
+
     def remove_item(self, **kwargs):
         """
-        Delete movies from a list that the user created.
+        Remove a movie from a list.
-
-        A valid session id is required.
 
         Args:
-            media_id: A movie id.
+            media_id: A movie id.  Minimum 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -479,19 +578,16 @@ class Lists(TMDB):
         kwargs.update({'session_id': self.session_id})
 
         payload = {
-            'media_id': kwargs.pop('media_id', None), 
+            'media_id': kwargs.pop('media_id', None),
         }
 
         response = self._POST(path, kwargs, payload)
         self._set_attrs_to_values(response)
         return response
 
-    def clear_list(self, **kwargs):
+    def list_clear(self, **kwargs):
         """
-        Clears all of the items within a list. This is an irreversible action
+        Clear all of the items from a list.
-        and should be treated with caution.
-
-        A valid session id is required.
 
         Args:
             confirm: True (do it) | False (don't do it)
@@ -499,7 +595,7 @@ class Lists(TMDB):
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_id_path('clear')
+        path = self._get_id_path('list_clear')
         kwargs.update({'session_id': self.session_id})
 
         payload = {}
@@ -507,3 +603,20 @@ class Lists(TMDB):
         response = self._POST(path, kwargs, payload)
         self._set_attrs_to_values(response)
         return response
+
+    def list_delete(self, **kwargs):
+        """
+        Delete a list.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_id_path('list_delete')
+        kwargs.update({'session_id': self.session_id})
+
+        response = self._DELETE(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response

lib/tmdbsimple/base.py

@@ -40,17 +40,21 @@ class TMDB(object):
     def _get_guest_session_id_path(self, key):
         return self._get_path(key).format(
             guest_session_id=self.guest_session_id)
-    
+
     def _get_credit_id_path(self, key):
         return self._get_path(key).format(credit_id=self.credit_id)
 
-    def _get_series_id_season_number_path(self, key):
+    def _get_media_type_time_window_path(self, key):
-        return self._get_path(key).format(series_id=self.series_id,
+        return self._get_path(key).format(
-            season_number=self.season_number)
+            media_type=self.media_type, time_window=self.time_window)
+
+    def _get_tv_id_season_number_path(self, key):
+        return self._get_path(key).format(
+            tv_id=self.tv_id, season_number=self.season_number)
 
-    def _get_series_id_season_number_episode_number_path(self, key):
+    def _get_tv_id_season_number_episode_number_path(self, key):
-        return self._get_path(key).format(series_id=self.series_id,
+        return self._get_path(key).format(
-            season_number=self.season_number,
+            tv_id=self.tv_id, season_number=self.season_number,
             episode_number=self.episode_number)
 
     def _get_complete_url(self, path):
@@ -77,7 +81,7 @@ class TMDB(object):
         params = self._get_params(params)
 
         response = requests.request(
-            method, url, params=params, 
+            method, url, params=params,
             data=json.dumps(payload) if payload else payload,
             headers=self.headers, verify=False)
 
@@ -108,4 +112,3 @@ class TMDB(object):
             for key in response.keys():
                 if not hasattr(self, key) or not callable(getattr(self, key)):
                     setattr(self, key, response[key])
-

lib/tmdbsimple/changes.py

@@ -13,6 +13,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class Changes(TMDB):
     """
     Changes functionality.
@@ -22,18 +23,23 @@ class Changes(TMDB):
     BASE_PATH = ''
     URLS = {
         'movie': 'movie/changes',
-        'person': 'person/changes',
         'tv': 'tv/changes',
+        'person': 'person/changes',
     }
 
     def movie(self, **kwargs):
         """
-        Get a list of movie ids that have been edited.
+        Get a list of all of the movie ids that have been changed
+        in the past 24 hours.
+
+        You can query it for up to 14 days worth of changed IDs at
+        a time with the start_date and end_date query parameters.
+        100 items are returned per page.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             start_date: (optional) Expected format is 'YYYY-MM-DD'.
             end_date: (optional) Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -44,37 +50,47 @@ class Changes(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def person(self, **kwargs):
+    def tv(self, **kwargs):
         """
-        Get a list of people ids that have been edited.
+        Get a list of all of the TV show ids that have been changed
+        in the past 24 hours.
+
+        You can query it for up to 14 days worth of changed IDs at
+        a time with the start_date and end_date query parameters.
+        100 items are returned per page.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             start_date: (optional) Expected format is 'YYYY-MM-DD'.
             end_date: (optional) Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('person')
+        path = self._get_path('tv')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def tv(self, **kwargs):
+    def person(self, **kwargs):
         """
-        Get a list of TV show ids that have been edited.
+        Get a list of all of the person ids that have been changed
+        in the past 24 hours.
+
+        You can query it for up to 14 days worth of changed IDs at
+        a time with the start_date and end_date query parameters.
+        100 items are returned per page.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             start_date: (optional) Expected format is 'YYYY-MM-DD'.
             end_date: (optional) Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('tv')
+        path = self._get_path('person')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)

lib/tmdbsimple/configuration.py

@@ -4,8 +4,8 @@
 tmdbsimple.configuration
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-This module implements the Configuration, Certifications, and Timezones 
+This module implements the Configuration and Certifications functionality of
-functionality of tmdbsimple.
+tmdbsimple.
 
 Created by Celia Oakley on 2013-10-31.
 
@@ -25,12 +25,36 @@ class Configuration(TMDB):
     BASE_PATH = 'configuration'
     URLS = {
         'info': '',
+        'countries': '/countries',
+        'jobs': '/jobs',
         'languages': '/languages',
+        'primary_translations': '/primary_translations',
+        'timezones': '/timezones',
     }
 
     def info(self, **kwargs):
         """
-        Get the system wide configuration info.
+        Get the system wide configuration information. Some elements of the API
+        require some knowledge of this configuration data. The purpose of this
+        is to try and keep the actual API responses as light as possible. It is
+        recommended you cache this data within your application and check for
+        updates every few days.
+
+        This method currently holds the data relevant to building image URLs as
+        well as the change key map.
+
+        To build an image URL, you will need 3 pieces of data. The base_url,
+        size and file_path. Simply combine them all and you will have a fully
+        qualified URL. Here’s an example URL:
+
+            https://image.tmdb.org/t/p/w500/8uO0gUM8aNqYLs1OsTBQiXu0fEv.jpg
+
+        The configuration method also contains the list of change keys which
+        can be useful if you are building an app that consumes data from the
+        change feed.
+
+        Args:
+            None
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -41,10 +65,45 @@ class Configuration(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def countries(self, **kwargs):
+        """
+        Get the list of countries (ISO 3166-1 tags) used throughout TMDb.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_path('countries')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    def jobs(self, **kwargs):
+        """
+        Get a list of the jobs and departments we use on TMDb.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_path('jobs')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
     def languages(self, **kwargs):
         """
         Get the list of languages (ISO 639-1 tags) used throughout TMDb.
 
+        Args:
+            None
+
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
@@ -54,6 +113,38 @@ class Configuration(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def primary_translations(self, **kwargs):
+        """
+        Get a list of the officially supported translations on TMDb.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_path('primary_translations')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    def timezones(self, **kwargs):
+        """
+        Get the list of timezones used throughout TMDb.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_path('timezones')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
 
 class Certifications(TMDB):
     """
@@ -64,11 +155,15 @@ class Certifications(TMDB):
     BASE_PATH = 'certification'
     URLS = {
         'movie_list': '/movie/list',
+        'tv_list': '/tv/list',
     }
 
-    def list(self, **kwargs):
+    def movie_list(self, **kwargs):
         """
-        Get the list of supported certifications for movies.
+        Get an up to date list of the officially supported movie certifications on TMDb.
+
+        Args:
+            None
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -79,29 +174,35 @@ class Certifications(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def tv_list(self, **kwargs):
+        """
+        Get an up to date list of the officially supported TV show certifications on TMDb.
 
-class Timezones(TMDB):
+        Args:
-    """
+            None
-    Timezones functionality.
 
-    See: https://developers.themoviedb.org/3/timezones
+        Returns:
-    """
+            A dict respresentation of the JSON returned from the API.
-    BASE_PATH = 'timezones'
+        """
-    URLS = {
+        path = self._get_path('tv_list')
-        'list': '/list',
-    }
 
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    # backward compatability, when only /movie/list existed
     def list(self, **kwargs):
         """
-        Get the list of supported timezones for the API methods that support
+        Get the list of supported certifications for movies.
-        them.
+
+        Args:
+            None
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('list')
+        path = self._get_path('movie_list')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
-

lib/tmdbsimple/discover.py

@@ -13,6 +13,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class Discover(TMDB):
     """
     Discover functionality.
@@ -27,64 +28,126 @@ class Discover(TMDB):
 
     def movie(self, **kwargs):
         """
-        Discover movies by different types of data like average rating, 
+        Discover movies by different types of data like average rating, number
-        number of votes, genres and certifications.
+        of votes, genres and certifications. You can get a valid list of
+        certifications from the certifications list method.
+
+        Discover also supports a nice list of sort options. See below for all
+        of the available options.
+
+        Please note, when using certification / certification.lte you must also
+        specify certification_country. These two parameters work together in
+        order to filter the results. You can only filter results with the
+        countries we have added to our certifications list.
+
+        If you specify the region parameter, the regional release date will be
+        used instead of the primary release date. The date returned will be the
+        first date based on your query (ie. if a with_release_type is
+        specified). It's important to note the order of the release types that
+        are used. Specifying "2|3" would return the limited theatrical release
+        date as opposed to "3|2" which would return the theatrical date.
+
+        Also note that a number of filters support being comma (,) or pipe (|)
+        separated. Comma's are treated like an AND and query while pipe's are
+        an OR.
+
+        Some examples of what can be done with discover can be found at
+        https://www.themoviedb.org/documentation/api/discover.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             language: (optional) ISO 639-1 code.
-            sort_by: (optional) Available options are 'vote_average.desc', 
+            region: (optional) Specify a ISO 3166-1 code.
-                     'vote_average.asc', 'release_date.desc', 'release_date.asc'
+            sort_by: (optional) Allowed values: popularity.asc,
-                     'popularity.desc', 'popularity.asc'.
+                popularity.desc, release_date.asc, release_date.desc,
-            include_adult: (optional) Toggle the inclusion of adult titles. 
+                revenue.asc, revenue.desc, primary_release_date.asc,
-                           Expected value is a boolean, True or False.
+                primary_release_date.desc, original_title.asc,
-            year: (optional) Filter the results release dates to matches that
+                original_title.desc, vote_average.asc, vote_average.desc,
-                  include this value. Expected value is a year.
+                vote_count.asc, vote_count.desc
-            primary_release_year: (optional) Filter the results so that 
+                Default: popularity.desc
-                                  only the primary release date year has 
+            certification_country: (optional) Used in conjunction with the
-                                  this value.  Expected value is a year.
+                certification filter, use this to specify a country with a
-            vote_count.gte or vote_count_gte: (optional) Only include movies 
+                valid certification.
-                            that are equal to, or have a vote count higher 
+            certification: Filter results with a valid certification from the
-                            than this value.  Expected value is an integer.
+                'certification_country' field.
-            vote_average.gte or vote_average_gte: (optional) Only include 
+            certification.gte: Filter and only include movies that have a
-                              movies that are equal to, or have a higher 
+                certification that is greater than or equal to the specified
-                              average rating than this value.  Expected value 
+                value.
-                              is a float.
+            certification.lte: Filter and only include movies that have a
-            with_genres: (optional) Only include movies with the specified 
+                certification that is less than or equal to the specified
-                         genres.  Expected value is an integer (the id of 
+                value.
-                         a genre).  Multiple values can be specified. 
+            include_adult: (optional) A filter and include or exclude adult
-                         Comma separated indicates an 'AND' query, while 
+                movies.
-                         a pipe (|) separated value indicates an 'OR'.
+            include_video: (optional) A filter to include or exclude videos.
-            release_date.gte or release_date_gte: (optional) The minimum 
+            page: (optional) Minimum 1, maximum 1000, default 1.
-                              release to include.  Expected format is 
+            primary_release_year: (optional) A filter to limit the results to a
-                              'YYYY-MM-DD'.
+                specific primary release year.
-            releaste_date.lte or release_date_lte: (optional) The maximum 
+            primary_release_date.gte: (optional) Filter and only include movies
-                              release to include.  Expected format is 
+                that have a primary release date that is greater or equal to
-                              'YYYY-MM-DD'.
+                the specified value.
-            certification_country: (optional) Only include movies with
+            primary_release_date.lte: (optional) Filter and only include movies
-                                   certifications for a specific country. When
+                that have a primary release date that is less than or equal to
-                                   this value is specified, 'certification.lte'
+                the specified value.
-                                   is required. An ISO 3166-1 is expected.
+            release_date.gte: (optional) Filter and only include movies that
-            certification.lte or certification_lte: (optional) Only include 
+                have a primary release date that is greater or equal to the
-                               movies with this certification and lower. 
+                specified value.
-                               Expected value is a valid certification for 
+            releaste_date.lte: (optional) Filter and only include movies that
-                               the specified 'certification_country'.
+                have a primary release date that is less than or equal to the
-            with_companies: (optional) Filter movies to include a specific 
+                specified value.
-                            company.  Expected value is an integer (the id 
+            with_release_type: (optional) Specify a comma (AND) or pipe (OR)
-                            of a company).  They can be comma separated 
+                separated value to filter release types by. These release types
-                            to indicate an 'AND' query.
+                map to the same values found on the movie release date method.
-          
+                Minimum 1, maximum 6.
+            year: (optional) A filter to limit the results to a specific year
+                (looking at all release dates).
+            vote_count.gte: (optional) Filter and only include movies that have
+                a vote count that is greater or equal to the specified value.
+                Minimum 0.
+            vote_count.lte: (optional) Filter and only include movies that have
+                a vote count that is less than or equal to the specified value.
+                Minimum 1.
+            vote_average.gte: (optional) Filter and only include movies that
+                have a rating that is greater or equal to the specified value.
+                Minimum 0.
+            vote_average.lte: (optional) Filter and only include movies that
+                have a rating that is less than or equal to the specified value.
+                Minimum 0.
+            with_cast: (optional) A comma separated list of person ID's. Only
+                include movies that have one of the ID's added as an actor. 
+            with_crew: (optional) A comma separated list of person ID's. Only
+                include movies that have one of the ID's added as a crew member.
+            with_people: (optional) A comma separated list of person ID's. Only
+                include movies that have one of the ID's added as a either a
+                actor or a crew member.
+            with_companies: (optional) A comma separated list of production
+                company ID's. Only include movies that have one of the ID's
+                added as a production company.
+            with_genres: (optional) Comma separated value of genre ids that you
+                want to include in the results.
+            without_genres: (optional) Comma separated value of genre ids that
+                you want to exclude from the results.
+            with_keywords: (optional) A comma separated list of keyword ID's.
+                Only includes movies that have one of the ID's added as a
+                keyword.
+            without_keywords: (optional) Exclude items with certain keywords.
+                You can comma and pipe seperate these values to create an 'AND' or 'OR' logic.
+            with_runtime.gte: (optional) Filter and only include movies that
+                have a runtime that is greater or equal to a value.
+            with_runtime.lte: (optional) Filter and only include movies that
+                have a runtime that is less than or equal to a value.
+            with_original_language: (optional) Specify an ISO 639-1 string to
+                filter results by their original language value.
+
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        # Periods are not allowed in keyword arguments but several API 
+        # Periods are not allowed in keyword arguments but several API
         # arguments contain periods. See both usages in tests/test_discover.py.
-        for param in kwargs:
+        for param in dict(kwargs):
             if '_lte' in param:
                 kwargs[param.replace('_lte', '.lte')] = kwargs.pop(param)
             if '_gte' in param:
                 kwargs[param.replace('_gte', '.gte')] = kwargs.pop(param)
-        
+
         path = self._get_path('movie')
 
         response = self._GET(path, kwargs)
@@ -93,53 +156,97 @@ class Discover(TMDB):
 
     def tv(self, **kwargs):
         """
-        Discover TV shows by different types of data like average rating, 
+        Discover TV shows by different types of data like average rating,
         number of votes, genres, the network they aired on and air dates.
 
+        Discover also supports a nice list of sort options. See below for all
+        of the available options.
+
+        Also note that a number of filters support being comma (,) or pipe (|)
+        separated. Comma's are treated like an AND and query while pipe's are
+        an OR.
+
+        Some examples of what can be done with discover can be found at
+        https://www.themoviedb.org/documentation/api/discover.
+
         Args:
-            page: (optional) Minimum 1, maximum 1000.
             language: (optional) ISO 639-1 code.
-            sort_by: (optional) Available options are 'vote_average.desc', 
+            sort_by: (optional) Available options are 'vote_average.desc',
-                     'vote_average.asc', 'first_air_date.desc', 
+                     'vote_average.asc', 'first_air_date.desc',
                      'first_air_date.asc', 'popularity.desc', 'popularity.asc'
-            first_air_year: (optional) Filter the results release dates to 
+            sort_by: (optional) Allowed values: vote_average.desc,
-                            matches that include this value. Expected value 
+                vote_average.asc, first_air_date.desc, first_air_date.asc,
-                            is a year.
+                popularity.desc, popularity.asc
-            vote_count.gte or vote_count_gte: (optional) Only include TV shows 
+                Default: popularity.desc
-                            that are equal to,
+            air_date.gte: (optional) Filter and only include TV shows that have
-                            or have vote count higher than this value. Expected
+                a air date (by looking at all episodes) that is greater or
-                            value is an integer.
+                equal to the specified value.
-            vote_average.gte or vote_average_gte: (optional) Only include TV 
+            air_date.lte: (optional) Filter and only include TV shows that have
-                              shows that are equal 
+                a air date (by looking at all episodes) that is less than or
-                              to, or have a higher average rating than this 
+                equal to the specified value.
-                              value.  Expected value is a float.
+            first_air_date.gte: (optional) Filter and only include TV shows
-            with_genres: (optional) Only include TV shows with the specified 
+                that have a original air date that is greater or equal to the
-                         genres. Expected value is an integer (the id of a 
+                specified value. Can be used in conjunction with the
-                         genre).  Multiple valued can be specified. Comma 
+                "include_null_first_air_dates" filter if you want to include
-                         separated indicates an 'AND' query, while a 
+                items with no air date.
-                         pipe (|) separated value indicates an 'OR'.
+            first_air_date.lte: (optional) Filter and only include TV shows
-            with_networks: (optional) Filter TV shows to include a specific 
+                that have a original air date that is less than or equal to the
-                           network. Expected value is an integer (the id of a
+                specified value. Can be used in conjunction with the
-                           network).  They can be comma separated to indicate an
+                "include_null_first_air_dates" filter if you want to include
-                           'AND' query.
+                items with no air date.
-            first_air_date.gte or first_air_date_gte: (optional) The minimum 
+            first_air_date_year: (optional) Filter and only include TV shows
-                                release to include. 
+                that have a original air date year that equal to the specified
-                                Expected format is 'YYYY-MM-DD'.
+                value. Can be used in conjunction with the
-            first_air_date.lte or first_air_date_lte: (optional) The maximum 
+                "include_null_first_air_dates" filter if you want to include
-                                release to include. 
+                items with no air date.
-                                Expected format is 'YYYY-MM-DD'.
+            page: (optional) Specify the page of results to query. Default 1.
-          
+            timezone: (optional) Used in conjunction with the air_date.gte/lte
+                filter to calculate the proper UTC offset. Default
+                America/New_York.
+            vote_average.gte: (optional) Filter and only include movies that
+                have a rating that is greater or equal to the specified value.
+                Minimum 0.
+            vote_count.gte: (optional) Filter and only include movies that have
+                a rating that is less than or equal to the specified value.
+                Minimum 0.
+            with_genres: (optional) Comma separated value of genre ids that you
+                want to include in the results.
+            with_networks: (optional) Comma separated value of network ids that
+                you want to include in the results.
+            without_genres: (optional) Comma separated value of genre ids that
+                you want to exclude from the results.
+            with_runtime.gte: (optional) Filter and only include TV shows with
+                an episode runtime that is greater than or equal to a value.
+            with_runtime.lte: (optional) Filter and only include TV shows with
+                an episode runtime that is less than or equal to a value.
+            include_null_first_air_dates: (optional) Use this filter to include
+                TV shows that don't have an air date while using any of the
+                "first_air_date" filters. 
+            with_original_language: (optional) Specify an ISO 639-1 string to
+                filter results by their original language value. 
+            without_keywords: (optional) Exclude items with certain keywords.
+                You can comma and pipe seperate these values to create an 'AND'
+                or 'OR' logic. 
+            screened_theatrically: (optional) Filter results to include items
+                that have been screened theatrically. 
+            with_companies: (optional) A comma separated list of production
+                company ID's. Only include movies that have one of the ID's
+                added as a production company. 
+            with_keywords: (optional) A comma separated list of keyword ID's.
+                Only includes TV shows that have one of the ID's added as a
+                keyword. 
+
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        # Periods are not allowed in keyword arguments but several API 
+        # Periods are not allowed in keyword arguments but several API
         # arguments contain periods. See both usages in tests/test_discover.py.
-        for param in kwargs:
+        for param in dict(kwargs):
             if '_lte' in param:
                 kwargs[param.replace('_lte', '.lte')] = kwargs.pop(param)
             if '_gte' in param:
                 kwargs[param.replace('_gte', '.gte')] = kwargs.pop(param)
-        
+
         path = self._get_path('tv')
 
         response = self._GET(path, kwargs)

lib/tmdbsimple/find.py

@@ -13,6 +13,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class Find(TMDB):
     """
     Find functionality.
@@ -23,24 +24,29 @@ class Find(TMDB):
     URLS = {
         'info': '/{id}',
     }
+
     def __init__(self, id=0):
         super(Find, self).__init__()
         self.id = id
 
     def info(self, **kwargs):
         """
-        Search for objects in the database by an external id. For instance,
+        The find method makes it easy to search for objects in our database by
-        an IMDB ID. This will search all objects (movies, TV shows and people) 
+        an external id. For example, an IMDB ID.
-        and return the results in a single response. TV season and TV episode 
-        searches will be supported shortly.
 
-        The supported external sources for each object are as follows:
+        This method will search all objects (movies, TV shows and people) and
-            Movies: imdb_id
+        return the results in a single response.
-            People: imdb_id, freebase_mid, freebase_id, tvrage_id
+
-            TV Series: imdb_id, freebase_mid, freebase_id, tvdb_id, tvrage_id
+        The supported external sources for each object are as follows.
+            Media Databases: IMDb ID, TVDB ID, Freebase MID*, Freebase ID*,
+                             TVRage ID*
+            Social IDs: Facebook, Insagram, Twitter
 
         Args:
-            external_source: See lists above.
+            language: (optional) ISO 639-1 code.
+            external_source: Allowed Values: imdb_id, freebase_mid,
+                freebase_id, tvdb_id, tvrage_id, facebook_id, twitter_id,
+                instagram_id 
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -50,3 +56,50 @@ class Find(TMDB):
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
+
+
+class Trending(TMDB):
+    """
+    Trending functionality.
+
+    See: https://developers.themoviedb.org/3/trending
+    """
+    BASE_PATH = 'trending'
+    URLS = {
+        'info': '/{media_type}/{time_window}',
+    }
+
+    def __init__(self, media_type='all', time_window='day'):
+        super(Trending, self).__init__()
+        self.media_type = media_type
+        self.time_window = time_window
+
+    def info(self, **kwargs):
+        """
+        Get the daily or weekly trending items. The daily trending list tracks
+        items over the period of a day while items have a 24 hour half life.
+        The weekly list tracks items over a 7 day period, with a 7 day half
+        life.
+
+        Valid Media Types
+            'all': Include all movies, TV shows and people in the results as a
+                   global trending list.
+            'movie': Show the trending movies in the results.
+            'tv': Show the trending TV shows in the results.
+            'people': Show the trending people in the results.
+
+        Valid Time Windows
+            'day': View the trending list for the day.
+            'week': View the trending list for the week.
+
+        Args:
+            None
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_media_type_time_window_path('info')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response

lib/tmdbsimple/genres.py

@@ -24,7 +24,7 @@ class Genres(TMDB):
     URLS = {
         'movie_list': '/movie/list',
         'tv_list': '/tv/list',
-        'movies': '/{id}/movies',
+        'movies': '/{id}/movies',    # backward compatability
     }
 
     def __init__(self, id=0):
@@ -33,7 +33,7 @@ class Genres(TMDB):
 
     def movie_list(self, **kwargs):
         """
-        Get the list of Movie genres.
+        Get the list of official genres for movies.
 
         Args:
             language: (optional) ISO 639-1 code.
@@ -49,7 +49,7 @@ class Genres(TMDB):
 
     def tv_list(self, **kwargs):
         """
-        Get the list of TV genres.
+        Get the list of official genres for TV shows.
 
         Args:
             language: (optional) ISO 639-1 code.
@@ -63,6 +63,7 @@ class Genres(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    # backward compatability
     def movies(self, **kwargs):
         """
         Get the list of movies for a particular genre by id. By default, only
@@ -71,8 +72,8 @@ class Genres(TMDB):
         Args:
             page: (optional) Minimum 1, maximum 1000.
             language: (optional) ISO 639-1 code.
-            include_all_movies: (optional) Toggle the inclusion of all movies 
+            include_all_movies: (optional) Toggle the inclusion of all movies
-                                and not just those with 10 or more ratings. 
+                                and not just those with 10 or more ratings.
                                 Expected value is: True or False.
             include_adult: (optional) Toggle the inclusion of adult titles.
                            Expected value is: True or False.

lib/tmdbsimple/movies.py

@@ -14,6 +14,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class Movies(TMDB):
     """
     Movies functionality.
@@ -23,27 +24,28 @@ class Movies(TMDB):
     BASE_PATH = 'movie'
     URLS = {
         'info': '/{id}',
+        'account_states': '/{id}/account_states',
         'alternative_titles': '/{id}/alternative_titles',
+        'changes': '/{id}/changes',
         'credits': '/{id}/credits',
         'external_ids': '/{id}/external_ids',
         'images': '/{id}/images',
         'keywords': '/{id}/keywords',
         'release_dates': '/{id}/release_dates',
-        'releases': '/{id}/releases',
         'videos': '/{id}/videos',
         'translations': '/{id}/translations',
+        'recommendations': '/{id}/recommendations',
         'similar_movies': '/{id}/similar_movies',
         'reviews': '/{id}/reviews',
         'lists': '/{id}/lists',
-        'changes': '/{id}/changes',
+        'rating': '/{id}/rating',
+        'rating_delete': '/{id}/rating',
         'latest': '/latest',
-        'upcoming': '/upcoming',
         'now_playing': '/now_playing',
         'popular': '/popular',
         'top_rated': '/top_rated',
-        'account_states': '/{id}/account_states',
+        'upcoming': '/upcoming',
-        'rating': '/{id}/rating',
+        'releases': '/{id}/releases',   # backward compatability
-        'recommendations': '/{id}/recommendations'
     }
 
     def __init__(self, id=0):
@@ -52,11 +54,15 @@ class Movies(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the basic movie information for a specific movie id.
+        Get the primary information about a movie.
+
+        Supports append_to_response. Read more about this at
+        https://developers.themoviedb.org/3/getting-started/append-to-response.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
+            append_to_response: (optional) Append requests within the same
+                namespace to the response.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -67,13 +73,32 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def account_states(self, **kwargs):
+        """
+        Grab the following account states for a session:
+            - Movie rating
+            - If it belongs to your watchlist
+            - If it belongs to your favourite list
+
+        Args:
+            session_id: (required) See Authentication.
+            guest_session_id: (optional) See Authentication.
+
+        Returns:
+            A dict representation of the JSON returned from the API.
+        """
+        path = self._get_id_path('account_states')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
     def alternative_titles(self, **kwargs):
         """
-        Get the alternative titles for a specific movie id.
+        Get all of the alternative titles for a movie.
 
         Args:
             country: (optional) ISO 3166-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -84,12 +109,35 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def changes(self, **kwargs):
+        """
+        Get the changes for a movie. By default only the last 24 hours are returned.
+
+        You can query up to 14 days in a single query by using the start_date
+        and end_date query parameters.
+
+        Args:
+            start_date: (optional) Filter the results with a start date.
+                Expected format is 'YYYY-MM-DD'.
+            end_date: (optional) Filter the results with a end date.
+                Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+
+        Returns:
+            A dict representation of the JSON returned from the API.
+        """
+        path = self._get_id_path('changes')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
     def credits(self, **kwargs):
         """
-        Get the cast and crew information for a specific movie id.
+        Get the cast and crew for a movie.
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
+            None
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -102,11 +150,14 @@ class Movies(TMDB):
 
     def external_ids(self, **kwargs):
         """
-        Get the external ids for a specific movie id.
+        Get the external ids for a movie. We currently support the following
+        external sources.
+
+        Media Databases - IMDb
+        Social IDs - Facebok, Instagram, Twitter
 
         Args:
-            language: (optional) ISO 639-1 code.
+            None
-            append_to_response: (optional) Comma separated, any movie method.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -119,11 +170,16 @@ class Movies(TMDB):
 
     def images(self, **kwargs):
         """
-        Get the images (posters and backdrops) for a specific movie id.
+        Get the images that belong to a movie.
+
+        Querying images with a language parameter will filter the results. If
+        you want to include a fallback language (especially useful for
+        backdrops) you can use the include_image_language parameter. This
+        should be a comma seperated value like so:
+        include_image_language=en,null.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
             include_image_language: (optional) Comma separated, a valid
                                     ISO 69-1.
 
@@ -138,7 +194,10 @@ class Movies(TMDB):
 
     def keywords(self):
         """
-        Get the plot keywords for a specific movie id.
+        Get the keywords that have been added to a movie.
+
+        Args:
+            None
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -149,29 +208,21 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def recommendations(self, **kwargs):
+    def release_dates(self, **kwargs):
-        """
-        Get a list of recommended movies for a movie.
-
-        Args:
-            language: (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1.  Expected value is an integer.
-
-        Returns:
-            A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('recommendations')
+        Get the release date along with the certification for a movie.
 
-        response = self._GET(path, kwargs)
+        Release dates support different types:
-        self._set_attrs_to_values(response)
-        return response
 
-    def release_dates(self, **kwargs):
+            1. Premiere
-        """
+            2. Theatrical (limited)
-        Get the release dates and certification for a specific movie id.
+            3. Theatrical
+            4. Digital
+            5. Physical
+            6. TV
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
+            None
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -182,51 +233,50 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def releases(self, **kwargs):
+    def videos(self, **kwargs):
         """
-        Get the release date and certification information by country for a
+        Get the videos that have been added to a movie.
-        specific movie id.
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
+            language: (optional) ISO 639-1 code.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('releases')
+        path = self._get_id_path('videos')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def videos(self, **kwargs):
+    def translations(self, **kwargs):
         """
-        Get the videos (trailers, teasers, clips, etc...) for a
+        Get a list of translations that have been created for a movie.
-        specific movie id.
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
+            None
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('videos')
+        path = self._get_id_path('translations')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def translations(self, **kwargs):
+    def recommendations(self, **kwargs):
         """
-        Get the translations for a specific movie id.
+        Get a list of recommended movies for a movie.
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
+            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('translations')
+        path = self._get_id_path('recommendations')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
@@ -234,12 +284,14 @@ class Movies(TMDB):
 
     def similar_movies(self, **kwargs):
         """
-        Get the similar movies for a specific movie id.
+        Get a list of similar movies. This is not the same as the
+        "Recommendation" system you see on the website.
+
+        These items are assembled by looking at keywords and genres.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -252,12 +304,11 @@ class Movies(TMDB):
 
     def reviews(self, **kwargs):
         """
-        Get the reviews for a particular movie id.
+        Get the user reviews for a movie.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -270,12 +321,11 @@ class Movies(TMDB):
 
     def lists(self, **kwargs):
         """
-        Get the lists that the movie belongs to.
+        Get a list of lists that this movie belongs to.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -286,54 +336,70 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def changes(self, **kwargs):
+    def rating(self, **kwargs):
         """
-        Get the changes for a specific movie id.
+        Rate a movie.
 
-        Changes are grouped by key, and ordered by date in descending order.
+        A valid session or guest session ID is required. You can read more
-        By default, only the last 24 hours of changes are returned. The
+        about how this works at
-        maximum number of days that can be returned in a single request is 14.
+        https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.
-        The language is present on fields that are translatable.
 
         Args:
-            start_date: (optional) Expected format is 'YYYY-MM-DD'.
+            session_id: (optional) See Authentication.
-            end_date: (optional) Expected format is 'YYYY-MM-DD'.
+            guest_session_id: (optional) See Authentication.
+            value: (required) This is the value of the rating you want to
+                submit. The value is expected to be between 0.5 and 10.0.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('changes')
+        path = self._get_id_path('rating')
 
-        response = self._GET(path, kwargs)
+        payload = {
+            'value': kwargs.pop('value', None),
+        }
+
+        response = self._POST(path, kwargs, payload)
         self._set_attrs_to_values(response)
         return response
 
-    def latest(self, **kwargs):
+    def rating_delete(self, **kwargs):
         """
-        Get the latest movie id.
+        Remove your rating for a movie.
+
+        A valid session or guest session ID is required. You can read more
+        about how this works at
+        https://developers.themoviedb.org/3/authentication/how-do-i-generate-a-session-id.
+
+        Args:
+            session_id: (optional) See Authentication.
+            guest_session_id: (optional) See Authentication.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_path('latest')
+        path = self._get_id_path('rating_delete')
 
-        response = self._GET(path, kwargs)
+        payload = {
+            'value': kwargs.pop('value', None),
+        }
+
+        response = self._DELETE(path, kwargs, payload)
         self._set_attrs_to_values(response)
         return response
 
-    def upcoming(self, **kwargs):
+    def latest(self, **kwargs):
         """
-        Get the list of upcoming movies. This list refreshes every day.
+        Get the most newly created movie. This is a live response and will
-        The maximum number of items this list will include is 100.
+        continuously change.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_path('upcoming')
+        path = self._get_path('latest')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
@@ -341,12 +407,19 @@ class Movies(TMDB):
 
     def now_playing(self, **kwargs):
         """
-        Get the list of movies playing in theatres. This list refreshes
+        Get a list of movies in theatres. This is a release type query that
-        every day. The maximum number of items this list will include is 100.
+        looks for all movies that have a release type of 2 or 3 within the
+        specified date range.
+
+        You can optionally specify a region prameter which will narrow the
+        search to only look for theatrical release dates within the specified
+        country.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -359,12 +432,14 @@ class Movies(TMDB):
 
     def popular(self, **kwargs):
         """
-        Get the list of popular movies on The Movie Database. This list
+        Get a list of the current popular movies on TMDb. This list updates
-        refreshes every day.
+        daily.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -377,13 +452,13 @@ class Movies(TMDB):
 
     def top_rated(self, **kwargs):
         """
-        Get the list of top rated movies. By default, this list will only
+        Get the top rated movies on TMDb.
-        include movies that have 10 or more votes. This list refreshes every
-        day.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -394,44 +469,46 @@ class Movies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def account_states(self, **kwargs):
+    def upcoming(self, **kwargs):
         """
-        This method lets users get the status of whether or not the movie has
+        Get a list of upcoming movies in theatres. This is a release type query
-        been rated or added to their favourite or watch lists. A valid session
+        that looks for all movies that have a release type of 2 or 3 within the
-        id is required.
+        specified date range.
+
+        You can optionally specify a region prameter which will narrow the
+        search to only look for theatrical release dates within the specified
+        country.
 
         Args:
-            session_id: see Authentication.
+            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('account_states')
+        path = self._get_path('upcoming')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def rating(self, **kwargs):
+    # backward compatability
+    def releases(self, **kwargs):
         """
-        This method lets users rate a movie. A valid session id or guest
+        Get the release date and certification information by country for a
-        session id is required.
+        specific movie id.
 
         Args:
-            session_id: see Authentication.
+            None
-            guest_session_id: see Authentication.
-            value: Rating value.
 
         Returns:
             A dict representation of the JSON returned from the API.
         """
-        path = self._get_id_path('rating')
+        path = self._get_id_path('releases')
-
-        payload = {
-            'value': kwargs.pop('value', None),
-        }
 
-        response = self._POST(path, kwargs, payload)
+        response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
@@ -446,6 +523,7 @@ class Collections(TMDB):
     URLS = {
         'info': '/{id}',
         'images': '/{id}/images',
+        'translations': '/{id}/translations',
     }
 
     def __init__(self, id):
@@ -454,16 +532,10 @@ class Collections(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the basic collection information for a specific collection id.
+        Get collection details by id.
-        You can get the ID needed for this method by making a /movie/{id}
-        request and paying attention to the belongs_to_collection hash.
-
-        Movie parts are not sorted in any particular order. If you would like
-        to sort them yourself you can use the provided release_date.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -476,13 +548,10 @@ class Collections(TMDB):
 
     def images(self, **kwargs):
         """
-        Get all of the images for a particular collection by collection id.
+        Get the images for a collection by id.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
-            include_image_language: (optional) Comma separated, a valid
-            ISO 69-1.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -493,6 +562,23 @@ class Collections(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def translations(self, **kwargs):
+        """
+        Get a list of the translations for a collection by id.
+
+        Args:
+            language: (optional) ISO 639-1 code.
+
+        Returns:
+            A dict representation of the JSON returned from the API.
+        """
+        path = self._get_id_path('translations')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+
 class Companies(TMDB):
     """
     Companies functionality.
@@ -502,7 +588,9 @@ class Companies(TMDB):
     BASE_PATH = 'company'
     URLS = {
         'info': '/{id}',
-        'movies': '/{id}/movies',
+        'alternative_names': '/{id}/alternative_names',
+        'images': '/{id}/images',
+        'movies': '/{id}/movies',    # backward compatability
     }
 
     def __init__(self, id=0):
@@ -511,11 +599,9 @@ class Companies(TMDB):
 
     def info(self, **kwargs):
         """
-        This method is used to retrieve all of the basic information about a
+        Get a companies details by id.
-        company.
 
         Args:
-            append_to_response: (optional) Comma separated, any movie method.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -526,14 +612,54 @@ class Companies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def alternative_names(self, **kwargs):
+        """
+        Get the alternative names of a company.
+
+        Args:
+
+        Returns:
+            A dict representation of the JSON returned from the API.
+        """
+        path = self._get_id_path('alternative_names')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    def images(self, **kwargs):
+        """
+        Get a company's logos by id.
+
+        There are two image formats that are supported for companies, PNG's and
+        SVG's. You can see which type the original file is by looking at the
+        file_type field. We prefer SVG's as they are resolution independent and
+        as such, the width and height are only there to reflect the original
+        asset that was uploaded.  An SVG can be scaled properly beyond those
+        dimensions if you call them as a PNG.
+
+        For more information about how SVG's and PNG's can be used, take a read
+        through https://developers.themoviedb.org/3/getting-started/images.
+
+        Args:
+
+        Returns:
+            A dict representation of the JSON returned from the API.
+        """
+        path = self._get_id_path('images')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
+    # backward compatability
     def movies(self, **kwargs):
         """
         Get the list of movies associated with a particular company.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any movie method.
+            page: (optional) Minimum value of 1.  Expected value is an integer.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -544,6 +670,7 @@ class Companies(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+
 class Keywords(TMDB):
     """
     Keywords functionality.
@@ -562,7 +689,10 @@ class Keywords(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the basic information for a specific keyword id.
+        Get the details of a keyword.
+
+        Args:
+           None
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -575,11 +705,15 @@ class Keywords(TMDB):
 
     def movies(self, **kwargs):
         """
-        Get the list of movies for a particular keyword by id.
+        Get the movies that belong to a keyword.
+
+        We highly recommend using movie discover instead of this method as it
+        is much more flexible.
 
         Args:
-            page: (optional) Minimum value of 1.  Expected value is an integer.
             language: (optional) ISO 639-1 code.
+            include_adult: Choose whether to inlcude adult (pornography)
+                content in the results.
 
         Returns:
             A dict representation of the JSON returned from the API.
@@ -590,6 +724,7 @@ class Keywords(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+
 class Reviews(TMDB):
     """
     Reviews functionality.
@@ -607,7 +742,10 @@ class Reviews(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the full details of a review by ID.
+        Get the review details by id.
+
+        Args:
+            None
 
         Returns:
             A dict representation of the JSON returned from the API.

lib/tmdbsimple/people.py

@@ -3,8 +3,7 @@
 """
 tmdbsimple.people
 ~~~~~~~~~~~~~~~~~
-This module implements the People, Credits, and Jobs functionality 
+This module implements the People and Credits functionality of tmdbsimple.
-of tmdbsimple.
 
 Created by Celia Oakley on 2013-10-31.
 
@@ -14,6 +13,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class People(TMDB):
     """
     People functionality.
@@ -23,14 +23,16 @@ class People(TMDB):
     BASE_PATH = 'person'
     URLS = {
         'info': '/{id}',
+        'changes': '/{id}/changes',
         'movie_credits': '/{id}/movie_credits',
         'tv_credits': '/{id}/tv_credits',
         'combined_credits': '/{id}/combined_credits',
         'external_ids': '/{id}/external_ids',
         'images': '/{id}/images',
-        'changes': '/{id}/changes',
+        'tagged_images': '/{id}/tagged_images',
-        'popular': '/popular',
+        'translations': '/{id}/translations',
         'latest': '/latest',
+        'popular': '/popular',
     }
 
     def __init__(self, id=0):
@@ -39,10 +41,15 @@ class People(TMDB):
 
     def info(self, **kwargs):
         """
-        Get the general person information for a specific id.
+        Get the primary person details by id.
+
+        Supports append_to_response. Read more about this at
+        https://developers.themoviedb.org/3/getting-started/append-to-response.
 
         Args:
-            append_to_response: (optional) Comma separated, any person method.
+            language: (optional) ISO 639-1 code.
+            append_to_response: (optional) Append requests within the same
+                namespace to the response.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -53,13 +60,35 @@ class People(TMDB):
         self._set_attrs_to_values(response)
         return response
 
+    def changes(self, **kwargs):
+        """
+        Get the changes for a person. By default only the last 24 hours are returned.
+
+        You can query up to 14 days in a single query by using the start_date
+        and end_date query parameters.
+
+        Args:
+            start_date: (optional) Filter the results with a start date.
+                Expected format is 'YYYY-MM-DD'.
+            end_date: (optional) Filter the results with a end date.
+                Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+
+        Returns:
+            A dict respresentation of the JSON returned from the API.
+        """
+        path = self._get_id_path('changes')
+
+        response = self._GET(path, kwargs)
+        self._set_attrs_to_values(response)
+        return response
+
     def movie_credits(self, **kwargs):
         """
-        Get the movie credits for a specific person id.
+        Get the movie credits for a person.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any person method.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -72,11 +101,13 @@ class People(TMDB):
 
     def tv_credits(self, **kwargs):
         """
-        Get the TV credits for a specific person id.
+        Get the TV show credits for a person.
+
+        You can query for some extra details about the credit with the credit
+        method.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any person method.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -89,15 +120,10 @@ class People(TMDB):
 
     def combined_credits(self, **kwargs):
         """
-        Get the combined (movie and TV) credits for a specific person id.
+        Get the movie and TV credits together in a single response.
-
-        To get the expanded details for each TV record, call the /credit method 
-        with the provided credit_id. This will provide details about which 
-        episode and/or season the credit is for.
 
         Args:
             language: (optional) ISO 639-1 code.
-            append_to_response: (optional) Comma separated, any person method.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -110,7 +136,19 @@ class People(TMDB):
 
     def external_ids(self, **kwargs):
         """
-        Get the external ids for a specific person id.
+        Get the external ids for a person. We currently support the following external sources.
+
+        External Sources
+            - IMDB ID
+            - Facebook
+            - Freebase MID
+            - Freebase ID
+            - Instagram
+            - TVRage ID
+            - Twitter
+
+        Args:
+            language: (optional) ISO 639-1 code.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -123,7 +161,10 @@ class People(TMDB):
 
     def images(self, **kwargs):
         """
-        Get the images for a specific person id.
+        Get the images for a person.
+
+        Args:
+            None
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -134,40 +175,34 @@ class People(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def changes(self, **kwargs):
+    def tagged_images(self, **kwargs):
         """
-        Get the changes for a specific person id.
+        Get the images that this person has been tagged in.
-
-        Changes are grouped by key, and ordered by date in descending order. 
-        By default, only the last 24 hours of changes are returned. The maximum 
-        number of days that can be returned in a single request is 14. The 
-        language is present on fields that are translatable.
 
         Args:
-            start_date: (optional) Expected format is 'YYYY-MM-DD'.
+            language: (optional) ISO 639-1 code.
-            end_date: (optional) Expected format is 'YYYY-MM-DD'.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_id_path('changes')
+        path = self._get_id_path('tagged_images')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def popular(self, **kwargs):
+    def translations(self, **kwargs):
         """
-        Get the list of popular people on The Movie Database. This list 
+        Get a list of translations that have been created for a person.
-        refreshes every day.
 
         Args:
-            page: (optional) Minimum 1, maximum 1000.
+            language: (optional) ISO 639-1 code.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('popular')
+        path = self._get_id_path('translations')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
@@ -175,7 +210,11 @@ class People(TMDB):
 
     def latest(self, **kwargs):
         """
-        Get the latest person id.
+        Get the most newly created person. This is a live response and will
+        continuously change.
+
+        Args:
+            language: (optional) ISO 639-1 code.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -186,67 +225,51 @@ class People(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-class Credits(TMDB):
+    def popular(self, **kwargs):
-    """
-    Credits functionality.
-
-    See: https://developers.themoviedb.org/3/credits
-    """
-    BASE_PATH = 'credit'
-    URLS = {
-        'info': '/{credit_id}',
-    }
-
-    def __init__(self, credit_id):
-        super(Credits, self).__init__()
-        self.credit_id = credit_id
-
-    def info(self, **kwargs):
         """
-        Get the detailed information about a particular credit record. This is 
+        Get the list of popular people on TMDb. This list updates daily.
-        currently only supported with the new credit model found in TV. These 
-        ids can be found from any TV credit response as well as the tv_credits 
-        and combined_credits methods for people.
-
-        The episodes object returns a list of episodes and are generally going 
-        to be guest stars. The season array will return a list of season 
-        numbers.  Season credits are credits that were marked with the 
-        "add to every season" option in the editing interface and are 
-        assumed to be "season regulars".
 
         Args:
             language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_credit_id_path('info')
+        path = self._get_path('popular')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-class Jobs(TMDB):
+
+class Credits(TMDB):
     """
-    Jobs functionality.
+    Credits functionality.
 
-    See: https://developers.themoviedb.org/3/jobs
+    See: https://developers.themoviedb.org/3/credits
     """
-    BASE_PATH = 'job'
+    BASE_PATH = 'credit'
     URLS = {
-        'list': '/list',
+        'info': '/{credit_id}',
     }
 
-    def list(self, **kwargs):
+    def __init__(self, credit_id):
+        super(Credits, self).__init__()
+        self.credit_id = credit_id
+
+    def info(self, **kwargs):
         """
-        Get a list of valid jobs.
+        Get a movie or TV credit details by id.
+
+        Args:
+            None
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('list')
+        path = self._get_credit_id_path('info')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
-        

lib/tmdbsimple/search.py

@@ -13,6 +13,7 @@ Created by Celia Oakley on 2013-10-31.
 
 from .base import TMDB
 
+
 class Search(TMDB):
     """
     Search functionality
@@ -21,40 +22,28 @@ class Search(TMDB):
     """
     BASE_PATH = 'search'
     URLS = {
-        'movie': '/movie',
-        'collection': '/collection',
-        'tv': '/tv',
-        'person': '/person',
         'company': '/company',
+        'collection': '/collection',
         'keyword': '/keyword',
-        'multi': '/multi'
+        'movie': '/movie',
+        'multi': '/multi',
+        'person': '/person',
+        'tv': '/tv',
     }
 
-    def movie(self, **kwargs):
+    def company(self, **kwargs):
         """
-        Search for movies by title.
+        Search for companies.
 
         Args:
-            query: CGI escpaed string.
+            query: (required) Pass a text query to search. This value should be
-            page: (optional) Minimum value of 1. Expected value is an integer.
+                URI encoded.
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
-            include_adult: (optional) Toggle the inclusion of adult titles. 
-                           Expected value is True or False.
-            year: (optional) Filter the results release dates to matches that 
-                  include this value.
-            primary_release_year: (optional) Filter the results so that only 
-                                  the primary release dates have this value.
-            search_type: (optional) By default, the search type is 'phrase'. 
-                         This is almost guaranteed the option you will want. 
-                         It's a great all purpose search type and by far the 
-                         most tuned for every day querying. For those wanting 
-                         more of an "autocomplete" type search, set this 
-                         option to 'ngram'.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('movie')
+        path = self._get_path('company')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
@@ -62,12 +51,13 @@ class Search(TMDB):
 
     def collection(self, **kwargs):
         """
-        Search for collections by name.
+        Search for collections.
 
         Args:
-            query: CGI escpaed string.
+            language: (optional) (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1. Expected value is an integer.
+            query: (required) Pass a text query to search. This value should be
-            language: (optional) ISO 639-1 code.
+                URI encoded.
+            page: (optional) Minimum 1, maximum 1000, default 1.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
@@ -78,106 +68,116 @@ class Search(TMDB):
         self._set_attrs_to_values(response)
         return response
 
-    def tv(self, **kwargs):
+    def keyword(self, **kwargs):
         """
-        Search for TV shows by title.
+        Search for keywords.
 
         Args:
-            query: CGI escpaed string.
+            query: (required) Pass a text query to search. This value should be
-            page: (optional) Minimum value of 1. Expected value is an integer.
+                URI encoded.
-            language: (optional) ISO 639-1 code.
+            page: (optional) Minimum 1, maximum 1000, default 1.
-            first_air_date_year: (optional) Filter the results to only match 
-                                 shows that have a air date with with value.
-            search_type: (optional) By default, the search type is 'phrase'. 
-                         This is almost guaranteed the option you will want. 
-                         It's a great all purpose search type and by far the 
-                         most tuned for every day querying. For those wanting 
-                         more of an "autocomplete" type search, set this 
-                         option to 'ngram'.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('tv')
+        path = self._get_path('keyword')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def person(self, **kwargs):
+    def movie(self, **kwargs):
         """
-        Search for people by name.
+        Search for movies.
 
         Args:
-            query: CGI escpaed string.
+            language: (optional) (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1. Expected value is an integer.
+            query: (required) Pass a text query to search. This value should be
-            include_adult: (optional) Toggle the inclusion of adult titles. 
+                URI encoded.
-                           Expected value is True or False.
+            page: (optional) Minimum 1, maximum 1000, default 1.
-            search_type: (optional) By default, the search type is 'phrase'. 
+            include_adult: (optional) Choose whether to inlcude adult
-                         This is almost guaranteed the option you will want. 
+                (pornography) content in the results.
-                         It's a great all purpose search type and by far the 
+            region: (optional) Specify a ISO 3166-1 code to filter release
-                         most tuned for every day querying. For those wanting 
+                dates. Must be uppercase.
-                         more of an "autocomplete" type search, set this 
+            year: (optional) A filter to limit the results to a specific year
-                         option to 'ngram'.
+                (looking at all release dates).
+            primary_release_year: (optional) A filter to limit the results to a
+                specific primary release year.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('person')
+        path = self._get_path('movie')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def company(self, **kwargs):
+    def multi(self, **kwargs):
         """
-        Search for companies by name.
+        Search multiple models in a single request. Multi search currently
+        supports searching for movies, tv shows and people in a single request.
 
         Args:
-            query: CGI escpaed string.
+            language: (optional) (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1. Expected value is an integer.
+            query: (required) Pass a text query to search. This value should be
+                URI encoded.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            include_adult: (optional) Choose whether to inlcude adult
+                (pornography) content in the results.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('company')
+        path = self._get_path('multi')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def keyword(self, **kwargs):
+    def person(self, **kwargs):
         """
-        Search for keywords by name.
+        Search for people.
 
         Args:
-            query: CGI escpaed string.
+            language: (optional) (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1. Expected value is an integer.
+            query: (required) Pass a text query to search. This value should be
+                URI encoded.
+            page: (optional) Minimum 1, maximum 1000, default 1.
+            include_adult: (optional) Choose whether to inlcude adult
+                (pornography) content in the results.
+            region: (optional) Specify a ISO 3166-1 code to filter release
+                dates. Must be uppercase.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('keyword')
+        path = self._get_path('person')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)
         return response
 
-    def multi(self, **kwargs):
+    def tv(self, **kwargs):
         """
-        Search the movie, tv show and person collections with a single query.
+        Search for a TV show.
 
         Args:
-            query: CGI escpaed string.
+            language: (optional) (optional) ISO 639-1 code.
-            page: (optional) Minimum value of 1. Expected value is an integer.
+            query: (required) Pass a text query to search. This value should be
-            language: (optional) ISO 639-1 code.
+                URI encoded.
-            include_adult: (optional) Toggle the inclusion of adult titles.
+            page: (optional) Minimum 1, maximum 1000, default 1.
-                           Expected value is True or False.
+            include_adult: (optional) Choose whether to inlcude adult
+                (pornography) content in the results.
+            first_air_date_year: (optional) Filter the results to only match
+                shows that have an air date with with value.
 
         Returns:
             A dict respresentation of the JSON returned from the API.
         """
-        path = self._get_path('multi')
+        path = self._get_path('tv')
 
         response = self._GET(path, kwargs)
         self._set_attrs_to_values(response)