Metadata-Version: 2.4
Name: fresh_blt
Version: 0.2.0
Summary: A CLI tool to parse and convert Opavote .blt ranked choice voter files.
Project-URL: Repository, https://github.com/mpancia/fresh_blt
Author-email: Matt Pancia <msp@themsp.org>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.11
Requires-Dist: lark>=1.2.2
Requires-Dist: pandas>=2.3.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: rich>=14.0.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# 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](installation.md).

Install the package using uv:

```bash
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:

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
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:

```bash
# 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:

```bash
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

```bash
# 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
```
