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

Core Data Access

Name: tessl/pypi-cinemagoer
Author: tessl

Primary functions for creating IMDb access instances and retrieving basic system information. These form the foundation for all IMDb data operations across different access methods.

Capabilities

IMDb Instance Creation

Creates IMDb access system instances with configurable data sources and parameters. The factory function automatically selects appropriate parsers based on the specified access system.

def IMDb(accessSystem=None, *arguments, **keywords):
    """
    Create an instance of the appropriate IMDb access system.
    
    Parameters:
    - accessSystem: str, optional - Access method ('http', 'sql', 's3', 'auto', 'config')
    - results: int - Default number of search results (default: 20)
    - keywordsResults: int - Default number of keyword results (default: 100)
    - reraiseExceptions: bool - Whether to re-raise exceptions (default: True)
    - loggingLevel: int - Logging level
    - loggingConfig: str - Path to logging configuration file
    - imdbURL_base: str - Base IMDb URL (default: 'https://www.imdb.com/')
    
    Returns:
    IMDbBase subclass instance (IMDbHTTPAccessSystem, IMDbSqlAccessSystem, or IMDbS3AccessSystem)
    """

Usage Example:

from imdb import IMDb

# Default HTTP access
ia = IMDb()

# Explicit HTTP access with custom settings
ia = IMDb('http', results=50, reraiseExceptions=False)

# SQL database access
ia = IMDb('sql', host='localhost', database='imdb')

# S3 dataset access
ia = IMDb('s3')

# Configuration file-based access
ia = IMDb('config')

Cinemagoer Alias

Alias for the IMDb function providing identical functionality with updated branding.

Cinemagoer = IMDb

Usage Example:

from imdb import Cinemagoer

# Identical to IMDb() function
ia = Cinemagoer()

Available Access Systems

Returns the list of currently available data access systems based on installed dependencies and system configuration.

def available_access_systems():
    """
    Return the list of available data access systems.
    
    Returns:
    list: Available access system names (e.g., ['http', 'sql'])
    """

Usage Example:

from imdb import available_access_systems

# Check what access systems are available
systems = available_access_systems()
print(f"Available systems: {systems}")
# Output: ['http'] or ['http', 'sql'] depending on installation

Access System Types

HTTP Access System

Access Methods: 'http', 'https', 'web', 'html'

Web scraping access to IMDb website
Default access method
No additional dependencies beyond base requirements
Rate-limited by IMDb's website policies

SQL Database Access System

Access Methods: 'sql', 'db', 'database'

Direct SQL database access to local IMDb data
Requires separate IMDb database setup
Fastest access for bulk operations
Requires additional SQL database dependencies

S3 Dataset Access System

Access Methods: 's3', 's3dataset', 'imdbws'

Access to IMDb S3 datasets and web services
Official IMDb data source
Requires AWS credentials and network access
Most up-to-date and authoritative data

Configuration System

Automatic Configuration

The IMDb function can automatically load configuration from files when accessSystem='config' or accessSystem='auto'.

Configuration File Locations (searched in order):

./cinemagoer.cfg or ./imdbpy.cfg (current directory)
./.cinemagoer.cfg or ./.imdbpy.cfg (current directory, hidden)
~/cinemagoer.cfg or ~/imdbpy.cfg (home directory)
~/.cinemagoer.cfg or ~/.imdbpy.cfg (home directory, hidden)
/etc/cinemagoer.cfg or /etc/imdbpy.cfg (Unix systems)
/etc/conf.d/cinemagoer.cfg or /etc/conf.d/imdbpy.cfg (Unix systems)

Configuration File Format:

[imdbpy]
accessSystem = http
results = 30
keywordsResults = 150
reraiseExceptions = true
imdbURL_base = https://www.imdb.com/

Custom Configuration

class ConfigParserWithCase:
    """
    Case-sensitive configuration parser for IMDb settings.
    
    Methods:
    - get(section, option, *args, **kwds): Get configuration value
    - getDict(section): Get section as dictionary
    - items(section, *args, **kwds): Get section items as list
    """

Error Handling

All core access functions can raise IMDb-specific exceptions:

from imdb import IMDb, IMDbError, IMDbDataAccessError

try:
    ia = IMDb('invalid_system')
except IMDbError as e:
    print(f"IMDb error: {e}")

try:
    ia = IMDb('sql')  # If SQL system not available
except IMDbError as e:
    print(f"SQL access not available: {e}")

Performance Best Practices

Optimize performance for different use cases and access patterns:

Access System Selection

HTTP Access (Default):

Best for: Small to medium applications, one-off scripts, development
Performance: Moderate, dependent on network latency
Rate limiting: Subject to IMDb's rate limits
Best practices: Cache results, use batch operations when possible

# HTTP access - good for most use cases
ia = IMDb()  # Default HTTP access

SQL Access:

Best for: Large-scale applications, high-volume queries, analytics
Performance: Excellent for complex queries and bulk operations
Setup required: Local IMDb database installation
Best practices: Use for production applications with heavy usage

# SQL access - optimal for large-scale applications
ia = IMDb('sql', host='localhost', user='imdb', password='password')

S3 Access:

Best for: Cloud applications, AWS-integrated systems
Performance: Good for bulk data processing
Requirements: AWS credentials and S3 dataset access
Best practices: Use for batch processing and analytics

# S3 access - good for cloud-based bulk processing
ia = IMDb('s3')

Information Set Optimization

Selective Information Loading:

# Efficient - only load needed information
movie = ia.get_movie('0133093', info=['main', 'plot'])

# Inefficient - loads all available information
movie = ia.get_movie('0133093', info='all')

Batch Updates:

# Efficient - batch processing
movies = ia.search_movie('Matrix')
for movie in movies[:5]:  # Limit results
    ia.update(movie, info=['main'])  # Minimal info for listings

# Inefficient - individual detailed updates
for movie in movies:
    ia.update(movie, info='all')  # Excessive information

Memory Management

Large Dataset Handling:

# Process results in batches to manage memory
def process_large_chart():
    top_movies = ia.get_top250_movies()
    
    # Process in smaller chunks
    chunk_size = 50
    for i in range(0, len(top_movies), chunk_size):
        chunk = top_movies[i:i + chunk_size]
        # Process chunk
        for movie in chunk:
            # Minimal processing to conserve memory
            print(f"{movie['title']} ({movie['year']})")

Caching Strategies

Results Caching:

from functools import lru_cache

# Cache expensive operations
@lru_cache(maxsize=100)
def cached_movie_search(title):
    return ia.search_movie(title, results=5)

# Reuse cached results
movies1 = cached_movie_search('Matrix')  # Network call
movies2 = cached_movie_search('Matrix')  # Cached result

Install with Tessl CLI