Find films by title.

Start here when you know the name. Returns the id needed by get_film.

Args: title: Part of the film's title. limit: How many matches to return.

Get one film in full: the review, the rating, credits and every field.

Args: id: Film id, from search_films or list_films.

List films, filtered and ordered.

Args: year: Release year, as the archive records it. genre: Genre name in Finnish, such as Komedia or Draama. director: Director's name. actor: Actor's name. min_rating: Only films Rolle rated at least this, 1 to 10. max_rating: Only films he rated at most this, 1 to 10. unrated: True for films with no rating yet. imdb: IMDb id, to find one specific film. status: publish, draft, or any. orderby: date, title or rating. order: ASC or DESC. page: Which page of results. per_page: Results per page, at most 100.

Get archive-wide figures: totals, average rating, the rating spread and films per year.

Use this for questions about the collection rather than one film.

List draft films waiting for a review.

These are queued by the Trakt importer after Rolle watches something. Needs an application password.

List genres, directors, writers or actors used in the archive.

Args: taxonomy: One of genre, director, writer, actor. search: Narrow to names containing this. limit: How many terms to return.

Report which site this points at and whether writing is possible.

Search TMDB for a film, to get the tmdb_id that create_film enriches from.

This goes through the site, which holds the TMDB key, so no key is needed here. Needs an application password.

Args: query: Film title to search for.

Find a film by its IMDb id, including drafts.

The reliable way to check whether a film is already in the archive before adding it, since titles repeat across remakes and translations.

Args: imdb_id: IMDb id such as tt0816692, or a full IMDb URL.

Set Rolle's own rating for a film.

Args: id: Film id. rating: Whole number 1 to 10, or 0 to clear. See create_film for the scale.

Put Rolle's review text on a film.

The text is his: pass what he wrote, never compose one for him.

Args: id: Film id. content: The review, as HTML or plain paragraphs. Replaces what is there. rating: Whole number 1 to 10. See create_film. date: Date shown on the review. See create_film. publish: True moves a draft to published.

Add a film to the archive, enriched from TMDB.

With tmdb_id the site fetches plot, poster, backdrop, cast, crew, genres, trailer, IMDb and Metascore exactly as the quick review page does. Find the id with lookup_tmdb.

The archive keeps one entry per film. If this one is already there, nothing is created and the existing entry comes back instead: update that with update_film or write_review rather than adding a second.

Args: title: Film title, usually the Finnish release title if it has one. tmdb_id: TMDB id, from lookup_tmdb. Strongly preferred. rating: Rolle's own rating: whole number 1 to 10, 0 for not rated. This is the archive's native scale, so never convert from IMDb or Metascore. If he gives stars out of 5, double them. date: Date shown on the review, YYYY-MM-DD or YYYY-MM-DD HH:MM, Helsinki time. Use the day he watched it, which Trakt history records, not today. content: His review text. Leave empty rather than writing one for him. status: draft or publish. imdb_url: Full IMDb URL, when there is no tmdb_id. year: Release year, when there is no tmdb_id. plot: Finnish synopsis, when there is no tmdb_id. allow_duplicate: Create even if the film exists. Almost never right.

Change anything about an existing film. Only the fields given change.

Args: id: Film id. title: New title. date: Date shown on the review. See create_film. rating: Whole number 1 to 10, 0 for not rated. See create_film. status: publish or draft. Publishing a draft keeps its date. tmdb_id: Refresh every metadata field, poster and credits from TMDB. The rating and review text are kept. plot: Finnish synopsis. imdb_url: Full IMDb URL. genre: Replace the genres. Finnish names, as list_terms shows them. director: Replace the directors. writer: Replace the writers. actor: Replace the cast.

Move a film to the trash. It can be restored from the WordPress admin.

Args: id: Film id.