nhl_scrabble.scoring

Scrabble scoring module.

Classes

ScrabbleScorer([letter_values])

Calculate Scrabble scores for player names using configurable letter values.

class nhl_scrabble.scoring.ScrabbleScorer(letter_values=None)

Bases: object

Calculate Scrabble scores for player names using configurable letter values.

This class provides methods to calculate scores based on letter point values. By default, uses standard English Scrabble values, but supports custom scoring systems via the letter_values parameter.

Default letter values (standard Scrabble):

• 1 point: A, E, I, O, U, L, N, S, T, R

• 2 points: D, G

• 3 points: B, C, M, P

• 4 points: F, H, V, W, Y

• 5 points: K

• 8 points: J, X

• 10 points: Q, Z

Custom scoring systems can be provided via the letter_values parameter, enabling alternative scoring methods (e.g., Wordle scoring, uniform values).

LETTER_VALUES: ClassVar[dict[str, int]] = {'A': 1, 'B': 3, 'C': 3, 'D': 2, 'E': 1, 'F': 4, 'G': 2, 'H': 4, 'I': 1, 'J': 8, 'K': 5, 'L': 1, 'M': 3, 'N': 1, 'O': 1, 'P': 3, 'Q': 10, 'R': 1, 'S': 1, 'T': 1, 'U': 1, 'V': 4, 'W': 4, 'X': 8, 'Y': 4, 'Z': 10}

__init__(letter_values=None)

Initialize the scorer with custom or default letter values.

Parameters:

letter_values (dict[str, int] | None) – Optional custom letter-to-points mapping. If None, uses standard Scrabble values.

Examples

>>> # Standard Scrabble scoring
>>> scorer = ScrabbleScorer()
>>> scorer.calculate_score("ALEX")
11

>>> # Custom scoring (all letters worth 1 point)
>>> uniform_values = {chr(i): 1 for i in range(65, 91)}
>>> scorer = ScrabbleScorer(letter_values=uniform_values)
>>> scorer.calculate_score_custom("ALEX")
4

static calculate_score(name)

Calculate the Scrabble score for a given name using standard values.

This static method provides convenient scoring with default Scrabble letter values. For custom scoring values, create a ScrabbleScorer instance and use the calculate_score_custom() method.

This method uses LRU caching to avoid recomputing scores for duplicate names, which significantly improves performance when processing ~700 NHL players with many duplicate first/last names.

Cache size: 2048 entries (sufficient for all unique name components)

Parameters:

name (str) – The name to score (can include spaces and special characters)

Return type:

int

Returns:

The total Scrabble score (non-letter characters are worth 0 points)

Examples

>>> ScrabbleScorer.calculate_score("ALEX")
11
>>> ScrabbleScorer.calculate_score("Ovechkin")
20

calculate_score_custom(name)

Calculate score using custom letter values configured in this instance.

Use this method when you’ve created a ScrabbleScorer with custom letter values. For default Scrabble scoring, use the static calculate_score() method.

Parameters:

name (str) – The name to score (can include spaces and special characters)

Return type:

int

Returns:

The total score using custom letter values

Examples

>>> uniform_values = {chr(i): 1 for i in range(65, 91)}
>>> scorer = ScrabbleScorer(letter_values=uniform_values)
>>> scorer.calculate_score_custom("ALEX")
4

score_player(player_data, team, division, conference, position_category='')

Score a player and return a PlayerScore object.

Uses custom letter values if configured, otherwise uses default Scrabble values.

Parameters:

• player_data (dict[str, Any]) – Dictionary with ‘firstName’, ‘lastName’, and optionally ‘id’, ‘birthCity’, ‘birthStateProvince’, ‘birthCountry’, ‘positionCode’ keys

• team (str) – Team abbreviation

• division (str) – Division name

• conference (str) – Conference name

• position_category (str) – Position category from API roster grouping (‘forwards’, ‘defensemen’, or ‘goalies’)

Return type:

PlayerScore

Returns:

PlayerScore object with all scoring and birthplace information

Examples

>>> scorer = ScrabbleScorer()
>>> player = {
...     "id": 8478402,
...     "firstName": {"default": "Connor"},
...     "lastName": {"default": "McDavid"},
...     "positionCode": "C"
... }
>>> result = scorer.score_player(player, "EDM", "Pacific", "Western", "forwards")
>>> result.full_score
24
>>> result.player_id
8478402
>>> result.position
'Center'
>>> result.position_type
'Forward'

static get_cache_info()

Get cache statistics for the score calculation cache.

Returns:

• hits: Number of cache hits

• misses: Number of cache misses

• maxsize: Maximum cache size

• currsize: Current cache size

Return type:

dict[str, int]

Examples

>>> info = ScrabbleScorer.get_cache_info()
>>> info['maxsize']
2048

static log_cache_stats()

Log cache statistics for monitoring and performance analysis.

Logs hit rate, total calls, and cache utilization at INFO level.

Return type:

None

static clear_cache()

Clear the score calculation cache.

Useful for testing or when memory needs to be freed.

Return type:

None