fresh_blt 0.2.0

A CLI tool to parse and convert Opavote .blt ranked choice voter files.

fresh_blt

A modern CLI tool for parsing and analyzing Opavote BLT (Ballot Language Template) files used in ranked choice voting elections.

Installation

For how to install uv and Python, see installation.md.

Install the package using uv:

uv install .

CLI Usage

The fresh_blt CLI provides several commands for working with BLT files:

Basic Information

Display basic information about a BLT file:

fresh_blt info path/to/election.blt

This shows election title, number of candidates, positions, total ballots, and vote counts.

Candidate Information

Display candidate information with filtering options:

# Show all candidates
fresh_blt candidates path/to/election.blt

# Show only withdrawn candidates
fresh_blt candidates path/to/election.blt --withdrawn-only

# Show only active candidates
fresh_blt candidates path/to/election.blt --active-only

Ballot Information

Display ballot information with various options:

# Show first 10 ballots with first preferences
fresh_blt ballots path/to/election.blt

# Show more ballots
fresh_blt ballots path/to/election.blt --limit 50

# Show detailed rankings for each ballot
fresh_blt ballots path/to/election.blt --show-rankings

Statistical Analysis

Display comprehensive statistical analysis:

fresh_blt stats path/to/election.blt

This provides:

• Candidate counts (total, active, withdrawn)
• Ballot and vote statistics
• First preference analysis with percentages

Data Export

Export BLT data to JSON or CSV formats:

# Export to JSON
fresh_blt export path/to/election.blt -o election_data.json -f json
fresh_blt export path/to/election.blt --output election_data.json --format json

# Export to CSV (creates separate files for candidates and ballots)
fresh_blt export path/to/election.blt -o election_data.csv -f csv
fresh_blt export path/to/election.blt --output election_data.csv --format csv

Validation

Validate BLT file structure and data integrity:

fresh_blt validate path/to/election.blt

This checks for:

• Valid file structure
• Correct candidate references in ballots
• Data consistency

Command Reference

Command	Description	Options
info	Display basic election information	None
candidates	Show candidate details	--withdrawn-only, --active-only
ballots	Display ballot information	--limit, --show-rankings
stats	Show election statistics	None
export	Export data to JSON/CSV	-o/--output, -f/--format
validate	Validate file structure	None

Examples

# Quick overview of an election
fresh_blt info election.blt

# Analyze candidate performance
fresh_blt stats election.blt

# Extract data for further analysis (using short options)
fresh_blt export election.blt -o analysis.json -f json

# Extract data using long options
fresh_blt export election.blt --output analysis.json --format json

# Check file integrity
fresh_blt validate election.blt