tessl/pypi-cinemagoer

Python package for retrieving and managing data from the Internet Movie Database (IMDb) about movies, people, characters and companies

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Movie Operations

Name: tessl/pypi-cinemagoer
Author: tessl

Comprehensive movie search, retrieval, and information management including search functionality, detailed information retrieval, and specialized movie lists and charts.

Capabilities

Movie Search

Search for movies by title with configurable result limits and search options.

def search_movie(title, results=None):
    """
    Search for movies by title.
    
    Parameters:
    - title: str - Movie title to search for
    - results: int, optional - Maximum number of results (default: instance default)
    
    Returns:
    list: List of Movie objects with basic information
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Basic movie search
movies = ia.search_movie('The Matrix')
print(f"Found {len(movies)} movies")
for movie in movies[:3]:
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")

# Limited results
movies = ia.search_movie('Matrix', results=5)

Advanced Movie Search

Advanced movie search with multiple criteria and sorting options.

def search_movie_advanced(title=None, adult=None, results=None, sort=None, sort_dir=None):
    """
    Advanced search for movies with multiple criteria.
    
    Parameters:
    - title: str, optional - Movie title
    - adult: bool, optional - Include adult content
    - results: int, optional - Maximum number of results
    - sort: str, optional - Sort criteria
    - sort_dir: str, optional - Sort direction ('asc', 'desc')
    
    Returns:
    list: List of Movie objects matching criteria
    """

Episode Search

Search specifically for TV series episodes.

def search_episode(title, results=None):
    """
    Search for TV series episodes by title.
    
    Parameters:
    - title: str - Episode title to search for
    - results: int, optional - Maximum number of results
    
    Returns:
    list: List of Movie objects representing episodes
    """

Movie Retrieval

Retrieve detailed movie information by IMDb ID with configurable information sets.

def get_movie(movieID, info=('main', 'plot'), modFunct=None):
    """
    Get movie by ID with specified information sets.
    
    Parameters:
    - movieID: str - Movie ID (internal or IMDb format)
    - info: tuple/list - Information sets to retrieve ('main', 'plot', 'full_credits', etc.)
    - modFunct: function, optional - String modification function
    
    Returns:
    Movie: Movie object with requested information
    
    See also: Data Container Classes for Movie object details
    """

Available Information Sets:

'main' - Basic movie information (title, year, rating, etc.)
'plot' - Plot summaries and synopses
'full_credits' - Complete cast and crew information
'awards' - Awards and nominations
'taglines' - Movie taglines
'keywords' - Associated keywords
'quotes' - Memorable quotes
'trivia' - Trivia and facts
'goofs' - Mistakes and goofs
'connections' - Related movies
'technical' - Technical specifications
'locations' - Filming locations
'soundtrack' - Soundtrack information
'reviews' - User reviews
'episodes' - TV series episodes
'faqs' - Frequently asked questions

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get movie with basic info
movie = ia.get_movie('0133093')  # The Matrix
print(f"Title: {movie['title']}")
print(f"Year: {movie['year']}")

# Get movie with multiple info sets
movie = ia.get_movie('0133093', info=['main', 'plot', 'full_credits'])
print(f"Plot: {movie['plot'][0]}")
print(f"Director: {movie['director'][0]['name']}")
print(f"Cast: {[actor['name'] for actor in movie['cast'][:5]]}")

Episode Retrieval

Alias for get_movie specifically for TV episodes.

get_episode = get_movie

Top Movie Charts

Retrieve various IMDb top movie lists and charts.

def get_top250_movies():
    """
    Get IMDb Top 250 movies list.
    
    Returns:
    list: List of Movie objects representing top 250 movies
    """

def get_bottom100_movies():
    """
    Get IMDb Bottom 100 movies list.
    
    Returns:
    list: List of Movie objects representing bottom 100 movies
    """

def get_top250_tv():
    """
    Get IMDb Top 250 TV shows list.
    
    Returns:
    list: List of Movie objects representing top 250 TV shows
    """

def get_popular100_movies():
    """
    Get 100 most popular movies.
    
    Returns:
    list: List of Movie objects representing most popular movies
    """

def get_popular100_tv():
    """
    Get 100 most popular TV shows.
    
    Returns:
    list: List of Movie objects representing most popular TV shows
    """

def get_top250_indian_movies():
    """
    Get top 250 Indian movies.
    
    Returns:
    list: List of Movie objects representing top Indian movies
    """

def get_boxoffice_movies():
    """
    Get current box office movies.
    
    Returns:
    list: List of Movie objects representing current box office hits
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get top movies
top_movies = ia.get_top250_movies()
print(f"#1 Movie: {top_movies[0]['title']} ({top_movies[0]['year']})")

# Get popular movies
popular = ia.get_popular100_movies()
print(f"Currently popular: {popular[0]['title']}")

Genre-Based Top Lists

Retrieve top movies and TV shows filtered by genre.

def get_top50_movies_by_genres(genres):
    """
    Get top 50 movies by genre(s).
    
    Parameters:
    - genres: str or list - Genre name or list of genre names
    
    Returns:
    list: List of Movie objects representing top movies in specified genres
    """

def get_top50_tv_by_genres(genres):
    """
    Get top 50 TV shows by genre(s).
    
    Parameters:
    - genres: str or list - Genre name or list of genre names
    
    Returns:
    list: List of Movie objects representing top TV shows in specified genres
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Single genre
action_movies = ia.get_top50_movies_by_genres('Action')

# Multiple genres
comedy_drama = ia.get_top50_movies_by_genres(['Comedy', 'Drama'])

# TV shows by genre
sci_fi_tv = ia.get_top50_tv_by_genres('Sci-Fi')

Movie Lists

Retrieve movies from specific IMDb lists by list ID.

def get_movie_list(list_id, results=None):
    """
    Get movies from IMDb list by ID.
    
    Parameters:
    - list_id: str - IMDb list ID
    - results: int, optional - Maximum number of results
    
    Returns:
    list: List of Movie objects from the specified list
    """

Movie Information Sets

Get available information sets for movie objects.

def get_movie_infoset():
    """
    Get list of available information sets for movies.
    
    Returns:
    list: Available information set names
    """

Series Season Updates

Update TV series with specific season information.

def update_series_seasons(movie, season_nums, override=0):
    """
    Update TV series movie object with specific seasons.
    
    Parameters:
    - movie: Movie - TV series Movie object
    - season_nums: list - List of season numbers to retrieve
    - override: int - Whether to override existing information (0/1)
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get TV series
series = ia.get_movie('0903747')  # Breaking Bad

# Update with specific seasons
ia.update_series_seasons(series, [1, 2, 3])

# Access season information
if 'episodes' in series:
    for season_num, episodes in series['episodes'].items():
        print(f"Season {season_num}: {len(episodes)} episodes")

Movie Object Integration

All movie search and retrieval functions return Movie objects that can be further updated with additional information:

from imdb import IMDb

ia = IMDb()

# Search and get basic movie
movies = ia.search_movie('Inception')
movie = movies[0]

# Update with additional information
ia.update(movie, info=['plot', 'full_credits', 'awards'])

# Access detailed information
print(f"Plot: {movie.get('plot', ['N/A'])[0]}")
print(f"Awards: {len(movie.get('awards', []))} awards")

See also: Data Container Classes for complete Movie object documentation.

Error Handling Best Practices

Common error scenarios and robust handling patterns for movie operations:

from imdb import IMDb, IMDbError, IMDbDataAccessError

ia = IMDb()

# Robust movie search with error handling
def safe_movie_search(title, max_results=5):
    try:
        movies = ia.search_movie(title, results=max_results)
        if not movies:
            print(f"No movies found for '{title}'")
            return []
        return movies
    except IMDbDataAccessError as e:
        print(f"Network/data access error: {e}")
        return []
    except IMDbError as e:
        print(f"IMDb error: {e}")
        return []

# Robust movie information retrieval
def safe_get_movie_info(movie_id, info_sets=['main', 'plot']):
    try:
        movie = ia.get_movie(movie_id, info=info_sets)
        return movie
    except IMDbDataAccessError as e:
        print(f"Cannot access movie {movie_id}: {e}")
        return None
    except IMDbError as e:
        print(f"Error retrieving movie {movie_id}: {e}")
        return None

# Safe chart operations with fallback
def get_top_movies_safe():
    try:
        return ia.get_top250_movies()
    except IMDbError as e:
        print(f"Cannot retrieve top movies: {e}")
        # Fallback to search for popular movies
        return ia.search_movie("popular", results=10)

Install with Tessl CLI