CLI Module

Command-line interface for NHL Scrabble Score Analyzer.

The CLI module provides the main entry point using Click for command-line argument parsing and subcommand management.

Command-line interface for NHL Scrabble.

class nhl_scrabble.cli.DashboardData[source]

Bases: TypedDict

Type definition for dashboard data dictionary.

team_scores

Dictionary of team abbreviations to team scores

all_players

List of all players with scores

division_standings

Division-level standings

conference_standings

Conference-level standings

team_scores: dict[str, TeamScore]
all_players: list[PlayerScore]
division_standings: dict[str, DivisionStandings]
conference_standings: dict[str, ConferenceStandings]
nhl_scrabble.cli.validate_output_path(output)[source]

Validate that output path is writable before processing.

Checks that the output path’s parent directory exists and is writable, and that any existing file at the path is also writable. This validation happens before any API calls to provide immediate feedback on path issues.

Parameters:

output (str | None) – Output file path, or None for stdout.

Raises:

click.ClickException – If output path is not writable, with helpful error message explaining the issue and how to fix it.

Return type:

None

Example

>>> validate_output_path("/tmp/output.txt")  # OK
>>> validate_output_path(None)  # OK (stdout)
>>> validate_output_path("/nonexistent/dir/file.txt")  # Raises
ClickException: Output directory does not exist: /nonexistent/dir
Create it first: mkdir -p /nonexistent/dir
nhl_scrabble.cli.validate_cli_arguments(output)[source]

Validate CLI output path before processing.

Uses validators module to check output path for security issues. This validation happens before any API calls to provide immediate feedback.

Note

Numeric validation (top_players, top_team_players, etc.) is now handled by Click’s IntRange type directly in option definitions, eliminating redundant validation.

Parameters:

output (str | None) – Output file path, or None for stdout

Return type:

Path | None

Returns:

Validated output path, or None for stdout

Raises:

click.ClickException – If output path is invalid with helpful error message

Security:

  • Prevents path traversal attacks via output path

  • Provides early validation before expensive operations

Examples

>>> validate_cli_arguments("output.txt")
PosixPath('/current/dir/output.txt')
>>> validate_cli_arguments(None)  # stdout
None
nhl_scrabble.cli.generate_excel_report(team_scores, all_players, division_standings, conference_standings, playoff_standings, output, sheets=None)[source]

Generate Excel format report.

Creates a comprehensive Excel workbook with multiple sheets for different aspects of the analysis.

Parameters:
Return type:

None

Returns:

None (writes directly to file)

Raises:

ImportError – If openpyxl is not installed

Example

>>> from pathlib import Path
>>> generate_excel_report(
...     team_scores={"TOR": team_score},
...     all_players=[player1, player2],
...     division_standings={"Atlantic": div_standings},
...     conference_standings={"Eastern": conf_standings},
...     playoff_standings={"Eastern": [team1, team2]},
...     output=Path("report.xlsx"),
...     sheets=["Teams", "Players"],  # Optional: limit sheets
... )
# Creates report.xlsx with Teams and Players sheets
nhl_scrabble.cli.run_analysis(config, clear_cache=False, report_filter=None, quiet=False, output_path=None, sheets=None, scoring_values=None, filters=None, season=None, template_file=None)[source]

Run the complete NHL Scrabble analysis.

Uses dependency injection to create properly configured components, making the function easier to test and maintain.

Parameters:

  • config (Config) – Configuration object

  • clear_cache (bool) – Whether to clear the API cache before running

  • report_filter (str | None) – Optional filter for specific report type (conference, division, playoff, team, stats)

  • quiet (bool) – Whether to suppress progress bars

  • output_path (Path | None) – Optional output file path for CSV/Excel exports

  • sheets (list[str] | None) – Optional list of sheets for Excel export

  • scoring_values (dict[str, int] | None) – Optional custom letter-to-point value mapping. If None, uses standard Scrabble values.

  • filters (AnalysisFilters | None) – Optional filters to apply to analysis results

  • season (str | None) – Optional season to analyze (format: YYYYYYYY, e.g., 20222023). If None, analyzes current season.

  • template_file (str | None) – Optional path to Jinja2 template file (for template format)

Return type:

str | None

Returns:

Complete report string for text/JSON/YAML/XML/HTML/Table/Markdown/Template formats, or None for CSV/Excel (CSV/Excel are written directly to output file)

Raises:

NHLApiError – If there are issues fetching data from NHL API

nhl_scrabble.cli.generate_search_text(results, query, fuzzy, min_score, max_score, teams, divisions, conferences, limit)[source]

Generate text format search results.

Parameters:

  • results (list[PlayerScore]) – List of PlayerScore objects

  • query (str | None) – Search query

  • fuzzy (bool) – Whether fuzzy matching was used

  • min_score (int | None) – Minimum score filter

  • max_score (int | None) – Maximum score filter

  • teams (str | None) – Team filter

  • divisions (str | None) – Division filter

  • conferences (str | None) – Conference filter

  • limit (int) – Result limit

Return type:

str

Returns:

Formatted text output

nhl_scrabble.cli.generate_search_json(results, query, stats)[source]

Generate JSON format search results.

Parameters:
Return type:

str

Returns:

JSON string

nhl_scrabble.cli.fetch_dashboard_data(config, quiet=False, season=None)[source]

Fetch data needed for dashboard.

Uses dependency injection to create properly configured components.

Parameters:

  • config (Config) – Configuration object

  • quiet (bool) – Whether to suppress progress bars

  • season (str | None) – Optional season to analyze (format: YYYYYYYY, e.g., 20222023)

Return type:

DashboardData | None

Returns:

Dictionary with team_scores, all_players, division_standings, conference_standings, or None if fetching failed

Main Command

nhl_scrabble.cli.cli(*args, **kwargs)

NHL Roster Scrabble Score Analyzer.

Fetch NHL roster data and calculate Scrabble scores for player names. Generate comprehensive reports showing team, division, and conference standings.

The main CLI entry point that serves as the command group.

Analyze Command

nhl_scrabble.cli.analyze(*args, **kwargs)

Run the NHL Scrabble analysis.

Fetches current NHL roster data and generates comprehensive reports with Scrabble scores for all players and teams.

b .. admonition:: Examples

Basic usage with text output to stdout:

$ nhl-scrabble analyze

Enable verbose logging for debugging:

$ nhl-scrabble analyze –verbose

Suppress progress bars (quiet mode):

$ nhl-scrabble analyze –quiet

Save text output to file:

$ nhl-scrabble analyze –output report.txt

JSON format output to file:

$ nhl-scrabble analyze –format json –output report.json

YAML format output to file:

$ nhl-scrabble analyze –format yaml –output report.yaml

XML format output to file:

$ nhl-scrabble analyze –format xml –output report.xml

HTML format output to file:

$ nhl-scrabble analyze –format html –output report.html

Markdown format output to file:

$ nhl-scrabble analyze –format markdown –output report.md

Table format to terminal:

$ nhl-scrabble analyze –format table

CSV format output to file:

$ nhl-scrabble analyze –format csv –output report.csv

Excel workbook with all sheets:

$ nhl-scrabble analyze –format excel –output report.xlsx

Excel with specific sheets only:

$ nhl-scrabble analyze –format excel –sheets teams,players –output report.xlsx

Custom template output:

$ nhl-scrabble analyze –format template –template custom.j2 –output report.txt

Disable API response caching:

$ nhl-scrabble analyze –no-cache

Clear cache before running:

$ nhl-scrabble analyze –clear-cache

Generate specific report only:

$ nhl-scrabble analyze –report team

Generate playoff report to file:

$ nhl-scrabble analyze –report playoff –output playoffs.txt

Use alternative scoring system (Wordle):

$ nhl-scrabble analyze –scoring wordle

Use custom scoring configuration:

$ nhl-scrabble analyze –scoring-config custom_values.json

Filter by division:

$ nhl-scrabble analyze –divisions Atlantic

Filter by conference:

$ nhl-scrabble analyze –conferences Eastern

Filter by specific teams:

$ nhl-scrabble analyze –teams TOR,MTL,OTT

Filter by score range:

$ nhl-scrabble analyze –min-score 50 –max-score 100

Exclude specific teams:

$ nhl-scrabble analyze –exclude-teams BOS,NYR

Analyze specific season:

$ nhl-scrabble analyze –season 20222023

Combine multiple options:

$ nhl-scrabble analyze –format json –output report.json –verbose $ nhl-scrabble analyze –divisions Atlantic –min-score 60 –output atlantic.txt

Run comprehensive NHL roster analysis with customizable output options.

Options:

  • --format - Output format (text or json)

  • --output - Output file path

  • --verbose - Enable verbose logging

  • --top-players - Number of top players to display

  • --top-team-players - Number of players per team to display

Examples:

# Basic usage
nhl-scrabble analyze

# JSON output
nhl-scrabble analyze --format json --output report.json

# Verbose mode
nhl-scrabble analyze --verbose

# Custom display limits
nhl-scrabble analyze --top-players 50 --top-team-players 10

Usage Patterns

Standard Analysis:

from nhl_scrabble.cli import analyze
from click.testing import CliRunner

runner = CliRunner()
result = runner.invoke(analyze)

Custom Configuration:

result = runner.invoke(analyze, ["--format", "json", "--output", "report.json", "--verbose"])