Metadata-Version: 1.0
Name: tmdb3
Version: 0.6.17
Summary: TheMovieDB.org APIv3 interface
Home-page: UNKNOWN
Author: UNKNOWN
Author-email: UNKNOWN
License: UNKNOWN
Description: ## PyTMDB3
        
        This Python module implements the v3 API for TheMovieDb.org, allowing access
        to movie and cast information, as well as related artwork. More information
        can be found at:
        
        http://help.themoviedb.org/kb/api/about-3
        
        ## Initial Access
        
        Access to the API requires a personal key. You can create one by signing up
        for an account on TheMovieDb.org, and generating one from your Account Details
        page. Once done, the PyTMDB3 module must be be given this key as follows:
        
          >>> from tmdb3 import set_key
          >>> set_key('your_api_key')
        
        ## Caching Engine
        
        In order to limit excessive usage against the online API server, the PyTMDB3
        module supports caching of requests. Cached data is keyed off the request URL,
        and is currently stored for one hour. This may get tuned further as the v3
        API gets increased usage, and official limits are set per host.
        
        There are currently two engines available for use. The 'null' engine merely
        discards all information, and is only intended for debugging use. The 'file'
        engine is defualt, and will store to '/tmp/pytmdb3.cache' unless configured
        otherwise. The cache engine can be configured as follows.
        
          >>> from tmdb3 import set_cache
          >>> set_cache('null')
          >>> set_cache(filename='/full/path/to/cache') # the 'file' engine is assumed
          >>> set_cache(filename='tmdb3.cache')         # relative paths are put in /tmp
          >>> set_cache(engine='file', filename='~/.tmdb3cache')
        
        ## Locale Configuration
        
        The previous v2 API supported language selection, but would fall through to
        the defaults for any fields that did not have language-specific values. The
        v3 API no longer performs this fall through, leaving it up to clients to
        optionally implement it on their own.
        
        The PyTMDB3 module supports the use of locales in two separate manners. One
        can define a global locale that is automatically used if not specified
        otherwise, or a specific locale can be supplied directly to searches and
        data queries using the 'locale=' keyword argument, which is then propogated
        through any subsequent queries made through those objects.
        
        Locale settings are controlled through two functions
        
          >>> from tmdb3 import get_locale, set_locale
          >>> get_locale()
          <Locale None_None>
          >>> set_locale()
          >>> get_locale()
          <Locale en_US>
          >>> set_locale('en', 'gb')
          >>> get_locale()
          <Locale en_GB>
          >>> get_locale('fr', 'fr')
          <Locale fr_FR>
        
        set_locale() is used to set the global default locale. It optionally accepts
        'language' and 'country' keyword arguments. If not supplied, it will attempt
        to pull such information from your environment. It also accepts a
        'fallthrough' keyword argument, which is used to control the language and 
        country filter fall through. This is disabled by default, meaning if a
        language is set, it will only return information specific to that language.
        
        get_locale() also accepts optional 'language' and 'country' keyword arguments,
        and can be used to generate locales to use directly, overriding the global
        configuration. If none are given, this instead returns the global
        configuration. Note that fall through behavior is applied module-wide, and
        individual locales cannot be used to change that behavior.
        
        ## Authentication
        
        This is not yet supported.
        
        ## Searching
        
        There are currently three search methods available for use: movies, people, 
        studios, lists, and collections. Search results from TheMovieDb are sent
        iteratively, twenty results per page. The search methods provided by the
        PyTMDB3 module return list-like structures that will automatically grab new
        pages as needed.
        
          >>> from tmdb3 import searchMovie
          >>> res = searchMovie('A New Hope')
          >>> res
          <Search Results: A New Hope>
          >>> len(res)
          4
          >>> res[0]
          <Movie 'Star Wars: Episode IV - A New Hope' (1977)>
        
        The movieSearch() method accepts an 'adult' keyword to allow adult content
        to be returned. By default, this is set to false and such content is filtered
        out. The people search method behaves similarly.
        
          >>> from tmdb import searchPerson
          >>> res = searchPerson('Hanks')
          >>> res
          <Search Results: Hanks>
          >>> res[0]
          <Person 'Tom Hanks'>
        
          >>> from tmdb import searchStudio
          >>> res = searchStudio('Sony Pictures')
          >>> res
          <Search Results: Sony Pictures>
          >>> res[0]
          <Studio 'Sony Pictures'>
        
        The movieSearch() method accepts a 'year' keyword, tell tell TMDB to filter
        for movies of only that specific year. There is a helper method,
        movieSearchWithYear(), which will process the release year from movie names
        where the year is contained in parentheses, as in:
        
          >>> from tmdb import searchMovieWithYear
          >>> list(searchMovieWithYear('Star Wars (1977)'))
          [<Movie 'Star Wars: Episode IV - A New Hope' (1977)>,
                        <Movie 'The Making of 'Star Wars'' (1977)>]
        
        
        ## Direct Queries
        
        There are currently four data types that support direct access: collections,
        movies, people, and studios. These each take a single integer ID as an
        argument. All data attributes are implemented as properties, and populated
        on-demand as used, rather than when the object is created.
        
          >>> from tmdb3 import Collection, Movie, Person, Studio
          >>> Collection(10)
          <Collection 'Star Wars Collection'>
          >>> Movie(11)
          <Movie 'Star Wars: Episode IV - A New Hope' (1977)>
          >>> Person(2)
          <Person 'Mark Hamill'>
          >>> Studio(1)
          <Studio 'Lucasfilm'>
        
        The Genre class cannot be called by id directly, however it does have a getAll
        classmethod, capable of returning all available genres for a specified
        language.
        
        ## Image Behavior
        
        TheMovieDb currently offers three types of artwork: backdrops, posters, and
        profiles. The three data queries above will each carry a default one of these
        and potentially a list of additionals to choose from. Each can be downloaded
        directly, or at one of several pre-scaled reduced resolutions. The PyTMDB3
        module provides a list of list of available sizes, and will generate a URL
        to download a requested size. Invalid sizes return an error
        
          >>> from tmdb3 import Movie
          >>> p = Movie(11).poster
          >>> p
          <Poster 'tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'>
          >>> p.sizes()
          [u'w92', u'w154', u'w185', u'w342', u'w500', u'original']
          >>> p.geturl()
          u'http://cf2.imgobject.com/t/p/original/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
          >>> p.geturl('w342')
          u'http://cf2.imgobject.com/t/p/w342/tvSlBzAdRE29bZe5yYWrJ2ds137.jpg'
          >>> p.geturl('w300')
          Traceback (most recent call last):
            File "<stdin>", line 1, in <module>
            File "tmdb3/tmdb_api.py", line 101, in geturl
              raise TMDBImageSizeError
          tmdb3.tmdb_exceptions.TMDBImageSizeError: None
        
        ## Trailers
        
        TheMovieDb offers access to trailers on Youtube and Apple, however their use
        is slightly different. Youtube trailers offer an individual file, while Apple
        trailers offer multiple sizes.
        
          >>> from tmdb3 import Movie
          >>> movie = Movie(27205)
          >>> movie.youtube_trailers
          [<YoutubeTrailer 'Trailer 1'>, <YoutubeTrailer 'Trailer 2'>]
          >>> movie.youtube_trailers[0].geturl()
          'http://www.youtube.com/watch?v=suIIHZqDR30'
          >>> movie.apple_trailers
          [<AppleTrailer 'Teaser'>, <AppleTrailer 'Trailer 1'>, <AppleTrailer 'Trailer 2'>]
          >>> movie.apple_trailers[0].sizes()
          [u'480p', u'720p', u'1080p']
          >>> movie.apple_trailers[0].geturl()
          u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_1080.mov'
          >>> movie.apple_trailers[0].geturl()
          u'http://pdl.warnerbros.com/wbmovies/inception/Inception_TRL1_480.mov'
        
        ## List of Available Data 
        
          type                  name
        
        Collection:
          integer               id
          string                name
          string                overview
          Backdrop              backdrop
          Poster                poster
          list(Movie)           members
          list(Backdrop)        backdrops
          list(Poster)          posters
        
        Movie:
          integer               id
          string                title               (language specific)
          string                originaltitle       (origin language)
          string                tagline
          string                overview
          integer               runtime
          integer               budget
          integer               revenue
          datetime              releasedate
          string                homepage
          string                IMDB reference id   ('ttXXXXXXX')
          Backdrop              backdrop
          Poster                poster
          float                 popularity
          float                 userrating
          integer               votes
          boolean               adult
          Collection            collection
          list(Genre)           genres
          list(Studio)          studios
          list(Country)         countries
          list(Language)        languages
          list(AlternateTitle)  alternate_titles
          list(Cast)            cast                (sorted by billing)
          list(Crew)            crew
          list(Backdrop)        backdrops
          list(Poster)          posters
          list(Keyword)         keywords
          dict(Release)         releases            (indexed by country)
          list(Translation)     translations
          list(Movie)           similar
          list(List)            lists
          list(Movie)           getSimilar()
          None                  setFavorite(bool)   mark favorite status for current user
          None                  setRating(int)      rate movie by current user
          None                  setWatchlist(bool)  mark watchlist status for current user
        
        Movie classmethods:
          Movie                 fromIMDB(imdbid)    special constructor for use with IMDb codes
          Movie                 latest()            gets latest movie added to database
          list(Movie)           nowplaying()        content currently in theater
          list(Movie)           mostpopular()       based off themoviedb.org page view counts
          list(Movie)           toprated()          based off themoviedb.org user ratings
          list(Movie)           upcoming()          curated list, typically contains 100 movies
          list(Movie)           favorites()         current user's favorite movies
          list(Movie)           ratedmovies()       movies rated by current user
          list(Movie)           watchlist()         movies marked to watch by current user
        
        List:
          hex string            id
          string                name
          string                author
          string                description
          integer               favorites           number of users that have marked list
          string                language
          integer               count
          Poster                poster
          list(Movie)           members
        
        Person:
          integer               id
          string                name
          string                biography
          datetime              dayofbirth
          datetime              dayofdeath
          string                homepage
          Profile               profile
          boolean               adult
          list(string)          aliases
          list(ReverseCast)     roles
          list(ReverseCrew)     crew
          list(Profile)         profiles
        
        Cast (derived from Person):
          string                character
          integer               order               (as appears in credits)
        
        Crew (derived from Person):
          string                job
          string                department
        
        ReverseCast (derived from Movie):
          string                character
        
        ReverseCrew (derived from Movie):
          string                job
          string                department
        
        Image:
          string                filename            (arbitrary alphanumeric code)
          float                 aspectratio         (not available for default images)
          integer               height              (not available for default images)
          integer               width               (not available for default images)
          integer               language            (not available for default images)
          float                 userrating
          integer               votes
          list(string)          sizes()
          string                geturl(size='original')
        
        Backdrop (derived from Image)
        Poster (derived from Image)
        Profile (derived from Image)
        Logo (derived from Image)
        
        AlternateTitle:
          string                country
          string                title
        
        Release:
          string                certification
          string                country
          datetime              releasedate
        
        Translation:
          string                name
          string                englishname
          string                language
        
        Genre:
          integer               id
          string                name
          list(Movie)           movies
        
        Genre classmethods:
          list(Genre)           getAll(language)    returns list of all genres
        
        Studio:
          integer               id
          string                name
          string                description
          string                headquarters
          Logo                  logo
          Studio                parent
          list(Movie)           movies
        
        Country:
          string                code
          string                name
        
        Language:
          string                code
          string                name
        
        Trailer:
          string                name
          string                size
          string                source
        
        YoutubeTrailer (derived from Trailer)
          string                geturl()
        
        AppleTrailer
          string                name
          dict(Trailer)         sources             (indexed by size)
          list(string)          sizes()
          string                geturl(size=None)
        
Platform: UNKNOWN
