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

Person Operations

Name: tessl/pypi-cinemagoer
Author: tessl

Person search, retrieval, and biographical information management including comprehensive filmography and career details.

Capabilities

Person Search

Search for people by name with configurable result limits.

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

Usage Example:

from imdb import IMDb

ia = IMDb()

# Basic person search
people = ia.search_person('Tom Hanks')
print(f"Found {len(people)} people")
for person in people[:3]:
    print(f"- {person['name']} (ID: {person.personID})")

# Limited results
people = ia.search_person('Smith', results=10)

Person Retrieval

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

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

Available Information Sets:

'main' - Basic person information (name, birth date, etc.)
'filmography' - Complete filmography with all roles
'biography' - Biography and personal information
'awards' - Awards and nominations
'other_works' - Other works beyond film/TV
'publicity' - Publicity information and media appearances

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get person with basic info
person = ia.get_person('0000158')  # Tom Hanks
print(f"Name: {person['name']}")
print(f"Birth date: {person.get('birth date', 'N/A')}")

# Get person with multiple info sets
person = ia.get_person('0000158', info=['main', 'filmography', 'biography'])
print(f"Biography: {person.get('mini biography', ['N/A'])[0][:100]}...")

# Access filmography
if 'filmography' in person:
    for role_type, movies in person['filmography'].items():
        print(f"{role_type}: {len(movies)} entries")
        if movies:
            print(f"  - {movies[0]['title']} ({movies[0].get('year', 'N/A')})")

Person Information Sets

Get available information sets for person objects.

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

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get available info sets
info_sets = ia.get_person_infoset()
print(f"Available person info sets: {info_sets}")
# Output: ['main', 'filmography', 'biography', 'awards', 'other_works', 'publicity']

Person Object Creation

Create new Person objects with specified parameters.

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

Person Data Structure

Person objects provide dictionary-like access to biographical and career information:

Basic Information

'name' - Person's name
'birth date' - Birth date
'birth name' - Birth name if different
'height' - Height information
'nick names' - Nicknames and aliases
'akas' - Also known as names

Biographical Information

'mini biography' - Biography text
'birth info' - Detailed birth information
'death date' - Death date (if applicable)
'death info' - Death information and cause
'spouse' - Spouse information
'trivia' - Personal trivia

Career Information

'filmography' - Complete filmography organized by role type:
- 'actor' - Acting roles
- 'actress' - Acting roles (female)
- 'director' - Directing credits
- 'producer' - Producer credits
- 'writer' - Writing credits
- 'composer' - Music composition
- 'cinematographer' - Cinematography work
- 'editor' - Film editing
- And many other role types

Awards and Recognition

'awards' - Awards and nominations
'news' - Recent news articles
'publicity' - Publicity information

Usage Example:

from imdb import IMDb

ia = IMDb()

# Get comprehensive person information
person = ia.get_person('0000158', info='all')  # Get all available info

# Access different types of information
print(f"Name: {person['name']}")
print(f"Born: {person.get('birth date', 'Unknown')}")

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

# Filmography by role
if 'filmography' in person:
    filmography = person['filmography']
    
    # Acting roles
    if 'actor' in filmography:
        print(f"Acting credits: {len(filmography['actor'])}")
        for movie in filmography['actor'][:5]:
            year = movie.get('year', 'N/A')
            print(f"  - {movie['title']} ({year})")
    
    # Directing roles
    if 'director' in filmography:
        print(f"Directing credits: {len(filmography['director'])}")
        for movie in filmography['director'][:3]:
            year = movie.get('year', 'N/A')
            print(f"  - {movie['title']} ({year})")

# Awards
if 'awards' in person:
    awards = person['awards']
    print(f"Awards and nominations: {len(awards)}")

Person Search and Filtering

Advanced person search techniques and result filtering:

from imdb import IMDb

ia = IMDb()

# Search with specific criteria
people = ia.search_person('Robert De Niro')

# Filter by exact name match
exact_matches = [p for p in people if p['name'].lower() == 'robert de niro']

# Search for people in specific roles
directors = ia.search_person('Scorsese')
for person in directors:
    # Get filmography to check if they're a director
    ia.update(person, info=['filmography'])
    if 'filmography' in person and 'director' in person['filmography']:
        print(f"Director: {person['name']}")
        director_films = person['filmography']['director']
        print(f"  Directed {len(director_films)} films")

Person Updates and Information Management

Managing person information and updates:

from imdb import IMDb

ia = IMDb()

# Get person with basic info first
person = ia.search_person('Meryl Streep')[0]

# Incrementally add more information
ia.update(person, info=['filmography'])
ia.update(person, info=['awards'], override=1)  # Force update

# Check what information is currently loaded
print(f"Current info: {person.current_info}")

# Get all possible information
ia.update(person, info='all')

Install with Tessl CLI