letterboxdpy

To use the example scripts provided in the repository, you must install the package along with the [examples] extra dependencies. This includes libraries like rich, Jinja2, matplotlib, numpy, and pillow which are required for the various CLI tools and data visualizations.

For a standard installation:

pip install ".[examples]"

For local development (editable mode):

pip install -e ".[examples]"

When contributing a new example script that generates a report, you must include specific metadata at the top of your Python file to comply with the project's standards. Use the following variables:

• __title__: The name of your tool.
• __description__: A one-sentence description of the tool's purpose.
• __version__: The version of your script.
• __author__: Your name.
• __author_url__: A URL to your profile/website.
• __created_at__: The creation date in YYYY-MM-DD format.

__title__ = "Your Tool Name"
__description__ = "What it does in one sentence."
__version__ = "0.1.0"
__author__ = "yourname"
__author_url__ = "https://github.com/yourname"
__created_at__ = "YYYY-MM-DD"

You can install letterboxdpy using pip via several methods:

Stable version from PyPI

pip install letterboxdpy

Latest version from GitHub

pip install git+https://github.com/nmcassa/letterboxdpy.git

Local development installation

If you have cloned the repository locally, install it in editable mode to see changes immediately:

pip install -e .

# Or with example dependencies
pip install -e ".[examples]"

When calling get_results() or accessing .results, the returned data is a dictionary containing metadata and a list of result objects. Each result object contains a type field indicating what was found.

Common result types and their unique fields include:

• film: slug, name, year, url, poster, directors (list of {name, slug, url})
• member: username, name, badge, avatar, followers, following
• review: slug, name, year, url, poster, directors (Note: reviews link to the film being reviewed)
• list: id, slug, url, title, count, likes, comments, owner (object with {username, name, url})
• tag: name, url
• actor/director/studio: name, slug, url
• story: title, url, writer (object with {name, url})
• journal: title, url, time, writer (object with {name, url})

The .get_results() method returns a dictionary containing metadata about the search and a list of result items.

Dictionary Keys:

• available: Boolean indicating if any results were found.
• query: The encoded search query.
• filter: The filter type used.
• end_page: The last page number containing results.
• count: Total number of results returned in this call.
• results: A list of dictionaries, where each dictionary represents a search item (e.g., a film, review, or list) and includes an incrementing no (index) and page number.

The UserSession class stores authentication cookies in plaintext JSON format.

Important Security Rules:

1. Never commit cookie files (e.g., session.json) to public version control repositories.
2. The library attempts to restrict file permissions to chmod 600 (read/write for owner only) on supported systems when saving sessions.
3. Treat the cookie file path as a sensitive secret.

Use get_film_slug_from_title(title: str) to search for a film by its title and retrieve its corresponding Letterboxd slug.

Important Note: This function is a convenience wrapper that returns only the first search result. If you need to disambiguate between multiple films with the same name or require more precise control, use the Search class directly instead.

Parameters:

• title (str): The title of the film to search for.

Returns:

• str: The film slug (e.g., "dune-2021").
• None: If no film is found matching the title.

from letterboxdpy.search import get_film_slug_from_title

# Get slug for a specific film
slug = get_film_slug_from_title("Dune")
print(slug)  # Output: "dune-2021"

# Handle case when film is not found  
slug = get_film_slug_from_title("NonexistentMovie123")
print(slug)  # Output: None

The user_network function retrieves a user's social connections from Letterboxd. It accepts a User object and a section string, returning the results as a dictionary.

Parameters:

• user: An instance of letterboxdpy.user.User.
• section: A string specifying which network to fetch. Must be exactly 'followers' or 'following'.

# Example usage (requires a User instance)
network = user_network(user, 'followers')
# or
network = user_network(user, 'following')

The Films object allows you to fetch lists of films from specific Letterboxd URLs (e.g., popular films). Use the max parameter to limit results. The .movies attribute provides access to the film data.

from letterboxdpy.films import Films
films_instance = Films("https://letterboxd.com/films/popular/", max=3)
print(films_instance.movies)

The Search object allows you to search Letterboxd for specific content. You specify a query string and a filter (e.g., 'films'). Use .get_results(count) to retrieve a specified number of results.

from letterboxdpy.search import Search
search_instance = Search("V for Vendetta", 'films')
print(search_instance.get_results(5))

The get_activity() method on a User instance retrieves a dictionary of recent activities performed by that user. The response includes metadata about the export and a collection of activities keyed by their unique activity IDs.

Each activity contains:

• activity_type: The type of activity (e.g., review, basic).
• timestamp: The ISO 8601 timestamp of the activity.
• content: A dictionary containing details specific to the action, such as action (e.g., watched, liked, added), description, and movie information (title, year, slug, and URL).

from letterboxdpy.user import User
user_instance = User("nmcassa")
print(user_instance.get_activity())