ESC Dramatic Unpause

A Eurovision Song Contest (ESC) scoring prediction system that helps calculate the final televoting scores to determine the winner before the last country's points are announced.

What is this?

This tool helps predict Eurovision Song Contest results by combining jury scores with televoting scores. The main goal is to skip the 20-30 seconds when the last country is about to receive their televoting points.

By entering all but one country's televoting scores, the system calculates what the final country's score must be, instantly revealing the winner without the suspense. It features:

• Interactive score entry with a beautiful terminal UI
• Automatic calculation of the final missing televoting score
• Dramatic pause with spinner animation (because Eurovision needs drama!)
• Winner announcement with celebration

Features

• Interactive CLI: Enter televoting scores one by one with Rich's beautiful interface
• Smart Validation: Prevents negative scores and validates input format
• Backtrack Support: Go back and correct previous entries with 'b'
• Automatic Calculation: Calculates the final country's televoting score based on ESC rules
• Dramatic Presentation: Includes spinner animations and winner announcements
• Comprehensive Testing: Full test suite with historical ESC data

Motive

While the main goal of this project is the one described above, it was the occasion for me to learn how to create CLI apps in python (with Typer) and how to create beautiful terminal UIs (with Rich), with an original idea.

Requirements

• Python 3.12 or higher
• Dependencies are managed via uv

Installation

1. Clone the repository:

git clone h
cd esc-drammatic-unpause

2. Install dependencies using uv:

uv sync

Or using pip:

pip install -e .

Usage

Basic Usage

Run the program with a jury scores file:

python -m src

Custom Options

python -m src --jury-path your_jury_file.txt --participating-countries 37 --rest-of-world-vote

Available options:

• --jury-path: Path to jury scores file (default: jury.txt)
• --participating-countries: Number of participating countries (default: 37)
• --rest-of-world-vote / --no-rest-of-world-vote: Include rest of world televote (default: enabled, introduced in 2023)

Jury File Format

Create a text file with jury scores in the following format:

Country Name 123
Another Country 456
Switzerland 789

Each line should contain:

• Country name (can include spaces)
• Score (integer, separated by space)

Interactive Process

1. The program displays current jury scores
2. Enter televoting scores for each country (except the last one)
3. Use 'b' to go back and correct previous entries
4. Confirm your final entry
5. Watch the dramatic pause...
6. See the calculated final scores and winner announcement!

How It Works

The system follows Eurovision scoring rules:

1. Jury Scores: Pre-calculated professional jury points
2. Televoting Scores: User enters N-1 country scores interactively
3. Final Calculation: The last country's televoting score is automatically calculated based on:
   • Total available points: (12+10+8+7+6+5+4+3+2+1) × voting countries
   • Voting countries = participating countries (+ 1 rest of the world if enabled, introduced in 2023)
   • Minus the sum of all entered televoting scores
4. Winner: Country with highest combined jury + televoting score

Testing

Run the test suite:

uv run pytest tests

The tests use EurovisionAPI/dataset and test data from 2016 to 2025 included.

The tests include:

• Score calculation accuracy
• File parsing functionality
• CLI interface testing

Dependencies

• Rich: Beautiful terminal UI, tables, and animations
• Typer: Modern CLI framework
• pytest: Testing framework

Development dependencies:

• basedpyright: Type checking
• ruff: Linting and formatting
• orjson: Fast JSON parsing for tests

License

This project is open source under the MIT License.