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

Character and Company Operations

Name: tessl/pypi-cinemagoer
Author: tessl

Character and company search and retrieval functionality for accessing information about fictional characters and production companies in the IMDb database.

Character Operations

Character Search

Search for fictional characters by name with configurable result limits.

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

Usage Example:

from imdb import IMDb

ia = IMDb()

# Basic character search
characters = ia.search_character('James Bond')
print(f"Found {len(characters)} characters")
for character in characters[:3]:
    print(f"- {character['name']} (ID: {character.characterID})")

# Search for specific character
characters = ia.search_character('Sherlock Holmes')

Character Retrieval

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

def get_character(characterID, info=('main', 'filmography', 'biography'), modFunct=None):
    """
    Get character by ID with specified information sets.
    
    Parameters:
    - characterID: str - Character ID (internal or IMDb format)
    - info: tuple/list - Information sets to retrieve ('main', 'filmography', 'biography')
    - modFunct: function, optional - String modification function
    
    Returns:
    Character: Character object with requested information
    """

Available Information Sets:

'main' - Basic character information (name, description, etc.)
'filmography' - Movies/shows the character appears in
'biography' - Character background and description

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get character with basic info
character = ia.get_character('0000196')  # James Bond
print(f"Character: {character['name']}")

# Get character with filmography
character = ia.get_character('0000196', info=['main', 'filmography'])

# Access character appearances
if 'filmography' in character:
    appearances = character['filmography']
    print(f"Appears in {len(appearances)} productions")
    for movie in appearances[:5]:
        print(f"  - {movie['title']} ({movie.get('year', 'N/A')})")

Character Information Sets

Get available information sets for character objects.

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

Character Object Creation

Create new Character objects with specified parameters.

def new_character(*arguments, **keywords):
    """
    Create a new Character object.
    
    Parameters:
    - *arguments: Variable arguments for Character constructor
    - **keywords: Keyword arguments for Character constructor
    
    Returns:
    Character: New Character object instance
    """

Company Operations

Company Search

Search for production companies by name with configurable result limits.

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

Usage Example:

from imdb import IMDb

ia = IMDb()

# Basic company search
companies = ia.search_company('Warner Bros')
print(f"Found {len(companies)} companies")
for company in companies[:3]:
    print(f"- {company['name']} (ID: {company.companyID})")

# Search for specific company
companies = ia.search_company('Pixar')

Company Retrieval

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

def get_company(companyID, info=('main',), modFunct=None):
    """
    Get company by ID with specified information sets.
    
    Parameters:
    - companyID: str - Company ID (internal or IMDb format)
    - info: tuple/list - Information sets to retrieve ('main', etc.)
    - modFunct: function, optional - String modification function
    
    Returns:
    Company: Company object with requested information
    """

Available Information Sets:

'main' - Basic company information (name, type, location, etc.)

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get company with basic info
company = ia.get_company('0022125')  # Warner Bros
print(f"Company: {company['name']}")
print(f"Country: {company.get('country', 'N/A')}")

# Access company details
if 'long imdb name' in company:
    print(f"Full name: {company['long imdb name']}")

Company Information Sets

Get available information sets for company objects.

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

Company Object Creation

Create new Company objects with specified parameters.

def new_company(*arguments, **keywords):
    """
    Create a new Company object.
    
    Parameters:
    - *arguments: Variable arguments for Company constructor
    - **keywords: Keyword arguments for Company constructor
    
    Returns:
    Company: New Company object instance
    """

Character Data Structure

Character objects provide dictionary-like access to character information:

Basic Information

'name' - Character name
'long imdb name' - Full character name as displayed on IMDb
'canonical name' - Canonical form of character name

Filmography Information

'filmography' - List of movies/shows the character appears in
Each entry contains movie information and character details

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get comprehensive character information
character = ia.get_character('0000196', info='all')

print(f"Character: {character['name']}")
if 'long imdb name' in character:
    print(f"Full name: {character['long imdb name']}")

# Character appearances
if 'filmography' in character:
    print(f"Appears in {len(character['filmography'])} productions:")
    for movie in character['filmography'][:5]:
        title = movie['title']
        year = movie.get('year', 'N/A')
        print(f"  - {title} ({year})")

Company Data Structure

Company objects provide dictionary-like access to company information:

Basic Information

'name' - Company name
'long imdb name' - Full company name as displayed on IMDb
'country' - Country of origin
'company type' - Type of company (distributor, production company, etc.)

Company Categories

Companies are categorized by their role in film production:

Production companies
Distributors
Special effects companies
Miscellaneous companies
And other specialized categories

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get comprehensive company information
companies = ia.search_company('Disney')
company = companies[0]
ia.update(company, info='all')

print(f"Company: {company['name']}")
print(f"Country: {company.get('country', 'N/A')}")
print(f"Type: {company.get('company type', 'N/A')}")

if 'long imdb name' in company:
    print(f"Full name: {company['long imdb name']}")

Advanced Search and Operations

Character-Actor Relationships

Characters are often linked to the actors who portray them:

from imdb import IMDb

ia = IMDb()

# Search for a character
characters = ia.search_character('Harry Potter')
character = characters[0]
ia.update(character, info=['filmography'])

# Find actors who played this character
for movie in character.get('filmography', []):
    print(f"In {movie['title']}:")
    # Character information often includes actor details
    if 'cast' in movie:
        for cast_member in movie['cast']:
            if character['name'].lower() in str(cast_member).lower():
                print(f"  Played by: {cast_member['name']}")

Company Productions

Find movies produced or distributed by specific companies:

from imdb import IMDb

ia = IMDb()

# Search for company
companies = ia.search_company('Marvel Studios')
company = companies[0]

# Note: Company filmography requires additional parsing
# Company data structure varies by access system
print(f"Company: {company['name']}")
print(f"Company ID: {company.companyID}")

# Company information is often found in movie data
# Search for movies and check production companies
movies = ia.search_movie('Avengers')
for movie in movies[:3]:
    ia.update(movie, info=['main'])
    if 'production companies' in movie:
        for prod_company in movie['production companies']:
            if 'Marvel' in prod_company['name']:
                print(f"{movie['title']} - produced by {prod_company['name']}")

ID Conversion and URLs

Character and company ID conversion and URL generation:

from imdb import IMDb

ia = IMDb()

# Get character
character = ia.get_character('0000196')

# Get IMDb URL for character
character_url = ia.get_imdbURL(character)
print(f"Character URL: {character_url}")

# Get company
company = ia.get_company('0022125')

# Get IMDb URL for company
company_url = ia.get_imdbURL(company)
print(f"Company URL: {company_url}")

# Convert names to IMDb IDs
character_id = ia.character2imdbID('James Bond')
company_id = ia.company2imdbID('Warner Bros')

Install with Tessl CLI