### Install Letterboxdpy with Example Dependencies

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/README.md

Use this command for a standard installation including dependencies required for running the examples. For local development, use the editable install option.

```bash
pip install "'.[examples]'"
```

```bash
pip install -e "'.[examples]'"
```

--------------------------------

### Install LetterboxdPY with Example Dependencies

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/requirements.txt

Use this command to install LetterboxdPY along with its optional example dependencies. Dependencies are managed in pyproject.toml.

```bash
-e ..[examples]
```

--------------------------------

### Install LetterboxdPy

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Install the core library using pip. For additional example dependencies, use the `[examples]` extra.

```bash
# Core installation
pip install letterboxdpy

# With example dependencies
pip install "letterboxdpy[examples]"
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Set up pre-commit hooks for automated checks before each commit. Install them once with `pre-commit install` and run them manually against all files using `pre-commit run --all-files`.

```bash
# Install hooks (one-time setup)
pre-commit install

# Run manually against all files
pre-commit run --all-files
```

--------------------------------

### Install Letterboxdpy

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Install the library from PyPI or GitHub. Use the '[examples]' extra for additional dependencies.

```bash
pip install letterboxdpy
```

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

```bash
pip install "letterboxdpy[examples]"
```

--------------------------------

### Install Letterboxdpy from GitHub

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Install the latest version directly from the GitHub repository.

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

--------------------------------

### Install Letterboxdpy from PyPI

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Install the stable version of the library using pip.

```bash
pip install letterboxdpy
```

--------------------------------

### Install Letterboxdpy Locally for Development

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Install the library in editable mode for local development. This allows for immediate reflection of code changes.

```bash
pip install -e .
```

```bash
pip install -e ".[examples]"
```

--------------------------------

### Metadata Standard for New Examples

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/README.md

This metadata standard should be included at the top of new example scripts that generate a report. It defines essential information about the tool.

```python
__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"
```

--------------------------------

### User Lists JSON Response Example

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_lists.md

This is an example of the JSON structure returned by the user_lists function, detailing the lists associated with a user.

```json
{
  "lists": {
    "30052453": {
      "title": "DEF CON Movie List",
      "slug": "def-con-movie-list",
      "description": "The DEF CON Hacking Conference's suggested movie list. defcon.org/html/links/movie-list.html",
      "url": "https://letterboxd.com/nmcassa/list/def-con-movie-list/",
      "count": 11,
      "likes": 0,
      "comments": 0
    }
  },
  "count": 1,
  "last_page": 1
}
```

--------------------------------

### Get User Watchlist with Filters

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_watchlist.md

Demonstrates how to fetch a user's watchlist and apply filters for genres. Requires importing the user module and creating a user instance.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
watchlist_result = user.user_watchlist(user_instance, {'genre':['action','-drama']})
print(watchlist_result)
```

--------------------------------

### User Wrapped JSON Response Example

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_wrapped.md

This is an example of the JSON output returned by the user_wrapped function, detailing a user's film activity for a given year.

```json
{
    "year": 2023,
    "logged": 120,
    "total_review": 2,
    "hours_watched": 223,
    "total_runtime": 13427,
    "first_watched": {
        "332289592": {
            "name": "The Gift",
            "slug": "the-gift-2015-1",
            "id": "255927",
            "release": 2015,
            "runtime": 108,
            "actions": {
                "rewatched": false,
                "rating": 3.0,
                "liked": false,
                "reviewed": false
            },
            "date": {
                "year": 2023,
                "month": 1,
                "day": 1
            },
            "page": {
                "url": "https://letterboxd.com/nmcassa/films/diary/for/2023/page/3/",
                "no": 3
            }
        }
    },
    "last_watched": {
        "495592379": {...}
    },
    "movies": {
        "495592379": {
            "name": "Poor Things",
            "slug": "poor-things-2023",
            "id": "710352",
            "release": 2023,
            "runtime": 141,
            "actions": {
                "rewatched": false,
                "rating": 3.0,
                "liked": false,
                "reviewed": true
            },
            "date": {
                "year": 2023,
                "month": 12,
                "day": 26
            },
            "page": {
                "url": "https://letterboxd.com/nmcassa/films/diary/for/2023/page/1/",
                "no": 1
            }
        },...
    },
    "months": {
        "1": 21,
        "2": 7,
        "3": 7,
        "4": 6,
        "5": 11,
        "6": 9,
        "7": 15,
        "8": 11,
        "9": 5,
        "10": 9,
        "11": 7,
        "12": 12
    },
    "days": {
        "1": 18,
        "2": 14,
        "3": 9,
        "4": 17,
        "5": 14,
        "6": 27,
        "7": 21
    },
    "milestones": {
        "50": {
            "413604382": {
                "name": "Richard Pryor: Live in Concert",
                "slug": "richard-pryor-live-in-concert",
                "id": "37594",
                "release": 1979,
                "runtime": 78,
                "actions": {
                    "rewatched": false,
                    "rating": 3.5,
                    "liked": false,
                    "reviewed": false
                },
                "date": {
                    "year": 2023,
                    "month": 7,
                    "day": 13
                },
                "page": {
                    "url": "https://letterboxd.com/nmcassa/films/diary/for/2023/page/1/",
                    "no": 1
                }
            }
        },
        "100": {
            "347318246": {...}
        }
    }
}
```

--------------------------------

### User Films JSON Response Example

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_films.md

This is an example of the JSON response structure returned by the user_films function, showing film details, counts, and rating metrics.

```json
{
  "movies": {
    "civil-war-2024": {
      "name": "Civil War",
      "id": "834656",
      "rating": 1.5,
      "liked": false
    },
    "monkey-man": {
      "name": "Monkey Man",
      "id": "488751",
      "rating": 4.5,
      "liked": true
    },...
  },
  "count": 560,
  "liked_count": 80,
  "rating_count": 518,
  "liked_percentage": 14.29,
  "rating_percentage": 92.5,
  "rating_average": 6.47
}
```

--------------------------------

### Get User Genre Information

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_genre_info.md

Instantiate a User object and then call the user_genre_info function with the user object to get genre statistics. The response is a JSON object mapping genres to their counts.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_genre_info(user_instance))
```

--------------------------------

### Get User Liked Reviews - Python

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_liked_reviews.md

Fetches and prints the liked reviews for a given user. Requires the 'letterboxdpy' library and a User object.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_liked_reviews(user_instance))
```

--------------------------------

### Get User Reviews - Python

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_reviews.md

Instantiate a User object and then call the user_reviews function with the user instance to retrieve their reviews. The response is a JSON object containing review details.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_reviews(user_instance))
```

--------------------------------

### Get Movie Details

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/movie/funcs/movie_details.md

Use the movie_details function to fetch specific details about a movie. Ensure the movie object is instantiated first.

```python
from letterboxdpy import movie
movie_instance = movie.Movie("v-for-vendetta")
print(movie.movie_details(movie_instance))
```

--------------------------------

### Get User Genre Information

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_genre_info.md

Fetches the genre information for a specified user, including watch counts for each genre.

```APIDOC
## user_genre_info(user object)

### Description
Retrieves the genre information for a given user, including the count of movies watched in each genre.

### Method
```python
user.user_genre_info(user_instance)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_genre_info(user_instance))
```

### Response
#### Success Response (200)
- **action** (integer) - Number of action movies watched.
- **adventure** (integer) - Number of adventure movies watched.
- **animation** (integer) - Number of animation movies watched.
- **comedy** (integer) - Number of comedy movies watched.
- **crime** (integer) - Number of crime movies watched.
- **documentary** (integer) - Number of documentary movies watched.
- **drama** (integer) - Number of drama movies watched.
- **family** (integer) - Number of family movies watched.
- **fantasy** (integer) - Number of fantasy movies watched.
- **history** (integer) - Number of history movies watched.
- **horror** (integer) - Number of horror movies watched.
- **music** (integer) - Number of music movies watched.
- **mystery** (integer) - Number of mystery movies watched.
- **romance** (integer) - Number of romance movies watched.
- **science-fiction** (integer) - Number of science-fiction movies watched.
- **thriller** (integer) - Number of thriller movies watched.
- **tv-movie** (integer) - Number of TV movies watched.
- **war** (integer) - Number of war movies watched.
- **western** (integer) - Number of western movies watched.

### Response Example
```json
{
    "action":55,
    "adventure":101,
    "animation":95,
    "comedy":188,
    "crime":22,
    "documentary":16,
    "drama":94,
    "family":109,
    "fantasy":54,
    "history":5,
    "horror":27,
    "music":9,
    "mystery":30,
    "romance":29,
    "science-fiction":48,
    "thriller":43,
    "tv-movie":13,
    "war":4,
    "western":5
}
```
```

--------------------------------

### Get User Lists - Python

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_lists.md

Use the user_lists function to fetch all lists created by a specific user. Ensure the user object is properly initialized before calling this function.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_lists(user_instance))
```

--------------------------------

### Get User Following List

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_following.md

Retrieves a dictionary of users that the specified user is following. Each key is the username, and the value contains display name information.

```APIDOC
## user_following(user object)

### Description
Retrieves a dictionary of users that the specified user is following. The keys are usernames and values contain display name information.

### Method
```python
user.user_following(user_instance)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_following(user_instance))
```

### Response
#### Success Response (200)
- **ppark** (object) - Information about a followed user.
- **ryanshubert** (object) - Information about a followed user.
- **crescendohouse** (object) - Information about a followed user.

#### Response Example
```json
{
    "ppark": {
        "display_name": "ppark"
    },
    "ryanshubert": {
        "display_name": "ryanshubert"
    },
    "crescendohouse": {
        "display_name": "Crescendo House"
    },...
}
```
```

--------------------------------

### Get User Followers

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_followers.md

Instantiate a User object and then call the `user_followers` function with the user instance to retrieve their followers. The response is a JSON object containing follower details.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_followers(user_instance))
```

--------------------------------

### Get User Reviews

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_reviews.md

Retrieves a list of reviews submitted by a specific user. This function requires a user object as input.

```APIDOC
## user_reviews(user object)

### Description
Retrieves a list of reviews submitted by a specific user. This function requires a user object as input.

### Method Signature
`user.user_reviews(user_object)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxd import user
user_instance = user.User("nmcassa")
print(user.user_reviews(user_instance))
```

### Response
#### Success Response (200)
Returns a JSON object containing the user's reviews, including movie details, rating, review content, and date. The response also includes the total count of reviews and the last page number.

```json
{
    "reviews": {
        "[review_id]": {
            "movie": {
                "name": "string",
                "slug": "string",
                "id": "string",
                "release": "integer",
                "link": "string"
            },
            "type": "string",
            "no": "integer",
            "link": "string",
            "rating": "float",
            "review": {
                "content": "string",
                "spoiler": "boolean"
            },
            "date": {
                "year": "integer",
                "month": "integer",
                "day": "integer"
            },
            "page": "integer"
        }
    },
    "count": "integer",
    "last_page": "integer"
}
```

### Error Handling
Specific error handling details are not provided in the source documentation.
```

--------------------------------

### User Object JSON Response

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Example JSON response structure for a User object, detailing user profile information, stats, and recent activity.

```json
{
  "username": "nmcassa",
  "url": "https://letterboxd.com/nmcassa",
  "id": 1500306,
  "is_hq": false,
  "display_name": "nmcassa",
  "bio": null,
  "location": null,
  "website": null,
  "watchlist_length": 76,
  "stats": {
    "films": 702,
    "this_year": 7,
    "lists": 2,
    "following": 8,
    "followers": 8
  },
  "favorites": {
    "51794": {
      "slug": "the-king-of-comedy",
      "name": "The King of Comedy",
      "url": "https://letterboxd.com/film/the-king-of-comedy/",
      "year": 1982,
      "log_url": "https://letterboxd.com/nmcassa/film/the-king-of-comedy/activity/"
    },
    "...": "..."
  },
  "avatar": {
    "exists": true,
    "upscaled": true,
    "url": "https://a.ltrbxd.com/resized/avatar/upload/1/5/0/0/3/0/6/shard/avtr-0-1000-0-1000-crop.jpg"
  },
  "recent": {
    "watchlist": {
      "703077": {
        "id": "703077",
        "slug": "magazine-dreams",
        "name": "Magazine Dreams",
        "year": 2023
      },
      "...": "..."
    },
    "diary": {
      "months": {
        "1": {
          "31": [
            {
              "name": "If I Had Legs I'd Kick You",
              "slug": "if-i-had-legs-id-kick-you"
            }
          ],
          "...": "..."
        }
      }
    }
  }
}
```

--------------------------------

### User Watchlist Response Structure

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_watchlist.md

Example of the JSON response structure returned by the user_watchlist function, including availability, counts, filters, and film data.

```json
{
  "available": true,
  "count": 57,
  "data_count": 6,
  "last_page": 1,
  "filters": {
    "genre": [
      "action",
      "-drama"
    ]
  },
  "data": {
    "51397": {
      "name": "From Dusk Till Dawn",
      "slug": "from-dusk-till-dawn",
      "no": 6,
      "page": 1,
      "url": "https://letterboxd.com/films/from-dusk-till-dawn/"
    },...
    "62780": {
      "name": "Mad Max: Fury Road",
      "slug": "mad-max-fury-road",
      "no": 1,
      "page": 1,
      "url": "https://letterboxd.com/films/mad-max-fury-road/"
    }
  }
}
```

--------------------------------

### Get User Activity

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_activity.md

Instantiate the User class and call the get_activity() method to retrieve a user's recent activity. The response is a JSON object containing metadata and a list of activities.

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

```json
{
  "metadata": {
    "export_timestamp": "2025-08-28T17:31:22.001861",
    "source_url": "https://letterboxd.com/ajax/activity-pagination/nmcassa",
    "total_activities": 3
  },
  "activities": {
    "9659817024": {
      "activity_type": "review",
      "timestamp": "2025-08-24T14:40:23.000000Z",
      "content": {
        "action": "watched",
        "description": "nmcassa watched and rated The Matrix ★★★★★",
        "movie": {
          "title": "The Matrix",
          "year": 1999,
          "slug": "the-matrix",
          "url": "https://letterboxd.com/film/the-matrix/"
        },
        "rating": 2.5
      }
    },
    "9624102431": {
      "activity_type": "basic",
      "timestamp": "2025-08-19T16:49:13.000000Z",
      "content": {
        "action": "liked",
        "description": "nmcassa liked Ben Wold's review of Superman",
        "movie": {
          "title": "Superman",
          "slug": "superman",
          "url": "https://letterboxd.com/film/superman/"
        }
      }
    },
    "9624100380": {
      "activity_type": "basic",
      "timestamp": "2025-08-19T16:48:50.000000Z",
      "content": {
        "action": "added",
        "description": "nmcassa added The Substance to their watchlist",
        "movie": {
          "title": "The Substance",
          "slug": "the-substance",
          "url": "https://letterboxd.com/film/the-substance/"
        }
      }
    }
  }
}
```

--------------------------------

### Get User Liked Reviews

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_liked_reviews.md

Retrieves a list of reviews that a user has liked. This function takes a user object as input and returns a dictionary containing the liked reviews.

```APIDOC
## user_liked_reviews(user object)

### Description
Retrieves a list of reviews that a user has liked. This function takes a user object as input and returns a dictionary containing the liked reviews.

### Method
Python Function Call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_liked_reviews(user_instance))
```

### Response
#### Success Response (200)
- **reviews** (object) - A dictionary where keys are review IDs and values are objects containing details of each liked review.
  - **type** (string) - The type of interaction (e.g., "Rewatched", "Added").
  - **no** (integer) - A numerical identifier, likely for internal use.
  - **url** (string) - The URL to the review on Letterboxd.
  - **rating** (float) - The rating given to the movie in the review.
  - **review** (object) - Details about the review content.
    - **content** (string) - The text of the review.
    - **spoiler** (boolean) - Indicates if the review contains spoilers.
    - **date** (object) - The date the review was posted.
      - **year** (integer) - The year the review was posted.
      - **month** (integer) - The month the review was posted.
      - **day** (integer) - The day the review was posted.
  - **user** (object) - Information about the user who posted the review.
    - **username** (string) - The username of the reviewer.
    - **display_name** (string) - The display name of the reviewer.
    - **url** (string) - The URL to the reviewer's profile.
  - **movie** (object) - Information about the movie being reviewed.
    - **name** (string) - The name of the movie.
    - **slug** (string) - The slugified name of the movie.
    - **id** (string) - The unique ID of the movie.
    - **release** (integer) - The release year of the movie.
    - **url** (string) - The URL to the movie's page.
  - **page** (integer) - The page number of the review results.

### Response Example
```json
{
    "reviews": {
        "666730921": {
            "type": "Rewatched",
            "no": 0,
            "url": "https://letterboxd.com/ppark/film/mean-girls/",
            "rating": 4.0,
            "review": {
                "content": "Refreshing",
                "spoiler": false,
                "date": {
                    "year": 2024,
                    "month": 9,
                    "day": 7
                }
            },
            "user": {
                "username": "ppark",
                "display_name": "ppark",
                "url": "https://letterboxd.com/ppark/"
            },
            "movie": {
                "name": "Mean Girls",
                "slug": "mean-girls",
                "id": "46049",
                "release": 2004,
                "url": "https://letterboxd.com/film/mean-girls/"
            },
            "page": 1
        },
        "80658991": {
            "type": "Added",
            "no": 0,
            "url": "https://letterboxd.com/kurstboy/film/the-departed/",
            "rating": 4.5,
            "review": {
                "content": "Great way to end my Scorsese binge!That final shot is perfect and the whole third act feels tight as hell. The entire film is rich with interesting approaches to the subject matter which is fitting for a plot that grabs your attention within the first 5 minutes. Scorsese is just spitballing here and throwing every idea at the wall, his love for filmmaking shines brighter here than in something like Hugo. Don't know what to add to the table…",
                "spoiler": false,
                "date": {
                    "year": 2019,
                    "month": 11,
                    "day": 24
                }
            },
            "user": {
                "username": "Kurstboy",
                "display_name": "Karsten",
                "url": "https://letterboxd.com/kurstboy/"
            },
            "movie": {
                "name": "The Departed",
                "slug": "the-departed",
                "id": "51042",
                "release": 2006,
                "url": "https://letterboxd.com/film/the-departed/"
            },
            "page": 2
        }
    }
}
```
```

--------------------------------

### Get Similar Movies

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Fetches a list of movies that Letterboxd users consider similar to a given film, based on community tagging. Displays movie name and average rating.

```python
from letterboxdpy.movie import Movie

movie = Movie("v-for-vendetta")
similar = movie.get_similar_movies()

for film_id, film in similar.items():
    print(film["name"], film["rating"])
```

--------------------------------

### Get User Lists

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_lists.md

Retrieves all lists created by a specific user. This function takes a user object as input and returns a dictionary containing the user's lists, their count, and pagination information.

```APIDOC
## user_lists(user object)

### Description
Retrieves all lists created by a specific user. This function takes a user object as input and returns a dictionary containing the user's lists, their count, and pagination information.

### Method
```python
user.user_lists(user_instance)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_lists(user_instance))
```

### Response
#### Success Response (200)
- **lists** (object) - A dictionary where keys are list IDs and values are list details.
  - **title** (string) - The title of the list.
  - **slug** (string) - The URL-friendly slug for the list.
  - **description** (string) - A description of the list.
  - **url** (string) - The URL to the list on Letterboxd.
  - **count** (integer) - The number of items in the list.
  - **likes** (integer) - The number of likes the list has received.
  - **comments** (integer) - The number of comments on the list.
- **count** (integer) - The total number of lists the user has.
- **last_page** (integer) - The index of the last page of results.

#### Response Example
```json
{
  "lists": {
    "30052453": {
      "title": "DEF CON Movie List",
      "slug": "def-con-movie-list",
      "description": "The DEF CON Hacking Conference's suggested movie list. defcon.org/html/links/movie-list.html",
      "url": "https://letterboxd.com/nmcassa/list/def-con-movie-list/",
      "count": 11,
      "likes": 0,
      "comments": 0
    }
  },
  "count": 1,
  "last_page": 1
}
```
```

--------------------------------

### Initialize User Object

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Create an instance of the User object by providing a username. This object can then be printed to display user information.

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

--------------------------------

### Initialize Movie Object by Slug

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Create an instance of the Movie object by providing its slug. This is a common way to look up movie data.

```python
from letterboxdpy.movie import Movie

# lookup by slug
movie_instance = Movie("v-for-vendetta")
```

--------------------------------

### Initialize and Use User Object

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Instantiate a User object to fetch profile data. Profile fields are available immediately, while heavier data is fetched on demand. The object can be printed as JSON or converted to a Python dictionary.

```python
from letterboxdpy.user import User

user = User("nmcassa")

# Profile data is available immediately after construction
print(user.username)         # "nmcassa"
print(user.display_name)     # "nmcassa"
print(user.id)               # 1500306
print(user.is_hq)            # False (Letterboxd HQ account)
print(user.watchlist_length) # 76
print(user.stats)
# {"films": 702, "this_year": 7, "lists": 2, "following": 8, "followers": 8}

print(user.favorites)
# {"51794": {"slug": "the-king-of-comedy", "name": "The King of Comedy", "year": 1982, ...}, ...}

# Full JSON serialization
print(user)  # Pretty-printed JSON of entire profile
data = user.jsonify()  # dict
```

--------------------------------

### Get Movie Watchers

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/movie/funcs/movie_watchers.md

Fetches the number of members, fans, likes, reviews, and lists associated with a movie.

```APIDOC
## movie_watchers(movie object)

### Description
Retrieves watcher statistics for a given movie object.

### Parameters
#### Path Parameters
- **movie object** (object) - Required - An instance of the movie object for which to fetch data.

### Request Example
```python
from letterboxdpy import movie
movie_instance = movie.Movie("v-for-vendetta")
print(movie.movie_watchers(movie_instance))
```

### Response
#### Success Response (200)
- **members** (integer) - The total number of members.
- **fans** (integer) - The number of fans.
- **likes** (integer) - The total number of likes.
- **reviews** (integer) - The total number of reviews.
- **lists** (integer) - The total number of lists the movie appears in.

#### Response Example
```json
{
    "members": 1090230,
    "fans": 9923,
    "likes": 278496,
    "reviews": 42180,
    "lists": 98866
}
```
```

--------------------------------

### User Object Initialization and Basic Profile Data

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Instantiate a User object to fetch a complete profile snapshot including stats, favorites, avatar, and recent activity. Profile fields are populated on construction, while heavier data is fetched on demand.

```APIDOC
## User Object

Instantiate a `User` to fetch a complete profile snapshot including stats, favorites, avatar, and recent activity. All profile fields are populated on construction; heavier data (films, diary, reviews, etc.) is fetched on demand via methods.

```python
from letterboxdpy.user import User

user = User("nmcassa")

# Profile data is available immediately after construction
print(user.username)         # "nmcassa"
print(user.display_name)     # "nmcassa"
print(user.id)               # 1500306
print(user.is_hq)            # False (Letterboxd HQ account)
print(user.watchlist_length) # 76
print(user.stats)
# {"films": 702, "this_year": 7, "lists": 2, "following": 8, "followers": 8}

print(user.favorites)
# {"51794": {"slug": "the-king-of-comedy", "name": "The King of Comedy", "year": 1982, ...}, ...}

# Full JSON serialization
print(user)  # Pretty-printed JSON of entire profile
data = user.jsonify()  # dict
```
```

--------------------------------

### Run Notification Manager CLI

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/README.md

Execute the full-featured CLI to manage Letterboxd notification settings.

```python
python examples/notification_manager.py
```

--------------------------------

### Initialize Search Object

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Sets up the Search object for querying Letterboxd across various categories like films, reviews, members, and more. Results are automatically paginated.

```python
from letterboxdpy.search import Search, SearchFilter, get_film_slug_from_title
```

--------------------------------

### Get Movie Watcher Statistics

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Retrieves community watch statistics for a movie, including total watchers, fans, and list appearances.

```python
from letterboxdpy.movie import Movie

movie = Movie("v-for-vendetta")
stats = movie.get_watchers_stats()

print(stats)
```

--------------------------------

### Initialize User Session

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Import and initialize the UserSession class for authentication and session management, enabling account-specific features.

```python
from letterboxdpy.auth import UserSession
```

--------------------------------

### Get User Films Python

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_films.md

Use the user_films function to retrieve all films logged by a user. This requires an instantiated user object.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_films(user_instance))
```

--------------------------------

### Get Movie Watcher Stats

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/movie/funcs/movie_watchers.md

Use this function to retrieve statistics about a movie's audience. It requires an initialized Movie object.

```python
from letterboxdpy import movie
movie_instance = movie.Movie("v-for-vendetta")
print(movie.movie_watchers(movie_instance))
```

--------------------------------

### Fetch User Watchlist

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Instantiate the Watchlist class with a username to fetch their watchlist. Movies are loaded lazily when the `.movies` attribute is accessed.

```python
from letterboxdpy.watchlist import Watchlist
watchlist = Watchlist("nmcassa")
watchlist.movies # fetch movies (lazy loading)
print(watchlist)
```

--------------------------------

### User Liked Reviews Response Structure - JSON

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_liked_reviews.md

Example JSON structure for the response of the user_liked_reviews function, showing details of each liked review.

```json
{
    "reviews": {
        "666730921": {
            "type": "Rewatched",
            "no": 0,
            "url": "https://letterboxd.com/ppark/film/mean-girls/",
            "rating": 4.0,
            "review": {
                "content": "Refreshing",
                "spoiler": false,
                "date": {
                    "year": 2024,
                    "month": 9,
                    "day": 7
                }
            },
            "user": {
                "username": "ppark",
                "display_name": "ppark",
                "url": "https://letterboxd.com/ppark/"
            },
            "movie": {
                "name": "Mean Girls",
                "slug": "mean-girls",
                "id": "46049",
                "release": 2004,
                "url": "https://letterboxd.com/film/mean-girls/"
            },
            "page": 1
        },
        "80658991": {
            "type": "Added",
            "no": 0,
            "url": "https://letterboxd.com/kurstboy/film/the-departed/",
            "rating": 4.5,
            "review": {
                "content": "Great way to end my Scorsese binge!That final shot is perfect and the whole third act feels tight as hell. The entire film is rich with interesting approaches to the subject matter which is fitting for a plot that grabs your attention within the first 5 minutes. Scorsese is just spitballing here and throwing every idea at the wall, his love for filmmaking shines brighter here than in something like Hugo. Don't know what to add to the table…",
                "spoiler": false,
                "date": {
                    "year": 2019,
                    "month": 11,
                    "day": 24
                }
            },
            "user": {
                "username": "Kurstboy",
                "display_name": "Karsten",
                "url": "https://letterboxd.com/kurstboy/"
            },
            "movie": {
                "name": "The Departed",
                "slug": "the-departed",
                "id": "51042",
                "release": 2006,
                "url": "https://letterboxd.com/film/the-departed/"
            },
            "page": 2
        }
    }
}
```

--------------------------------

### Run Profile Editor CLI

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/README.md

Execute the interactive CLI tool to edit profile settings and manage favorites.

```python
python examples/profile_editor.py
```

--------------------------------

### User Tags Response Structure

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_tags.md

Example JSON structure of the response from the user_tags function, showing counts and tag details for different categories.

```json
{
  "films": {"tags": {"lol": {...}}, "count": 1},
  "diary": {"tags": {"lol": {...}}, "count": 1},
  "reviews": {"tags": {"lol": {...}}, "count": 1},
  "lists": {
    "tags": {
      "hacking": {
        "name": "hacking",
        "title": "hacking",
        "link": "/nmcassa/tag/hacking/lists/",
        "count": 1,
        "no": 1
      }
    },
    "count": 1
  },
  "count": 4
}
```

--------------------------------

### Manage User Settings

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Use UserSettings to read and update user profile and notification settings. Requires an authenticated session.

```python
from letterboxdpy.account.settings import UserSettings

settings = UserSettings(session)

# Get current profile data
profile = settings.get_profile()
print(f"Current Bio: {profile['bio']}")

# Update specific profile fields
settings.update_profile({
    "location": "New York, USA",
    "website": "https://example.com",
    "bio": "Just another movie lover."
})

# Manage notifications
notifs = settings.get_notifications()
settings.update_notifications({"emailEditorial": True, "pushFollowers": False})
```

--------------------------------

### Get User Tags

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_tags.md

Retrieves all tags associated with a user's activity across different sections. Requires an initialized User object.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
result = user.user_tags(user_instance)
print(result)
```

--------------------------------

### User Session Management

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Handles user authentication and session persistence. Use `ensure()` to load a saved session or prompt for login, `login()` for programmatic login, and specify `cookie_path` for custom session file locations. Credentials can be passed directly to `ensure()` to avoid interactive prompts.

```python
from letterboxdpy.auth import UserSession
from pathlib import Path

# Option 1: Auto-load saved session or prompt for login interactively
session = UserSession.ensure()
print(f"Authenticated as: {session.username}")

# Option 2: Programmatic login (saves session to .cookie/session.json)
session = UserSession.login("myusername", "mypassword")

# Option 3: Custom cookie path
session = UserSession.ensure(cookie_path=Path(".my_cookies/lb.json"))

# Option 4: Pass credentials directly (no prompt)
session = UserSession.ensure(username="myusername", password="mypassword")

# Check authentication status
print(session.is_logged_in)  # True
is_valid = session.validate()  # Network check
print(is_valid)  # True

# Save/reload session manually
session.save(Path(".cookie/session.json"))
loaded = UserSession.load(Path(".cookie/session.json"))

# CSRF token (used internally for POST requests)
print(session.csrf)  # "abc123..."
```

--------------------------------

### Compare User Watchlists

Source: https://github.com/nmcassa/letterboxdpy/blob/main/examples/README.md

Run the script to compare watchlists from followed users. This generates an interactive HTML report. Replace <username> with the target user's username.

```python
python examples/compare_watchlists.py --user <username>
```

--------------------------------

### Fetch User Followers/Following

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Retrieves a user's followers or following list. Supports pagination and limiting the number of results returned.

```python
from letterboxdpy.user import User

user = User("nmcassa")

followers = user.get_followers()
following = user.get_following()

# Limit results
first_5_followers = user.get_followers(limit=5)
# Paginate manually
page2 = user.get_followers(page=2)
```

--------------------------------

### Fetch Members List

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Instantiate the Members class to fetch a list of members. The `max` parameter limits the number of members returned.

```python
from letterboxdpy.members import Members
members_instance = Members(max=5)
print(members_instance.members)
```

--------------------------------

### User Object

Source: https://github.com/nmcassa/letterboxdpy/blob/main/README.md

Instantiate a User object by providing a username. This object allows access to user-specific data.

```APIDOC
## User Object

### Description
Instantiate a User object by providing a username. This object allows access to user-specific data.

### Method
```python
from letterboxdpy.user import User
user_instance = User("nmcassa")
print(user_instance)
```

### Response Example
```json
{
  "username": "nmcassa",
  "url": "https://letterboxd.com/nmcassa",
  "id": 1500306,
  "is_hq": false,
  "display_name": "nmcassa",
  "bio": null,
  "location": null,
  "website": null,
  "watchlist_length": 76,
  "stats": {
    "films": 702,
    "this_year": 7,
    "lists": 2,
    "following": 8,
    "followers": 8
  },
  "favorites": {
    "51794": {
      "slug": "the-king-of-comedy",
      "name": "The King of Comedy",
      "url": "https://letterboxd.com/film/the-king-of-comedy/",
      "year": 1982,
      "log_url": "https://letterboxd.com/nmcassa/film/the-king-of-comedy/activity/"
    },
    "...": "..."
  },
  "avatar": {
    "exists": true,
    "upscaled": true,
    "url": "https://a.ltrbxd.com/resized/avatar/upload/1/5/0/0/3/0/6/shard/avtr-0-1000-0-1000-crop.jpg"
  },
  "recent": {
    "watchlist": {
      "703077": {
        "id": "703077",
        "slug": "magazine-dreams",
        "name": "Magazine Dreams",
        "year": 2023
      },
      "...": "..."
    },
    "diary": {
      "months": {
        "1": {
          "31": [
            {
              "name": "If I Had Legs I'd Kick You",
              "slug": "if-i-had-legs-id-kick-you"
            }
          ],
          "...": "..."
        }
      }
    }
  }
}
```
```

--------------------------------

### Get User Following List

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_following.md

Use this function to retrieve a dictionary of users that a given user is following. The response includes the display name for each followed user.

```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_following(user_instance))
```

```json
{
    "ppark": {
        "display_name": "ppark"
    },
    "ryanshubert": {
        "display_name": "ryanshubert"
    },
    "crescendohouse": {
        "display_name": "Crescendo House"
    },...
}
```

--------------------------------

### Get User Followers

Source: https://github.com/nmcassa/letterboxdpy/blob/main/docs/user/funcs/user_followers.md

Retrieves a list of followers for a specified user. The response includes a JSON object where keys are usernames and values contain display names.

```APIDOC
## user_followers(user object)

### Description
Retrieves a list of followers for a specified user object.

### Method
```python
user.user_followers(user_instance)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from letterboxdpy import user
user_instance = user.User("nmcassa")
print(user.user_followers(user_instance))
```

### Response
#### Success Response (200)
- **ppark** (object) - Information about a follower.
- **joacogarcia2023** (object) - Information about a follower.
- **ryanshubert** (object) - Information about a follower.

#### Response Example
```json
{
   "ppark": {
        "display_name": "ppark"
    },
    "joacogarcia2023": {
        "display_name": "joacogarcia2023"
    },
    "ryanshubert": {
        "display_name": "ryanshubert"
    },...
}
```
```

--------------------------------

### Get Movie Lists

Source: https://context7.com/nmcassa/letterboxdpy/llms.txt

Retrieves user-curated lists on Letterboxd that feature a specific film. Includes list title, owner's username, and the number of films in the list.

```python
from letterboxdpy.movie import Movie

movie = Movie("v-for-vendetta")
lists = movie.get_lists()

for lst in lists["lists"]:
    print(lst["title"], lst["owner"]["username"], lst["film_count"])
```