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

Advanced Features

Name: tessl/pypi-cinemagoer
Author: tessl

Advanced functionality including URL/ID conversion, specialized charts, keyword operations, data updates, and utility methods for complex IMDb data operations.

ID and URL Conversion

IMDb ID Retrieval

Get IMDb IDs for objects or convert between different ID formats.

def get_imdbID(mop):
    """
    Get IMDb ID for Movie/Person/Character/Company object.
    
    Parameters:
    - mop: Movie/Person/Character/Company - Object to get IMDb ID for
    
    Returns:
    str: IMDb ID (e.g., '0133093' for movies, '0000158' for people)
    """

def get_imdbMovieID(movieID):
    """
    Convert internal movieID to IMDb ID.
    
    Parameters:
    - movieID: str - Internal movie ID
    
    Returns:
    str: IMDb movie ID
    """

def get_imdbPersonID(personID):
    """
    Convert internal personID to IMDb ID.
    
    Parameters:
    - personID: str - Internal person ID
    
    Returns:
    str: IMDb person ID
    """

def get_imdbCharacterID(characterID):
    """
    Convert internal characterID to IMDb ID.
    
    Parameters:
    - characterID: str - Internal character ID
    
    Returns:
    str: IMDb character ID
    """

def get_imdbCompanyID(companyID):
    """
    Convert internal companyID to IMDb ID.
    
    Parameters:
    - companyID: str - Internal company ID
    
    Returns:
    str: IMDb company ID
    """

Name/Title to IMDb ID Conversion

Convert text strings to IMDb IDs through search and matching.

def title2imdbID(title, kind=None):
    """
    Convert movie title to IMDb ID through search.
    
    Parameters:
    - title: str - Movie title in plain text format
    - kind: str, optional - Movie kind (movie, tv series, etc.)
    
    Returns:
    str or list: IMDb ID or list of IDs if multiple matches
    """

def name2imdbID(name):
    """
    Convert person name to IMDb ID through search.
    
    Parameters:
    - name: str - Person name
    
    Returns:
    str: IMDb person ID or None if not found
    """

def character2imdbID(name):
    """
    Convert character name to IMDb ID through search.
    
    Parameters:
    - name: str - Character name
    
    Returns:
    str: IMDb character ID or None if not found
    """

def company2imdbID(name):
    """
    Convert company name to IMDb ID through search.
    
    Parameters:
    - name: str - Company name
    
    Returns:
    str: IMDb company ID or None if not found
    """

URL Generation

Generate IMDb URLs for objects.

def get_imdbURL(mop):
    """
    Get IMDb URL for Movie/Person/Character/Company object.
    
    Parameters:
    - mop: Movie/Person/Character/Company - Object to get URL for
    
    Returns:
    str: Full IMDb URL or None if unable to generate
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get movie and its IMDb ID
movie = ia.get_movie('0133093')
imdb_id = ia.get_imdbID(movie)
print(f"IMDb ID: {imdb_id}")

# Get IMDb URL
url = ia.get_imdbURL(movie)
print(f"IMDb URL: {url}")

# Convert title to IMDb ID
movie_id = ia.title2imdbID('The Matrix', kind='movie')
print(f"Movie ID from title: {movie_id}")

# Convert person name to IMDb ID
person_id = ia.name2imdbID('Keanu Reeves')
print(f"Person ID from name: {person_id}")

Keyword Operations

Keyword Search

Search for existing keywords in the IMDb database.

def search_keyword(keyword, results=None):
    """
    Search for existing keywords similar to the given one.
    
    Parameters:
    - keyword: str - Keyword to search for
    - results: int, optional - Maximum number of results (default: keywordsResults)
    
    Returns:
    list: List of keyword strings
    """

Movies by Keyword

Retrieve movies associated with specific keywords.

def get_keyword(keyword, results=None, page=None):
    """
    Get movies associated with a keyword.
    
    Parameters:
    - keyword: str - Keyword to search for
    - results: int, optional - Maximum number of results
    - page: int, optional - Page number for pagination
    
    Returns:
    list: List of Movie objects associated with the keyword
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Search for keywords
keywords = ia.search_keyword('space')
print(f"Found keywords: {keywords[:10]}")

# Get movies by keyword
space_movies = ia.get_keyword('space', results=20)
print(f"Found {len(space_movies)} movies with 'space' keyword")
for movie in space_movies[:5]:
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")

Data Update Operations

Object Updates

Update objects with additional information or refresh existing data.

def update(mop, info=None, override=0):
    """
    Update Movie/Person/Character/Company object with additional information.
    
    Parameters:
    - mop: Movie/Person/Character/Company - Object to update
    - info: list/tuple/str - Information sets to retrieve ('all' for everything)
    - override: int - Whether to override existing info (0=no, 1=yes)
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get movie with basic info
movie = ia.search_movie('Inception')[0]
print(f"Initial info: {movie.current_info}")

# Update with additional information
ia.update(movie, info=['plot', 'full_credits', 'awards'])
print(f"After update: {movie.current_info}")

# Update with all available information
ia.update(movie, info='all')
print(f"All info loaded: {movie.current_info}")

# Force refresh existing information
ia.update(movie, info=['main'], override=1)

Showtimes and Theater Information

Cinema Showtimes

Retrieve current cinema showtimes information.

def get_showtimes():
    """
    Get cinema showtimes information.
    
    Returns:
    list: List of dictionaries with cinema and movie showtime information.
    Format: [{'cinema': 'Cinema Name', 'address and contacts': '...',
             'movies': [{'movie': MovieObject, 'showtimes': 'times'}]}]
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get current showtimes
showtimes = ia.get_showtimes()
print(f"Found {len(showtimes)} cinemas with showtimes")

for cinema in showtimes[:3]:
    print(f"Cinema: {cinema['cinema']}")
    print(f"Address: {cinema.get('address and contacts', 'N/A')}")
    movies_count = len(cinema.get('movies', []))
    print(f"Movies showing: {movies_count}")

Special Methods and Utilities

Information Set Discovery

Get available information sets for different object types.

def get_movie_infoset():
    """Get list of available movie information sets."""

def get_person_infoset():
    """Get list of available person information sets."""

def get_character_infoset():
    """Get list of available character information sets."""

def get_company_infoset():
    """Get list of available company information sets."""

def get_special_methods():
    """Get special methods defined by the access system."""

Usage Example:

from imdb import IMDb

ia = IMDb()

# Discover available information sets
movie_info = ia.get_movie_infoset()
person_info = ia.get_person_infoset()

print(f"Movie info sets: {movie_info}")
print(f"Person info sets: {person_info}")

# Get special methods available
special_methods = ia.get_special_methods()
print(f"Special methods: {list(special_methods.keys())}")

URL Configuration

Configure base URLs for IMDb access.

def set_imdb_urls(imdbURL_base):
    """
    Set the URLs used for accessing IMDb site.
    
    Parameters:
    - imdbURL_base: str - Base IMDb URL (e.g., 'https://www.imdb.com/')
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Set custom IMDb base URL (rarely needed)
ia.set_imdb_urls('https://www.imdb.com/')

# Access configured URLs
print(f"Movie URL pattern: {ia.urls['movie_main']}")
print(f"Person URL pattern: {ia.urls['person_main']}")

Advanced Search Features

Cross-Reference Search

Search across different IMDb entities using internal search functionality.

from imdb import IMDb

ia = IMDb()

# Advanced movie search with multiple criteria
movies = ia.search_movie_advanced(
    title='Matrix',
    adult=False,
    results=10,
    sort='moviemeter',
    sort_dir='asc'
)

print(f"Advanced search found {len(movies)} movies")
for movie in movies:
    print(f"- {movie['title']} ({movie.get('year', 'N/A')})")

Batch Operations

Perform operations on multiple objects efficiently:

from imdb import IMDb

ia = IMDb()

# Get multiple movies and update them
movie_titles = ['The Matrix', 'Inception', 'Interstellar']
movies = []

for title in movie_titles:
    search_results = ia.search_movie(title)
    if search_results:
        movie = search_results[0]
        ia.update(movie, info=['main', 'plot'])
        movies.append(movie)

# Process all movies
for movie in movies:
    print(f"{movie['title']}: {movie.get('rating', 'N/A')}/10")
    plot = movie.get('plot', ['No plot available'])[0]
    print(f"Plot: {plot[:100]}...\n")

Error Handling and Debugging

Advanced error handling and debugging capabilities:

from imdb import IMDb, IMDbError, IMDbDataAccessError

# Create instance with detailed error reporting
ia = IMDb(reraiseExceptions=True, loggingLevel=10)  # DEBUG level

try:
    # Operations that might fail
    movie = ia.get_movie('invalid_id')
except IMDbDataAccessError as e:
    print(f"Data access error: {e}")
except IMDbError as e:
    print(f"General IMDb error: {e}")

# Check object state after operations
movie = ia.search_movie('Test')[0]
print(f"Movie current info: {movie.current_info}")
print(f"Available keys: {list(movie.keys())}")

Install with Tessl CLI