Game Components

Core game logic and components for the Wordle Solver.

Game Engine

Game engine module for handling the game logic when the computer selects a target word.

class src.modules.backend.game_engine.GameEngine(event_bus=None)[source]

Bases: object

Handles the computer vs player game mode.

__init__(event_bus=None)[source]

Initialize a new GameEngine instance.

The GameEngine maintains strict encapsulation by creating and controlling its own WordManager and StatsManager instances.

property game_id: str: Get the current game ID or raise an exception if there is no active game.

start_new_game()[source]

Start a new game by selecting a random target word.

Return type:: str

make_guess(guess, mode=None)[source]

Make a guess and return the result pattern and whether the game is won.

Parameters:

guess (str) – The word being guessed
mode (str) – Optional game mode identifier (manual, solver, etc.)

Return type:

Tuple[str, bool]

Returns:

(result_pattern, is_solved)

get_remaining_guesses()[source]

Get number of remaining guesses.

Return type:: int

is_game_won()[source]

Check if the game has been won.

Return type:: bool

is_game_over()[source]

Check if the game is over (won or max guesses reached).

Return type:: bool

get_game_state()[source]

Get current game state.

Return type:: Dict[str, object]

get_hint()[source]

Get a hint for the current game.

Return type:: str

Game State Manager

Result Color

Enumeration of result colors for Wordle feedback.

class src.modules.backend.result_color.ResultColor(value)[source]

Bases: Enum

Enumeration of possible letter result colors in Wordle.

GREEN = 'G'

YELLOW = 'Y'

BLACK = 'B'

classmethod from_char(char)[source]

Convert a character representation to the corresponding ResultColor.

Return type:: ResultColor

classmethod is_valid_result_string(result)[source]

Check if a string contains only valid result characters.

Return type:: bool

classmethod is_winning_result(result)[source]

Check if a result string represents a winning game (all green).

Return type:: bool

classmethod result_to_emoji(result)[source]

Convert a result string to emoji representation for sharing.

Return type:: str

classmethod parse_result(result_str)[source]

Parse a string of result characters into a list of ResultColor objects.

Return type:: List[ResultColor]

classmethod format_result(colors)[source]

Convert a list of ResultColor objects to a string representation.

Return type:: str

to_style()[source]

Get the Rich style string for this color.

Return type:: str

Word Manager

Game History Manager

Game history management for reviewing previous games.

exception src.modules.backend.game_history_manager.GameHistoryError(message='')[source]

Bases: WordleError

Exception raised for game history related errors.

class src.modules.backend.game_history_manager.GameHistoryManager(history_file_path=None)[source]

Bases: object

Manages loading and processing game history data.

__init__(history_file_path=None)[source]

load_game_history()[source]

Load and parse game history from JSON file.

Return type:: List[Dict]

paginate_games(games, page_size=10)[source]

Split games into pages of specified size.

Return type:: List[List[Dict]]

get_game_by_id(game_id)[source]

Find and return a game by its ID.

Return type:: Optional[Dict]

format_game_summary(game)[source]

Format a game for display in the summary table.

Return type:: Dict[str, str]

validate_game_id(game_id)[source]

Validate that a game ID is in the correct format (6 characters).

Return type:: bool

Stats Manager

Module for managing game statistics and history.

class src.modules.backend.stats_manager.StatsManager(history_file='game_history.json', event_bus=None)[source]

Bases: GameStateObserver

Handles game statistics and history storage/retrieval.

__init__(history_file='game_history.json', event_bus=None)[source]

notify(event)[source]

Called when a relevant event occurs.

Parameters:: event – The event that occurred

save_history()[source]

Save game history to file.

Return type:: None

get_stats()[source]

Calculate and return current statistics dynamically from game history.

Return type:: Dict[str, Any]

get_history(limit=None)[source]

Get game history, optionally limited to the most recent games.

Return type:: List[Dict[str, Any]]

get_game_by_id(game_id)[source]

Get a specific game by its ID.

Parameters:: game_id (str) – The unique ID of the game to retrieve
Return type:: Optional[Dict[str, Any]]
Returns:: The game record if found, None otherwise

search_games(game_id=None, won=None, target_word=None, max_attempts=None)[source]

Search for games matching specific criteria.

Parameters:

game_id (Optional[str]) – Filter by game ID (exact match)
won (Optional[bool]) – Filter by game outcome (won/lost)
target_word (Optional[str]) – Filter by target word
max_attempts (Optional[int]) – Return only games with attempts <= this value

Return type:

List[Dict[str, Any]]

Returns:

List of matching game records

clear_all_history()[source]

Clear all game history and reset to blank.

Returns:: True if successful, False if there was an error
Return type:: bool

get_history_count()[source]

Get the total number of games in history.

Return type:: int

has_history()[source]

Check if there is any game history.

Return type:: bool

Exceptions

Custom exception classes for the Wordle Solver application. This module defines specialized exceptions for different error conditions in the game.

class src.modules.backend.exceptions.DebugLogMixin[source]: Bases: object

exception src.modules.backend.exceptions.WordleError(message='')[source]

Bases: Exception

Base class for all Wordle-related exceptions.

__init__(message='')[source]

exception src.modules.backend.exceptions.GameStateError(message='')[source]

Bases: WordleError

Raised when an operation is attempted in an invalid game state.

exception src.modules.backend.exceptions.InvalidGuessError(guess, reason)[source]

Bases: DebugLogMixin, WordleError

Raised when a guess is invalid.

__init__(guess, reason)[source]

exception src.modules.backend.exceptions.InvalidWordError(word)[source]

Bases: InvalidGuessError

Raised when a word is not in the word list.

__init__(word)[source]

exception src.modules.backend.exceptions.InvalidResultError(result, reason)[source]

Bases: DebugLogMixin, WordleError

Raised when a result pattern is invalid.

__init__(result, reason)[source]

exception src.modules.backend.exceptions.InvalidColorError(char)[source]

Bases: DebugLogMixin, WordleError

Raised when an invalid color character is used.

__init__(char)[source]

exception src.modules.backend.exceptions.InputLengthError(input_type, actual_length, expected_length=5)[source]

Bases: DebugLogMixin, WordleError

Raised when input is not the correct length.

__init__(input_type, actual_length, expected_length=5)[source]