Modules reference

letterboxd package reference

letterboxd module

Python 3 wrapper for Version 0 of the Letterboxd API

class letterboxd.letterboxd.Letterboxd(api_base='https://api.letterboxd.com/api/v0', api_key='', api_secret='')

Loads the API base URL, API key, and API shared secret, and connects with all of the other classes.

If the key and secret are not passed as arguments, it looks for them as environment variables, as LBXD_API_KEY and LBXD_API_SECRET.

auth()

Returns:services.auth.Authentication object

film(film_id)

Parameters:film_id – str - the LID of a film on Letterboxd Returns:services.film.Film object

film_collection(film_collection_id, film_collection_request)

/film-collection/{id}

Get details about a film collection by ID. The response will include the film relationships for the signed-in member and the member indicated by the member LID if specified.

Parameters:

• film_collection_id – str - LID of the FilmCollection
• film_collection_request – dict - FilmCollectionRequest

Returns:

dict - FilmCollection

films()

Returns:services.film.Films object

list(list_id)

Parameters:list_id – str - the LID of a list on Letterboxd Returns:services.list.List object

member(member_id)

Parameters:member_id – str - LID for Letterboxd member Returns:services.member.Member object

search(search_request)

/search

Parameters:search_request – dict - SearchRequest Returns:dict - SearchResponse

user(username, password)

Signs in the user, and adds the oAuth token to future API calls

Parameters:

• username – str
• password – str

Returns:

user.User object

api module

class letterboxd.api.API(api_base, api_key, api_secret)

Communication methods for the Letterboxd API

api_call(path, params={}, form=None, headers={}, method='get')

The workhorse method of calls to the Letterboxd API

Parameters:

• path – str - URL endpoint path for the desired service
• params – dict - request parameters
• form – str - form information, likely from the auth.py call
• headers – dict - request parameters
• method – str - HTML methods, [get, post, put, patch, delete]

Returns:

requests.Response object

user module

User-based features of the Letterboxd API

class letterboxd.user.User(api, username, password)

Provices access token and shortcuts to user-focused methods

me

/me

Get details about the authenticated member.

Calls to this endpoint must include the access token for an authenticated member.

Returns:dict - MemberAccount

me_update(member_settings_update_request)

/me

Update the profile settings for the authenticated member.

Calls to this endpoint must include the access token for an authenticated member

Parameters:member_settings_update_request – dict - MemberSettingsUpdateRequest Returns:dict - MemberSettingsUpdateResponse

token

Ask services.auth to get a token, and return the token string

Returns:str - oAuth token

config module

Configuration

Constants for package use.

services package reference

auth module

User authentication services for the Letterboxd API

Authentication API Documentation: http://api-docs.letterbotokend.com/#auth

class letterboxd.services.auth.Authentication(api, username, password)

User authentication services for Letterboxd

This token business mostly takes care of itself. Instantiate authentication with username and password, then call token(), and if there isn’t a token already, or if it’s expired, it will go and get one.

static forgotten_password_request(api, forgotten_password_request)

/auth/forgotten-password-request

Request a link via email to reset the password for a member’s account.

Request:forgotten_password_request - ForgottenPasswordRequest Returns:int - HTTP status code

login(username, password)

User access to the Letterboxd API. Requests a token for the user.

Parameters:

• username – str
• password – str

Returns:

dict - either an AccessToken or OAuthError

refresh_token()

Uses the current single-use refresh_token to request a new access token for the user

Returns:dict - either an AccessToken or OAuthError

token

Checks if the user authentication token already exists. If not, it tries to get one. If it does exist, it checks to see if it is expired, and if so, it attempts to refresh the token.

Returns:str - user token

film module

class letterboxd.services.film.Film(api, film_id=None)

/film/* services for the Letterboxd API

availability(film_id=None)

/film/{id}/availability

Get availability data about a film by ID. If no film ID passed, uses the initialized film.

NOTE: This data is currently available to first-party only.

Parameters:film_id – str - LID of the film Returns:dict - FilmAvailabilityResponse

details(film_id=None)

/film/{id}

Get details about a film by ID. If no film ID passed, uses the initialized film.

Parameters:film_id – str - LID of the film Returns:dict - Film

me(film_id=None)

/film/{id}/me

Get details of the authenticated member’s relationship with a film by ID. If no film ID passed, uses the initialized film.

Parameters:film_id – str - LID of the film Returns:dict - FilmRelationship

me_update(film_relationship_update_request, film_id=None)

/film/{id}/me [PATCH]

Update the authenticated member’s relationship with a film by ID.

Calls to this endpoint must include the access token for an authenticated member

Parameters:

• film_id – str - LID of the film
• film_relationship_update_request – dict - FilmRelationshipUpdateRequest

Returns:

dict - FilmRelationshipUpdateResponse

members(film_id=None, member_film_relationships_request=None)

/film/{id}/members

Get details of members’ relationships with a film by ID. If no film ID passed, uses the initialized film.

Parameters:

• film_id – str - LID of the film
• member_film_relationships_request – dict - MemberFilmRelationshipsRequest

Returns:

dict - MemberFilmRelationshipsResponse

report(film_id=None, report_film_request=None)

/film/{id}/report

Report problems with a film by ID. Does NOT default to the initialized Film instance LID, so as to not submit unnecessary reports.

Parameters:

• film_id – str - the LID of the film
• report_film_request – dict - ReportFilmRequest

Returns:

requests.Response.status_code

statistics(film_id=None)

/film/{id}/statistics

Get statistical data about a film by ID.

Parameters:film_id – str - the LID of the film Returns:dict - FilmStatistics

class letterboxd.services.film.FilmCollection(api)

/film-collection service for the Letterboxd API

film_collection(film_collection_id=None, film_collection_request=None)

/film-collection/{id}

Get details about a film collection by ID. The response will include the film relationships for the signed-in member and the member indicated by the member LID if specified.

Parameters:

• film_collection_id – str - The LID of the film collection.
• film_collection_request – dict - FilmCollectionRequest

Returns:

dict - FilmCollection

class letterboxd.services.film.Films(api)

/films/* services for the Letterboxd API

films(films_request=None)

/films

A cursored window over the list of films.

Use the ‘next’ cursor to move through the list. The response will include the film relationships for the signed-in member and the member indicated by the member LID if specified.

Parameters:films_request – dict - FilmsRequest Returns:dict

genres()

/films/genres

Get a list of genres supported by the /films endpoint.

Genres are returned in alphabetical order.

Returns:dict - GenresResponse

services()

/films/film-services

Get a list of services supported by the /films endpoint.

Services are returned in alphabetical order. Some services are only available to paying members, so results will vary based on the authenticated member’s status.

Returns:dict - FilmServicesResponse

list module

class letterboxd.services.list.List(api, list_id=None)

/list/* services for the Letterboxd API

comments(list_id=None, comments_request=None)

/list/{id}/comments

A cursored window over the comments for a list. Use the ‘next’ cursor to move through the comments.

Parameters:

• list_id – str - LID of the list
• comments_request – dict - CommentsRequest

Returns:

create_comment(list_id=None, comment_creation_request=None)

/list/{id}/comments

Create a comment on a list.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:

• list_id – str - LID for the list
• comment_creation_request – dict - CommentCreationRequest

Returns:

dict - ListComment

delete(list_id=None)

/list/{id}

Delete a list by ID. Does NOT default to the initialized List instance LID, so as to not accidentally delete the instance list.

Calls to this endpoint must include the access token for an authenticated member, and the authenticated member must be the owner of the specified list.

Parameters:list_id – str - LID of the list Returns:bool - Success

details(list_id=None)

/list/{id}

Get details of a list by LID. If no list ID passed, uses the initialized list.

Parameters:list_id – str - LID of the film Returns:dict - Film

entries(list_id=None, list_entries_request=None)

/list/{id}/entries

Get entries for a list by ID.

Parameters:

• list_id – str - LID of the list
• list_entries_request – dict - ListEntriesRequest

Returns:

dict - ListEntriesResponse

me(list_id=None)

/list/{id}/me

Get details of the authenticated member’s relationship with a list by ID.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:list_id – str - LID of the list Returns:dict - ListRelationship

me_update(list_id=None, list_relationship_update_request=None)

/list/{id}/me

Update the authenticated member’s relationship with a list by ID.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:

• list_id – str - LID for the list
• list_relationship_update_request – dict - ListRelationshipUpdateRequest

Returns:

dict - ListRelationshipUpdateResponse

report(list_id=None, report_list_request=None)

/list/{id}/report

Report a list by ID. Does NOT default to the initialized List instance LID, so as to not submit erroneous reports.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:

• list_id – str - LID of the list
• report_list_request – dict - ReportListRequest

Returns:

bool - Success

statistics(list_id=None)

/list/{id}/statistics

Get statistical data about a list by ID.

Parameters:list_id – str - LID of the list Returns:dict - ListStatistics

update(list_id=None, list_update_request=None)

/list/{id} [PATCH]

Update a list by ID.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:

• list_id – str - LID of the list
• list_update_request – dict - ListUpdateRequest

Returns:

dict - ListUpdateResponse

class letterboxd.services.list.Lists(api)

/lists service for the Letterboxd API

create_list(list_creation_request=None)

[POST] /lists

Create a list.

Calls to this endpoint must include the access token for an authenticated member.

Parameters:list_creation_request – dict - ListCreationRequest Returns:dict - ListCreateResponse

lists(lists_request=None)

[GET] /lists

A cursored window over a list of lists.

Use the ‘next’ cursor to move through the list.

Parameters:lists_request – dict - ListsRequest Returns:dict - ListsResponse

member module

class letterboxd.services.member.Member(api, member_id=None)

/member/* services for the Letterboxd API

details(member_id=None)

/member/{id}

Get details about a member by ID.

# TODO: Write this function

Parameters:member_id – str - The LID of the member. Returns:dict - Member

watchlist(member_id=None, watchlist_request=None)

/member/{id}/watchlist

Get details of a member’s public watchlist by ID.

The response will include the film relationships for the signed-in member, the watchlist’s owner, and the member indicated by the member LID if specified (the member and memberRelationship parameters are optional, and can be used to perform comparisons between the watchlist owner and another member). Use the /film/{id}/me endpoint to add or remove films from a member’s watchlist.

Parameters:

• member_id – str - The LID of the member.
• watchlist_request – dict - WatchlistRequest

Returns:

dict - FilmsResponse

search module

class letterboxd.services.search.Search(api)

/search for the Letterboxd API

search(search_request=None)

/search

Parameters:search_request – dict - SearchRequest Returns:dict - SearchResponse