Imported from JosefKuchar/pv260-movie-scraper (AGENTS.md). Install upstream with npx skills add JosefKuchar/pv260-movie-scraper. Copyright stays with the author.

Move scraper

This project is a movie scraper that uses Playwright to scrape movie data from various websites. The Playwright is used for navigation and BeautifulSoup is used for parsing the HTML content - so the we can have commited HTML fixtures for testing.

Functional Requirements

• Scrape ratings of the TOP 200 movies on csfd.cz using browser automation

  • Note that the listing is paginated (~100 movies per page), you will have to follow the pagination
  • The original (typically English) title is needed for the next step and is available on each film's detail page

• Look up the same movies on Rotten Tomatoes and collect the Tomatometer and Audience Score (now branded Popcornmeter) for each

  • Document and justify your title-matching strategy (year disambiguation, fallback when no exact match exists, etc.)

• Create two TOP 100 lists based on the ratings of this alternative site (tomatometer and audience score)

  • Both lists should be ordered based on the rating (highest goes first)
  • The object structure should hold all three ratings

• For each movie in the TOP 200 list, find the actors who have ever won an acting Academy Award and aggregate them across the whole list

  • Use the four "Academy Award for Best Actor / Best Actress / Best Supporting Actor / Best Supporting Actress" Wikipedia pages as the source of truth
  • An actor's "oscars" count is the number of times they appear as a winner across these four pages (regardless of which film the award was for)
  • The list should be ordered by the number of oscars (highest goes first)
  • If there are actors with the same number of oscars, they should be ordered alphabetically
  • The object structure should hold the name of the actors and the number of their oscars

Output format

The application should write a single JSON structure to the standard output. All ratings are integers in the 0–100 range. The example below is illustrative (not valid JSON — comments and ellipses are explanatory):

{
  "team": "<team_name>",
  // TOP 100 movies from the TOP 200 list, selected and ordered by Tomatometer
  "tomatometer_100": [
    {
      "title": "Movie A",
      "ratings": {
        "csfd": 95,
        "tomatometer": 89,
        "audience": 80
      }
    },
    {
      "title": "Movie B",
      "ratings": {
        "csfd": 90,
        "tomatometer": 85,
        "audience": 98
      }
    }
    // ...
  ],
  // TOP 100 movies from the TOP 200 list, selected and ordered by Audience Score (Popcornmeter)
  "audience_100": [
    {
      "title": "Movie B",
      "ratings": {
        "csfd": 90,
        "tomatometer": 85,
        "audience": 98
      }
    },
    {
      "title": "Movie A",
      "ratings": {
        "csfd": 95,
        "tomatometer": 89,
        "audience": 80
      }
    }
    // ...
  ],
  // Aggregated across all movies in the TOP 200, ordered by oscars desc, then name asc
  "oscars": [
    { "name": "Actor BA", "oscars": 3 },
    { "name": "Actor BB", "oscars": 3 },
    { "name": "Actor AB", "oscars": 2 }
    // ...
  ]
}

Code quality

After making changes to the code, please make sure to run the following commands to ensure code quality:

• uv run ruff check - to check the code for style and linting issues
• uv run ty check - to check the code for type errors
• uv run pytest - to run tests

Non-functional requirements

• SOLID principles should be followed
• The code should be well-structured and modular
• The code should be well-documented and readable
• The code should be covered by tests