NHL Scrabble Logo

Getting Started

  • Getting Started
    • How to Install NHL Scrabble
      • Problem
      • Solutions
        • Method 1: Install from source (Recommended for now)
        • Method 2: Install with UV (10x faster)
        • Method 3: Install from PyPI (Future)
        • Method 4: Development installation
        • Method 5: Docker installation (Advanced)
        • Method 6: Offline installation
      • Verification
      • Troubleshooting
        • Issue: “command not found: nhl-scrabble”
        • Issue: “Python 3.12 or higher required”
        • Issue: “Permission denied”
        • Issue: “Failed building wheel for…”
        • Issue: “UV not found”
      • Platform-specific notes
        • macOS
        • Linux
        • Windows
      • Uninstallation
      • Related
    • Getting Started with NHL Scrabble
      • What you’ll learn
      • Prerequisites
      • Installation Options
        • Option A: Standard Installation (Python)
        • Option B: Docker Installation (Recommended for Quick Start)
      • Step 1: Clone the repository
      • Step 2: Set up the development environment
      • Step 3: Run your first analysis
      • Step 4: Understanding the output
        • Conference Standings
        • Division Standings
        • Mock Playoff Bracket
        • Top Players
      • Step 5: Save output to a file
      • Step 6: Try JSON output
      • Step 7: Customize the output
      • What you’ve learned
      • Next steps
      • Troubleshooting
        • Issue: “command not found: nhl-scrabble”
        • Issue: “NHL API Error: Connection timeout”
        • Issue: “Permission denied” when saving output
      • Getting help
    • Installation
      • From Source
    • Quick Start
      • Example Output
    • Next Steps
  • Tutorials
    • Getting Started with NHL Scrabble
      • What you’ll learn
      • Prerequisites
      • Installation Options
        • Option A: Standard Installation (Python)
        • Option B: Docker Installation (Recommended for Quick Start)
      • Step 1: Clone the repository
      • Step 2: Set up the development environment
      • Step 3: Run your first analysis
      • Step 4: Understanding the output
        • Conference Standings
        • Division Standings
        • Mock Playoff Bracket
        • Top Players
      • Step 5: Save output to a file
      • Step 6: Try JSON output
      • Step 7: Customize the output
      • What you’ve learned
      • Next steps
      • Troubleshooting
        • Issue: “command not found: nhl-scrabble”
        • Issue: “NHL API Error: Connection timeout”
        • Issue: “Permission denied” when saving output
      • Getting help
    • Understanding NHL Scrabble Output
      • What you’ll learn
      • Prerequisites
      • Step 1: Generate a full report
      • Step 2: Conference standings
      • Step 3: Division standings
      • Step 4: Mock playoff bracket
      • Step 5: Team detail reports
      • Step 6: League-wide player rankings
      • Step 7: Statistical summary
      • Step 8: Working with JSON output
      • What you’ve learned
      • Next steps
      • Fun challenges
      • Common questions
      • Getting help
    • Your First Contribution to NHL Scrabble
      • What you’ll learn
      • Prerequisites
      • Step 1: Fork the repository
      • Step 2: Clone your fork
      • Step 3: Set up development environment
      • Step 4: Run the test suite
      • Step 5: Create a feature branch
      • Step 6: Make a small change
      • Step 7: Write a test
      • Step 8: Run tests
      • Step 9: Run quality checks
      • Step 10: Commit your changes
      • Step 11: Push to your fork
      • Step 12: Create a pull request
      • Step 13: Wait for CI checks
      • Step 14: Address review feedback
      • Step 15: Celebrate! 🎉
      • What you’ve learned
      • Next steps
      • Tips for success
      • Common issues
        • Issue: Pre-commit hooks failing
        • Issue: Tests passing locally but failing in CI
        • Issue: Merge conflicts
        • Issue: “Permission denied” when pushing
      • Getting help
    • What You’ll Learn
    • Next Steps
    • About the Tutorial Format
    • Tips for Success

User Documentation

  • How-To Guides
    • How to Install NHL Scrabble
      • Problem
      • Solutions
        • Method 1: Install from source (Recommended for now)
        • Method 2: Install with UV (10x faster)
        • Method 3: Install from PyPI (Future)
        • Method 4: Development installation
        • Method 5: Docker installation (Advanced)
        • Method 6: Offline installation
      • Verification
      • Troubleshooting
        • Issue: “command not found: nhl-scrabble”
        • Issue: “Python 3.12 or higher required”
        • Issue: “Permission denied”
        • Issue: “Failed building wheel for…”
        • Issue: “UV not found”
      • Platform-specific notes
        • macOS
        • Linux
        • Windows
      • Uninstallation
      • Related
    • How to Use UV Package Manager
      • Problem
      • Solution
        • Install UV
        • Use UV for installation
        • UV with tox (automatic)
        • Direct UV commands
      • Benefits
      • Related
    • How to Setup Pre-commit Hooks
      • Problem
      • Solution
        • Install hooks
        • Run hooks manually
        • Update hook versions
        • Skip hooks (when needed)
      • Available hooks (55 total)
      • Related
    • How to Configure API Settings
      • Problem
      • Solutions
        • Via Environment Variables
        • Via .env File
        • Via Command-Line Options
      • Common Scenarios
        • Slow network connection
        • Development/testing
        • Production use
      • Related
    • How to Customize Output Format
      • Problem
      • Solutions
        • Change number of players shown
        • Change output format
        • Save to file
        • Verbose output
      • Environment variables
      • Related
    • How to Export to JSON
      • Problem
      • Solution
        • Basic JSON export
        • JSON structure
        • Use with Python
        • Use with jq (command-line)
        • Import to Excel/Google Sheets
      • Related
    • How to Run Tests
      • Problem
      • Quick Start
      • Solutions
        • Method 1: Run all tests (fastest)
        • Method 2: Run with coverage
        • Method 3: Run specific test file
        • Method 4: Run specific test function
        • Method 5: Run tests by marker
        • Method 6: Run with tox (multiple Python versions)
        • Method 7: Run tests on file change (watch mode)
        • Method 8: Run with verbose output
        • Method 9: Run failed tests only
        • Method 10: Run with coverage report
      • Using the Makefile
      • Continuous Integration
      • Test Structure
      • Writing Tests
      • Troubleshooting
        • Issue: “No module named ‘nhl_scrabble’”
        • Issue: “Fixture not found”
        • Issue: Tests pass locally but fail in CI
        • Issue: Slow tests
        • Issue: Import errors
      • Performance Tips
      • Related
    • How to Contribute Code
      • Problem
      • Solution
      • Quick reference
        • 1. Fork and clone
        • 2. Create feature branch
        • 3. Make changes
        • 4. Run quality checks
        • 5. Commit
        • 6. Push and create PR
      • PR checklist
      • Related
    • How to Add a New Report Type
      • Problem
      • Solution
        • Step 1: Create report class
        • Step 2: Add tests
        • Step 3: Register report in CLI
        • Step 4: Run tests
        • Step 5: Update documentation
      • Example: Player Comparison Report
      • Troubleshooting
        • Issue: Import errors
        • Issue: Tests fail
        • Issue: Report not showing
      • Related
    • How to Debug API Issues
      • Problem
      • Common Issues
        • Connection timeout
        • 404 errors
        • Rate limiting
        • Invalid JSON
      • Debugging workflow
      • Related
    • Quick Index
    • How These Guides Work
    • Related Documentation
  • Reference
    • CLI Reference
      • Synopsis
      • Global Options
      • Commands
        • analyze
        • interactive
        • search
        • Future Commands (Planned)
      • Exit Codes
      • Environment Variables
      • Configuration Files
      • Shell Completion
      • Programmatic Usage
      • Logging
      • Examples by Use Case
        • Basic Analysis
        • Data Export
        • Development & Debugging
        • Custom Reports
      • Related
    • CLI Reference (Auto-Generated)
      • Overview
      • Main Command
      • analyze Command
        • Examples
      • Configuration
      • Exit Codes
      • Related Documentation
    • Configuration Reference
      • Overview
      • All Configuration Options
        • API Configuration
        • Caching Configuration
        • Output Configuration
        • Logging Configuration
      • Configuration File (.env)
      • Command-Line Options
      • Configuration Scenarios
        • Development
        • Production
        • Slow Network
      • Validation
      • Related
    • Environment Variables Reference
      • Quick Reference
      • API Configuration
        • NHL_SCRABBLE_API_TIMEOUT
        • NHL_SCRABBLE_API_RETRIES
        • NHL_SCRABBLE_RATE_LIMIT_DELAY
        • NHL_SCRABBLE_MAX_CONCURRENT
      • Caching
        • NHL_SCRABBLE_CACHE_ENABLED
        • NHL_SCRABBLE_CACHE_EXPIRY
      • Output
        • NHL_SCRABBLE_OUTPUT_FORMAT
        • NHL_SCRABBLE_LANG
        • NHL_SCRABBLE_TOP_PLAYERS
        • NHL_SCRABBLE_TOP_TEAM_PLAYERS
      • Logging
        • NHL_SCRABBLE_VERBOSE
        • NHL_SCRABBLE_SANITIZE_LOGS
        • NHL_SCRABBLE_LOG_LEVEL
        • NHL_SCRABBLE_LOG_FORMAT
        • NO_COLOR
        • TERM
      • Web Server Configuration
        • NHL_SCRABBLE_WEB_HOST
        • NHL_SCRABBLE_WEB_PORT
        • NHL_SCRABBLE_WEB_WORKERS
        • NHL_SCRABBLE_CORS_ORIGINS
        • NHL_SCRABBLE_CACHE_TTL
      • Setting Variables
        • Temporary (current shell)
        • Persistent (shell profile)
        • Via .env file
      • Related
    • Makefile Documentation
      • Overview
        • Key Features
      • Quick Start
      • Target Categories
      • Installation & Setup
        • Create Virtual Environment
        • Install Package
        • Sync & Update
        • Check Tools
      • Testing
        • Basic Testing
        • Tox Multi-Environment Testing
      • UV Fast Package Manager
      • Code Quality
        • Linting & Formatting
        • Pre-commit Hooks
      • Security & Dependencies
      • Build & Publish
      • Documentation
      • Running the Application
      • Development Utilities
      • Release Management
      • Cleaning
      • All-in-One Workflows
      • Utility Targets
      • Complete Target Reference
        • Setup & Installation (9 targets)
        • Testing (7 targets)
        • Tox Multi-Environment (6 targets)
        • UV Package Manager (10 targets)
        • Code Quality (8 targets)
        • Security (1 target)
        • Build & Publish (3 targets)
        • Documentation (2 targets)
        • Running (3 targets)
        • Development (4 targets)
        • Release (2 targets)
        • Cleaning (6 targets)
        • All-in-One (2 targets)
        • Utility (2 targets)
      • Common Workflows
        • First Time Setup
        • Daily Development
        • Before Committing
        • Before Pull Request
        • CI Simulation
        • Release Preparation
      • Environment Variables
      • Tips & Tricks
        • 1. Use UV for Speed
        • 2. Parallel Testing
        • 3. Pre-commit with UV
        • 4. Chain Commands
        • 5. Pass Arguments to Tools
      • Troubleshooting
        • Make Command Not Found
        • Virtual Environment Issues
        • UV Not Found
        • Colors Not Showing
      • Resources
      • Summary
    • API Reference (Auto-Generated)
      • Overview
      • Browse API Documentation
        • Main Modules
      • Documentation Quality
      • For Developers
        • Regenerating Documentation
        • Viewing Locally
        • CI Integration
      • Related Documentation
      • External Resources
    • Quick Reference
    • Reference Documentation
    • How to Use This Reference
    • Related Documentation
    • About Auto-Generated Documentation

Understanding

  • Explanation
    • Why Scrabble Scoring?
      • The Concept
      • Origin Story
      • Why This Is Interesting
        • 1. Pure Absurdity
        • 2. Name Diversity
        • 3. Data Science Learning
        • 4. Conversation Starter
      • What It Demonstrates
        • Clean Architecture
        • Testing Strategy
        • Modern Python Practices
        • Documentation as Code
      • Real-World Applications (Seriously!)
        • 1. Name Analysis
        • 2. API Integration Patterns
        • 3. Report Generation
        • 4. Data Pipeline Design
      • Philosophy
        • Embrace the Absurd
        • Perfect Practice Project
        • Teaching Tool
      • Alternatives Considered
        • Why Not Other Metrics?
        • Why NHL and Not Other Sports?
      • Future Directions
        • Historical Analysis
        • Advanced Metrics
        • Web Interface
        • Scrabble Playoffs
      • Conclusion
      • Related
    • Architecture Overview
      • High-Level Architecture
      • Module Organization (May 2026 Refactoring)
        • CLI Package (cli/)
        • Web Package (web/)
        • API Package (api/)
        • Interactive Package (interactive/)
      • Layer Responsibilities
        • 1. CLI Layer (cli/ package)
        • 2. Business Logic Layer
        • 3. Data Layer
      • Design Principles
        • 1. Separation of Concerns
        • 2. Dependency Injection
        • 3. Type Safety
        • 4. Immutability
        • 5. Error Handling
      • Data Flow
      • Testing Strategy
        • Test Pyramid
      • Extension Points
        • 1. Add New Report Type
        • 2. Add New Data Source
        • 3. Add New Output Format
      • Performance Considerations
        • Bottleneck: API Calls
        • Memory: Minimal
        • CPU: Negligible
      • Trade-offs
        • Pydantic vs Dataclasses
        • Async vs Sync
        • Rich vs Plain Text
        • Click vs Argparse
      • Future Architecture
        • 1. Plugin System
        • 2. Web API
        • 3. Database Storage
        • 4. Async API Client
      • Related
    • NHL API Strategy
      • The NHL API
      • Why This API?
        • Alternatives Considered
      • Integration Approach
        • 1. Retry Logic
        • 2. Rate Limiting
        • 3. Caching
        • 4. Error Handling
      • Data Validation
      • Trade-offs
        • Synchronous vs Async
        • Caching Strategy
        • Error Handling Philosophy
      • Future Improvements
        • 1. Async/Parallel Fetching
        • 2. Persistent Caching
        • 3. Webhook/Streaming
        • 4. GraphQL Alternative
      • Related
    • Testing Philosophy
      • Testing Goals
      • Test Pyramid
        • Why this distribution?
      • What We Test
        • Core Logic (100% coverage goal)
        • API Client (Integration tests)
        • CLI (Integration tests)
        • Reports (Unit tests)
      • What We Don’t Test
        • External APIs
        • Framework Code
      • Mocking Strategy
        • When to Mock
        • How We Mock
      • Test Organization
      • Naming Conventions
      • Coverage Targets
      • Test Fixtures
      • Parametrized Tests
      • Continuous Integration
      • Trade-offs
        • High Coverage vs Speed
        • Mocking vs Real APIs
        • Unit vs Integration
      • Future Improvements
        • Property-Based Testing
        • Mutation Testing
        • Performance Testing
      • Related
    • Topics Covered
    • About Explanations
    • When to Read Explanations
    • Related Documentation

API Documentation

  • API Reference
    • CLI Module
      • generate_excel_report()
      • run_analysis()
      • validate_cli_arguments()
      • validate_output_path()
      • Main Command
        • cli()
      • Analyze Command
        • analyze()
      • Usage Patterns
      • Related Documentation
    • Models Module
      • Overview
        • ConferenceStandings
        • DivisionStandings
        • PlayerScore
        • PlayoffTeam
        • TeamScore
      • Player Models
        • PlayerScore
        • Player
        • PlayerScore
      • Team Models
        • TeamScore
        • Team
        • TeamScore
      • Standings Models
        • DivisionStandings
        • ConferenceStandings
        • PlayoffTeam
        • DivisionStandings
        • ConferenceStandings
      • Related Documentation
    • NHL API Module
      • NHLApiClient
        • NHLApiClient.base_url
        • NHLApiClient.timeout
        • NHLApiClient.retries
        • NHLApiClient.rate_limiter
        • NHLApiClient.circuit_breaker
        • NHLApiClient.ca_bundle
        • NHLApiClient.BASE_URL
        • NHLApiClient.__init__()
        • NHLApiClient.__del__()
        • NHLApiClient.get_teams()
        • NHLApiClient.get_team_roster()
        • NHLApiClient.get_player_details()
        • NHLApiClient.get_rate_limit_stats()
        • NHLApiClient.clear_cache()
        • NHLApiClient.get_cache_info()
        • NHLApiClient.close()
        • NHLApiClient.__enter__()
        • NHLApiClient.__exit__()
      • NHLApiConnectionError
      • NHLApiError
      • NHLApiNotFoundError
      • NHLApiSSLError
      • get_retry_after()
      • handle_connection_error()
      • handle_http_error()
      • NHL Client
        • NHLApiClient
        • NHLApiConnectionError
        • NHLApiError
        • NHLApiNotFoundError
        • NHLApiSSLError
        • NHLClient
      • Methods
        • fetch_all_teams
        • fetch_team_roster
        • fetch_all_rosters
      • Error Handling
      • Rate Limiting
      • Retry Logic
      • Related Documentation
    • Scoring Module
      • ScrabbleScorer
        • ScrabbleScorer.LETTER_VALUES
        • ScrabbleScorer.__init__()
        • ScrabbleScorer.calculate_score()
        • ScrabbleScorer.calculate_score_custom()
        • ScrabbleScorer.score_player()
        • ScrabbleScorer.get_cache_info()
        • ScrabbleScorer.log_cache_stats()
        • ScrabbleScorer.clear_cache()
      • Scrabble Scorer
        • ScrabbleScorer
        • ScrabbleScorer
      • Letter Values
      • Methods
        • calculate_score
        • score_player
      • Usage Patterns
      • Special Cases
      • Related Documentation
    • Processors Module
      • GroupStatistics
        • GroupStatistics.player_count
        • GroupStatistics.total_score
        • GroupStatistics.average_score
        • GroupStatistics.min_score
        • GroupStatistics.max_score
        • GroupStatistics.top_player
        • GroupStatistics.player_count
        • GroupStatistics.total_score
        • GroupStatistics.average_score
        • GroupStatistics.min_score
        • GroupStatistics.max_score
        • GroupStatistics.top_player
      • PlayoffCalculator
        • PlayoffCalculator.calculate_playoff_standings()
      • TeamProcessor
        • TeamProcessor.__init__()
        • TeamProcessor.process_all_teams()
        • TeamProcessor.calculate_division_standings()
        • TeamProcessor.calculate_conference_standings()
      • calculate_group_statistics()
      • group_by_birth_country()
      • group_by_conference()
      • group_by_division()
      • group_by_nationality()
      • group_by_position()
      • group_by_position_code()
      • group_by_position_type()
      • group_by_team()
      • Team Processor
        • TeamProcessor
        • TeamProcessor
        • process_teams
        • get_division_standings
        • get_conference_standings
      • Playoff Calculator
        • PlayoffCalculator
        • PlayoffCalculator
        • calculate_playoff_bracket
        • Playoff Indicators
        • Tiebreakers
      • Usage Patterns
      • Related Documentation
    • Reports Module
      • BaseReporter
        • BaseReporter.generate()
      • ConferenceReporter
        • ConferenceReporter.generate()
      • DivisionReporter
        • DivisionReporter.generate()
      • PlayoffReporter
        • PlayoffReporter.generate()
      • StatsReporter
        • StatsReporter.__init__()
        • StatsReporter.generate()
      • TeamReporter
        • TeamReporter.__init__()
        • TeamReporter.generate()
      • Base Report
        • BaseReporter
        • BaseReport
      • Conference Report
        • ConferenceReporter
        • ConferenceReport
      • Division Report
        • DivisionReporter
        • DivisionReport
      • Playoff Report
        • PlayoffReporter
        • PlayoffReport
      • Team Report
        • TeamReporter
        • TeamReport
      • Stats Report
        • StatsReporter
        • StatsReport
      • Usage Patterns
      • Rich Console Features
      • Related Documentation
    • Package Overview
      • Command-Line Interface
      • Data Models
      • NHL API Client
      • Scoring Logic
      • Business Logic
      • Report Generators
    • Module Dependency Graph
    • Quick Example
    • Type Hints and Type Safety
    • Async/Await Support
    • Pydantic Data Validation
    • Related Documentation

Development

  • Development Guide
    • How to Contribute Code
      • Problem
      • Solution
      • Quick reference
        • 1. Fork and clone
        • 2. Create feature branch
        • 3. Make changes
        • 4. Run quality checks
        • 5. Commit
        • 6. Push and create PR
      • PR checklist
      • Related
    • How to Run Tests
      • Problem
      • Quick Start
      • Solutions
        • Method 1: Run all tests (fastest)
        • Method 2: Run with coverage
        • Method 3: Run specific test file
        • Method 4: Run specific test function
        • Method 5: Run tests by marker
        • Method 6: Run with tox (multiple Python versions)
        • Method 7: Run tests on file change (watch mode)
        • Method 8: Run with verbose output
        • Method 9: Run failed tests only
        • Method 10: Run with coverage report
      • Using the Makefile
      • Continuous Integration
      • Test Structure
      • Writing Tests
      • Troubleshooting
        • Issue: “No module named ‘nhl_scrabble’”
        • Issue: “Fixture not found”
        • Issue: Tests pass locally but fail in CI
        • Issue: Slow tests
        • Issue: Import errors
      • Performance Tips
      • Related
    • How to Setup Pre-commit Hooks
      • Problem
      • Solution
        • Install hooks
        • Run hooks manually
        • Update hook versions
        • Skip hooks (when needed)
      • Available hooks (55 total)
      • Related
    • Architecture Overview
      • High-Level Architecture
      • Module Organization (May 2026 Refactoring)
        • CLI Package (cli/)
        • Web Package (web/)
        • API Package (api/)
        • Interactive Package (interactive/)
      • Layer Responsibilities
        • 1. CLI Layer (cli/ package)
        • 2. Business Logic Layer
        • 3. Data Layer
      • Design Principles
        • 1. Separation of Concerns
        • 2. Dependency Injection
        • 3. Type Safety
        • 4. Immutability
        • 5. Error Handling
      • Data Flow
      • Testing Strategy
        • Test Pyramid
      • Extension Points
        • 1. Add New Report Type
        • 2. Add New Data Source
        • 3. Add New Output Format
      • Performance Considerations
        • Bottleneck: API Calls
        • Memory: Minimal
        • CPU: Negligible
      • Trade-offs
        • Pydantic vs Dataclasses
        • Async vs Sync
        • Rich vs Plain Text
        • Click vs Argparse
      • Future Architecture
        • 1. Plugin System
        • 2. Web API
        • 3. Database Storage
        • 4. Async API Client
      • Related
    • Testing Philosophy
      • Testing Goals
      • Test Pyramid
        • Why this distribution?
      • What We Test
        • Core Logic (100% coverage goal)
        • API Client (Integration tests)
        • CLI (Integration tests)
        • Reports (Unit tests)
      • What We Don’t Test
        • External APIs
        • Framework Code
      • Mocking Strategy
        • When to Mock
        • How We Mock
      • Test Organization
      • Naming Conventions
      • Coverage Targets
      • Test Fixtures
      • Parametrized Tests
      • Continuous Integration
      • Trade-offs
        • High Coverage vs Speed
        • Mocking vs Real APIs
        • Unit vs Integration
      • Future Improvements
        • Property-Based Testing
        • Mutation Testing
        • Performance Testing
      • Related
    • Quick Links for Contributors
    • Development Setup
      • Quick Start
    • Testing
    • Code Quality
    • Code Style Standards
      • Example Code
    • Contributing Workflow
      • Commit Message Format
    • Building Documentation
    • Release Process
    • Project Resources
    • Development Tools
    • Community

Project Links

  • GitHub Repository
  • Issue Tracker
  • Changelog
NHL Scrabble
  • Search

© Copyright 2026, Brandon Perkins.

Built with Sphinx using a theme provided by Read the Docs.