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

Data Container Classes

Name: tessl/pypi-cinemagoer
Author: tessl

Core classes for representing and manipulating IMDb data objects with dictionary-like access and specialized methods for movies, people, characters, and companies.

Base Container Functionality

All IMDb data classes inherit from _Container, providing consistent dictionary-like access patterns and common functionality across all data types.

Common Container Methods

All container classes (Movie, Person, Character, Company) share these methods:

def keys():
    """Return list of available data keys."""

def values():
    """Return list of data values."""

def items():
    """Return list of (key, value) tuples."""

def get(key, default=None):
    """Get value for key with optional default."""

def __getitem__(key):
    """Dictionary-style access to data."""

def __setitem__(key, value):
    """Dictionary-style assignment of data."""

def __contains__(key):
    """Check if key exists in data."""

def summary():
    """Return formatted summary of the object."""

Movie Class

Container for movie information with specialized movie-specific functionality.

class Movie:
    """
    Movie data container with dictionary-like access.
    
    Attributes:
    - movieID: str - Unique movie identifier
    - accessSystem: str - Access system used to retrieve data
    - myTitle: str - Personal title override
    - default_info: tuple - Default information sets ('main', 'plot')
    - keys_alias: dict - Mapping of alias keys to canonical keys
    - current_info: list - Currently loaded information sets
    """

Movie-Specific Methods

def set_title(title):
    """
    Set movie title.
    
    Parameters:
    - title: str - Movie title to set
    """

def getID():
    """
    Return movie ID.
    
    Returns:
    str: Movie ID (movieID attribute)
    """

def isSameTitle(other):
    """
    Compare titles with another movie.
    
    Parameters:
    - other: Movie - Another Movie object to compare
    
    Returns:
    bool: True if titles are considered the same
    """

def guessLanguage():
    """
    Guess the language of the movie title.
    
    Returns:
    str: Detected language code
    """

def smartCanonicalTitle():
    """
    Get canonical title representation.
    
    Returns:
    str: Canonical form of the movie title
    """

Movie Data Structure

Movies contain extensive information organized by categories:

Basic Information:

'title' - Movie title
'year' - Release year
'kind' - Type (movie, tv series, video game, etc.)
'rating' - IMDb rating
'votes' - Number of votes
'runtime' - Duration information

Cast and Crew:

'cast' - Main cast members
'director' - Directors
'writer' - Writers
'producer' - Producers
'composer' - Music composers
'cinematographer' - Cinematographers
'editor' - Film editors

Content Information:

'plot' - Plot summaries
'genres' - List of genres
'languages' - Languages
'countries' - Production countries
'color info' - Color/black & white information

Usage Example:

from imdb import IMDb

ia = IMDb()

# Create and populate movie object
movie = ia.get_movie('0133093', info=['main', 'plot', 'full_credits'])

# Dictionary-like access
print(f"Title: {movie['title']}")
print(f"Year: {movie['year']}")
print(f"Rating: {movie['rating']}")

# Specialized movie methods
print(f"Movie ID: {movie.getID()}")
canonical_title = movie.smartCanonicalTitle()
print(f"Canonical title: {canonical_title}")

# Check available information
print(f"Available keys: {list(movie.keys())}")
print(f"Current info sets: {movie.current_info}")

# Summary
print(movie.summary())

Person Class

Container for person information with specialized person-specific functionality.

class Person:
    """
    Person data container with dictionary-like access.
    
    Attributes:
    - personID: str - Unique person identifier
    - accessSystem: str - Access system used to retrieve data
    - myName: str - Personal name override
    - billingPos: int - Position in cast billing
    - default_info: tuple - Default information sets ('main', 'filmography', 'biography')
    - keys_alias: dict - Mapping of alias keys to canonical keys
    - current_info: list - Currently loaded information sets
    """

Person-Specific Methods

def set_name(name):
    """
    Set person name.
    
    Parameters:
    - name: str - Person name to set
    """

def getID():
    """
    Return person ID.
    
    Returns:
    str: Person ID (personID attribute)
    """

def isSameName(other):
    """
    Compare names with another person.
    
    Parameters:
    - other: Person - Another Person object to compare
    
    Returns:
    bool: True if names are considered the same
    """

Person Data Structure

Basic Information:

'name' - Person's name
'birth date' - Birth date
'birth name' - Birth name
'height' - Height information
'nick names' - Nicknames

Biographical Information:

'mini biography' - Biography text
'birth info' - Birth details
'death date' - Death date (if applicable)
'spouse' - Spouse information

Career Information:

'filmography' - Complete filmography by role type

Usage Example:

from imdb import IMDb

ia = IMDb()

# Create and populate person object
person = ia.get_person('0000158', info=['main', 'filmography', 'biography'])

# Dictionary-like access
print(f"Name: {person['name']}")
print(f"Birth date: {person.get('birth date', 'N/A')}")

# Specialized person methods
print(f"Person ID: {person.getID()}")

# Biography access
if 'mini biography' in person:
    bio = person['mini biography'][0]
    print(f"Biography: {bio[:100]}...")

# Filmography access
if 'filmography' in person:
    for role_type, movies in person['filmography'].items():
        print(f"{role_type}: {len(movies)} credits")

print(person.summary())

Character Class

Container for character information with specialized character-specific functionality.

class Character:
    """
    Character data container with dictionary-like access.
    
    Attributes:
    - characterID: str - Unique character identifier (may be None)
    - accessSystem: str - Access system used to retrieve data
    - myName: str - Personal name override
    - default_info: tuple - Default information sets ('main', 'filmography', 'biography')
    - keys_alias: dict - Mapping of alias keys to canonical keys
    - current_info: list - Currently loaded information sets
    """

Character-Specific Methods

def set_name(name):
    """
    Set character name.
    
    Parameters:
    - name: str - Character name to set
    """

def getID():
    """
    Return character ID.
    
    Returns:
    str: Character ID (characterID attribute) or None
    """

def isSameName(other):
    """
    Compare names with another character.
    
    Parameters:
    - other: Character - Another Character object to compare
    
    Returns:
    bool: True if names are considered the same
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Create and populate character object
character = ia.get_character('0000196', info=['main', 'filmography'])

# Dictionary-like access
print(f"Character: {character['name']}")

# Character-specific methods
char_id = character.getID()
print(f"Character ID: {char_id}")

print(character.summary())

Company Class

Container for company information with specialized company-specific functionality.

class Company:
    """
    Company data container with dictionary-like access.
    
    Attributes:
    - companyID: str - Unique company identifier
    - accessSystem: str - Access system used to retrieve data
    - myName: str - Personal name override
    - default_info: tuple - Default information sets ('main',)
    - keys_alias: dict - Mapping of alias keys to canonical keys
    - current_info: list - Currently loaded information sets
    """

Company-Specific Methods

def set_name(name):
    """
    Set company name.
    
    Parameters:
    - name: str - Company name to set
    """

def getID():
    """
    Return company ID.
    
    Returns:
    str: Company ID (companyID attribute)
    """

def isSameName(other):
    """
    Compare names with another company.
    
    Parameters:
    - other: Company - Another Company object to compare
    
    Returns:
    bool: True if names are considered the same
    """

Usage Example:

from imdb import IMDb

ia = IMDb()

# Create and populate company object
company = ia.get_company('0022125', info=['main'])

# Dictionary-like access
print(f"Company: {company['name']}")
print(f"Country: {company.get('country', 'N/A')}")

# Company-specific methods
company_id = company.getID()
print(f"Company ID: {company_id}")

print(company.summary())

Container Integration and Updates

All container objects work seamlessly with the update system:

from imdb import IMDb

ia = IMDb()

# Get objects with minimal information
movie = ia.search_movie('Inception')[0]
person = ia.search_person('Leonardo DiCaprio')[0]

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

# Check what information is loaded
print(f"Movie info: {movie.current_info}")
print(f"Person info: {person.current_info}")

# Access updated information
print(f"Movie plot: {movie.get('plot', ['N/A'])[0]}")
print(f"Person filmography keys: {list(person.get('filmography', {}).keys())}")

Key Aliases and Data Access

All container classes support key aliases for easier data access:

from imdb import IMDb

ia = IMDb()

# Get person with biography
person = ia.get_person('0000158', info=['biography'])

# These are equivalent due to key aliases
bio1 = person.get('mini biography')
bio2 = person.get('biography')  # Alias
bio3 = person.get('bio')        # Alias

print(f"All equivalent: {bio1 == bio2 == bio3}")

# Movie aliases
movie = ia.get_movie('0133093', info=['main'])
rating1 = movie.get('rating')
rating2 = movie.get('user rating')  # Alias

print(f"Rating aliases work: {rating1 == rating2}")

Install with Tessl CLI