Metadata-Version: 2.4
Name: yahtzee-li
Version: 0.6.3
Summary: A professional-grade, colorful CLI Yahtzee game for 1-4 players
Project-URL: Homepage, https://github.com/carlmatt/yahtzee-li
Project-URL: Repository, https://github.com/carlmatt/yahtzee-li.git
Project-URL: Issues, https://github.com/carlmatt/yahtzee-li/issues
Project-URL: Changelog, https://github.com/carlmatt/yahtzee-li/blob/main/change-log.md
Author-email: Carl Mattsson <carl.mattsson@gmail.com>
License: MIT
License-File: LICENSE
Keywords: cli,dice,game,terminal,tui,yahtzee
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.12
Requires-Dist: rich>=13.0
Description-Content-Type: text/markdown

# yahtzee-li *(yaht-CLI)*

[![PyPI version](https://img.shields.io/pypi/v/yahtzee-li.svg)](https://pypi.org/project/yahtzee-li/)
[![Python 3.12+](https://img.shields.io/pypi/pyversions/yahtzee-li.svg)](https://pypi.org/project/yahtzee-li/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Actions status](https://github.com/carlmatt/yahtzee-li/workflows/CI/badge.svg)](https://github.com/carlmatt/yahtzee-li/actions)

A professional-grade, colorful CLI Yahtzee game for 1–4 players, built in Python with `rich`.

## Features

- Full Yahtzee rule set: upper-section bonus (35 pts at ≥63), Yahtzee bonus (+100 per extra Yahtzee), and the official joker rule
- Vivid terminal UI: ASCII-art dice panels, live multi-player scorecards, and a victory screen
- 1–4 human players per game
- "Play again" prompt after each game — keep the same players or start fresh

## Requirements

- Python 3.12+
- [`uv`](https://github.com/astral-sh/uv) (recommended) or any virtual-environment manager

## Installation

### From PyPI

```bash
pip install yahtzee-li
```

Or with `uv`:

```bash
uv tool install yahtzee-li
```

### From source (development)

```bash
git clone https://github.com/carlmatt/yahtzee-li.git
cd yahtzee-li
uv sync
```

## Running the game

```bash
# With uv / the project virtual environment
uv run yahtzee-li

# Or activate the venv first
source venv/bin/activate
yahtzee-li
```

## Development

```bash
# Install dev dependencies
make install

# Run the game
make run

# Run the full test suite (unit + integration)
make test

# Run only one tier
make test-unit
make test-integration

# Run tests with coverage report
make test-cov

# Lint and format (combined)
make fix

# Lint only
make lint

# Format only
make format

# Type check (Astral's ty)
make typecheck

# Lint + typecheck + test
make check

# Remove cache and build artifacts
make clean
```

### Tests

Tests are organised into two folders:

- `tests/unit/` — fast unit tests that mock collaborators and cover individual modules.
- `tests/integration/` — end-to-end tests that drive a real `Game` through full flows using a scripted `Display` double and a deterministic dice RNG. Tests in this folder are auto-marked with `@pytest.mark.integration`, so you can also run them via `pytest -m integration`.

### Pre-commit hooks

This project uses [pre-commit](https://pre-commit.com/) to enforce code quality on every commit. The hooks run `ruff` (lint) and `ruff-format` automatically.

```bash
# Install the git hooks (once, after cloning)
pre-commit install

# Run all hooks manually against every file
pre-commit run --all-files
```

## How to Play

1. Enter the number of players (1–4) and each player's name.
2. On each turn, all five dice are rolled automatically.
3. After each roll you may hold any dice by entering their numbers (e.g. `1,3,5`), press Enter to hold none, or enter `d` to skip straight to scoring.
4. After up to three rolls, choose a scoring category from the numbered list.
5. The game runs for 13 rounds; the player with the highest grand total wins.
6. Press **Ctrl-C** at any time to quit.

## Scoring Reference

| Category | Score |
| --- | --- |
| Ones – Sixes | Sum of matching dice |
| Three of a Kind | Sum of all dice (if ≥3 match) |
| Four of a Kind | Sum of all dice (if ≥4 match) |
| Full House | 25 pts |
| Small Straight | 30 pts |
| Large Straight | 40 pts |
| Yahtzee | 50 pts |
| Chance | Sum of all dice |
| Upper Bonus | +35 if upper subtotal ≥ 63 |
| Yahtzee Bonus | +100 per extra Yahtzee |
