nhl-scrabble 0.0.5rc0

NHL Roster Scrabble Score Analyzer - Calculate Scrabble scores for NHL player names

NHL Scrabble Score Analyzer

A Python application that fetches current NHL roster data and calculates "Scrabble scores" for player names based on standard Scrabble letter values. Generate comprehensive reports showing team, division, and conference standings complete with playoff brackets!

Features

• 🏒 Live NHL Data - Fetches current roster data from the official NHL API
• 🌐 Web Interface - FastAPI-powered server with interactive dashboard
  • Interactive dashboard with real-time analysis
  • Chart.js visualizations and graphs
  • REST API with OpenAPI documentation
  • Mobile-friendly responsive design (WCAG 2.1 AA)
• 📊 Comprehensive Reports - Conference/division standings, playoff brackets, team scores, statistics
• 📈 Progress Tracking - Real-time progress bars for long operations
• 🎯 Flexible Output - Text, JSON, or HTML format
• 🎨 Colorized Logging - Color-coded log levels with TTY detection and NO_COLOR support
• 🧪 Well-Tested - >90% coverage on core modules with 170+ tests
• ⚡ Lightning Fast - UV support for 10-100x faster installation
• 🔒 Production-Ready - Security headers, CORS, caching, deployment guides

Screenshots

Web Interface

The NHL Scrabble web interface provides a modern, interactive experience:

• Main Dashboard - Clean, responsive design with one-click analysis
• Analysis Results - Sortable tables, standings, playoff brackets, statistics
• Interactive Features - Chart.js visualizations, export (JSON/CSV/PDF), table sorting
• API Documentation - Swagger UI (/docs) and ReDoc (/redoc)

CLI Output

Text Output (Default)

🏒 NHL SCRABBLE SCORE ANALYSIS 🏒

TOP 20 PLAYERS BY SCRABBLE SCORE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1. Alexander Ovechkin (WSH)    45 points
2. Zdeno Chara (BOS)           42 points
...

JSON Output - Machine-readable format for integrations

HTML Output - Fully styled browser report with embedded CSS

Installation

From Source

# Clone the repository
git clone https://github.com/bdperkin/nhl-scrabble.git
cd nhl-scrabble

# Install in development mode
make init

# Or manually with pip
pip install -e ".[dev]"

Requirements

• Supported: Python 3.12, 3.13, 3.14
• Experimental: Python 3.15-dev (CI testing only, may have issues)
• Dependencies: requests, click, pydantic, python-dotenv, rich, fastapi, uvicorn, jinja2
• Note: UV acceleration is automatic when using tox (via tox-uv plugin)

Quick Start

Run the analysis with default settings:

nhl-scrabble analyze

Or use the Python module directly:

python -m nhl_scrabble analyze

For detailed usage, see the CLI Tutorial.

Usage

CLI Commands

# Basic analysis
nhl-scrabble analyze

# Verbose output with colorized logging
nhl-scrabble analyze -v

# JSON output to file
nhl-scrabble analyze -f json -o report.json

# HTML output
nhl-scrabble analyze -f html -o report.html

# Customize display
nhl-scrabble analyze --top-players 50 --top-team-players 10

Web Server

# Start web server (default port 8000)
nhl-scrabble serve

# Custom host and port with auto-reload
nhl-scrabble serve --host 0.0.0.0 --port 5000 --reload

Visit http://localhost:8000/docs for interactive API documentation.

Interactive Dashboard

# Launch terminal dashboard
nhl-scrabble dashboard

# Filter by division/conference
nhl-scrabble dashboard --divisions Atlantic --conferences Eastern

# Static snapshot (no live updates)
nhl-scrabble dashboard --static

Complete Usage Documentation:

• CLI Tutorial - Step-by-step CLI guide
• CLI Reference - All commands and options
• Configuration Guide - Environment variables and settings

How It Works

The analyzer uses standard English Scrabble letter point values (A=1, Z=10, etc.) to score player names. It fetches live NHL data, calculates scores, aggregates by team/division/conference, and generates comprehensive reports with playoff brackets.

Learn More:

• Why Scrabble Scoring? - The concept explained
• How Scrabble Scoring Works - Detailed scoring logic
• Architecture Overview - System design
• NHL API Strategy - API integration approach

Development

Quick Start

# Clone and setup
git clone https://github.com/bdperkin/nhl-scrabble.git
cd nhl-scrabble
make init
source .venv/bin/activate

# View all available commands (57 targets)
make help

Testing

# Run all tests
make test

# Run with coverage
make test-cov

# Multi-version testing with tox
make tox              # Test Python 3.12, 3.13, 3.14
make tox-parallel     # Faster parallel execution

Code Quality

# Format and lint
make ruff-format
make ruff-check

# Type checking
make mypy

# Run all quality checks
make quality

# Full validation (format + quality + tests)
make check

Pre-commit Hooks

The project uses 67 comprehensive pre-commit hooks for automatic code quality validation:

# Install hooks (one-time)
pre-commit install

# Run all hooks manually
pre-commit run --all-files

# Update hook versions
pre-commit autoupdate

Complete Development Documentation:

• CONTRIBUTING.md - Development guidelines and workflow
• Makefile Reference - All 57 Makefile targets
• Testing Guide - Test execution and configuration
• UV Package Manager - 10-100x faster installation

Project Structure

nhl-scrabble/
├── src/nhl_scrabble/          # Main package
│   ├── api/                   # NHL API client
│   ├── scoring/               # Scrabble scoring logic
│   ├── models/                # Data models (Pydantic)
│   ├── processors/            # Business logic
│   ├── reports/               # Report generators
│   ├── cli.py                 # CLI interface (Click)
│   └── config.py              # Configuration management
├── tests/                     # Test suite (170+ tests)
│   ├── unit/                  # Unit tests
│   └── integration/           # Integration tests
├── docs/                      # Documentation (Diátaxis framework)
├── pyproject.toml             # Project & UV configuration
└── uv.lock                    # Dependency lock file (1,957 lines)

See Architecture Overview for detailed system design.

Documentation

Online Documentation: https://bdperkin.github.io/nhl-scrabble/

Documentation follows the Diátaxis framework:

• Tutorials - Step-by-step lessons for beginners
  • Getting Started
  • Understanding Output
  • First Contribution
• How-to Guides - Practical solutions to specific tasks
  • Installation Variations
  • Run Tests
  • Add Report Type
  • Use UV Package Manager
• Reference - Technical specifications
  • CLI Reference
  • Configuration
  • Makefile Reference
  • Environment Variables
  • Project Stats
• Explanation - Design philosophy and concepts
  • Why Scrabble Scoring?
  • Architecture Overview
  • NHL API Strategy

Community:

• CONTRIBUTING.md - Development guidelines
• SECURITY.md - Security policy
• SUPPORT.md - Getting help
• CHANGELOG.md - Version history
• CLAUDE.md - Project overview for Claude Code

Contributing

Contributions are welcome! See CONTRIBUTING.md for detailed guidelines.

Quick Overview:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run quality checks (make check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Security

This project takes security seriously with comprehensive automated scanning:

• Dependabot - Automated dependency updates and security alerts
• pip-audit - CI vulnerability scanning
• CodeQL - Weekly security scans
• Pre-commit hooks - 67 comprehensive quality and security checks

Reporting Vulnerabilities: See SECURITY.md for responsible disclosure guidelines. Do not report security vulnerabilities through public GitHub issues.

Support

• Documentation: https://bdperkin.github.io/nhl-scrabble/
• Issues: Report bugs or request features via GitHub Issues
• Discussions: Ask questions in GitHub Discussions

See SUPPORT.md for detailed support information.

License

This project is licensed under the MIT License - see the LICENSE file for details.

All runtime dependencies use permissive licenses compatible with MIT (Apache, BSD, ISC, etc.). See LICENSES.md for the complete list.

To verify license compliance:

tox -e licenses

Project Statistics

• Test Coverage: 49.93% overall, >90% on core modules
• Tests: 170+ tests (100% passing)
• Modules: 15 core modules
• Makefile Targets: 57 documented targets
• Pre-commit Hooks: 67 comprehensive quality checks
• CI/CD: GitHub Actions on Python 3.12, 3.13, 3.14 (required), 3.15-dev (experimental)

See Project Stats for complete metrics.

Acknowledgments

• NHL API for providing roster data
• Scrabble is a trademark of Hasbro, Inc.

Changelog

See CHANGELOG.md for version history.

---

Made with ❤️ for hockey and word games