mfdf_ninja 🥷

Automated booking of tickets for events at the Ji.hlava International Documentary Film Festival (MFDF Jihlava) 💘, so you can sleep in after those long, thoroughly enjoyed festival days 😴.

This simple app logs into the festival reservation service (Eventival) and books tickets you pre‑configure for each festival day.

Note: The festival is awesome, you should come.

Key Info

• Self-hosted Python app
• Run with python -m mfdf_ninja (entrypoint: mfdf_ninja/__main__.py)
• Configuration: Environment variables & one JSON file (database-as-a-json-file)
  • Local file: DB_LOCATION=local
  • S3 object: DB_LOCATION=s3
• Can be run locally or remotely (e.g. Heroku)
• If the first pass does not book all specified tickets, it performs several retries.
• Implemented with restraint and consideration to the reservation service, ensuring the BE server only receives reasonable traffic.

Example Logs

See docs/example-output.txt for a full, real execution log run in remotely in Heroku + S3 storage.

Not Covered

• This app needs to be externally scheduled to run at reservation start time (Heroku Scheduler, cron, Windows Task Scheduler, a user pressing Enter...)
• If you want to run this remotely (recommended), i.e. without any user action or your local machine having to run during the reservation window, you need to set up your own S3 storage. This includes an Amazon account, an S3 bucket, and a service user with GetObject/PutObject permissions.

Environment Variables

You can set these via a .env file or directly in your shell environment.

Required for Eventival login:

• EVENTIVAL_USERNAME - your Eventival account email/username
• EVENTIVAL_PASSWORD - your Eventival account password

Database selection and naming:

• DB_LOCATION - local or s3
• DB_FILE_NAME - JSON file name (and S3 object key when using S3). Default: mfdf_ninja_data.json

If using S3 (DB_LOCATION=s3), also set:

• AWS_ACCESS_KEY_ID - your service user's access key id (found in IAM)
• AWS_SECRET_ACCESS_KEY - the associated secret key
• AWS_DEFAULT_REGION
• S3_BUCKET_NAME - your bucket name

Configuring Events To Book

The state of which events still need to be booked is managed in a single JSON document with this structure:

• events_to_book - a mapping from YYYY-MM-DD to a list of Eventival event IDs to book that day.

Example:

{
    "events_to_book": {
        "2025-10-25": ["8457001"],
        "2025-10-26": ["8457002"]
    }
}

Notes:

• Event IDs can be found in the HTML code when browsing the film schedule section of the Eventival website. Open the screening you're interested in and use the browser's Inspect element function on the Add to Favorites button, the section of intereset looks like this: <button data-url="/jidff/2025/favorite/8457001" class="button secondary icon small add-favorite.... In this case, 8457001 is the event ID.

Running Locally

• Install dependencies: pip install -r requirements.txt
• Create .env (copy from .env_template and edit values), and create/edit your local mfdf_ninja_data.json.
• Execute: python -m mfdf_ninja

Running Remotely (Heroku)

• Fork this repo and set it as your app, set Config Vars for all required environment variables.
• Create/edit your remote mfdf_ninja_data.json on S3.
• Use Heroku Scheduler to run daily at the reservation start time.
• Command to run: python -m mfdf_ninja
• Costs: This app is short-lived when orchestrated like described above, so Heroku costs 0$ and S3 costs pennies.

Related Utilities

• scripts/manage_data_in_s3.py - convenience script to view and/or update the JSON database on S3.

Alternative Solution

• scripts/book.sh provides an alternative solution - a much simpler, standalone bash script. The downside is that you have to manually log into Eventival each day and obtain a fresh ev_vp cookie (and then run the script manually, or schedule it as per the above).