Utilities and Common Modules

Utility modules and common functionality used throughout the Wordle Solver.

Types

Centralized imports and type definitions for the Wordle Solver. This module helps eliminate circular imports and provides a single point for common types.

class src.common.types.SolverStrategyProtocol(*args, **kwargs)

Bases: Protocol

Protocol defining the interface for solver strategies.

get_top_suggestions(possible_words, common_words, guesses_so_far, count=10, word_manager=None)

Get top N suggestions based on the strategy’s algorithm.

Return type:

List[str]

__init__(*args, **kwargs)

class src.common.types.WordManagerProtocol(*args, **kwargs)

Bases: Protocol

Protocol defining the interface for word management.

get_all_words()

Get all valid words.

Return type:

List[str]

get_common_words()

Get common words subset.

Return type:

List[str]

is_valid_word(word)

Check if word is valid.

Return type:

bool

__init__(*args, **kwargs)

class src.common.types.GameMode(value)

Bases: Enum

Available game modes.

SOLVER = 'solver'

PLAYER = 'player'

class src.common.types.GameOutcome(value)

Bases: Enum

Possible game outcomes.

WON = 'won'

LOST = 'lost'

IN_PROGRESS = 'in_progress'

Utilities

Common utilities for error handling and validation across the Wordle Solver.

src.common.utils.validate_word_input(word, word_length=5)

Validate word input ensuring it meets Wordle requirements.

Parameters:

• word (str) – The word to validate

• word_length (int) – Expected word length (default: 5)

Return type:

str

Returns:

The validated and normalized word (uppercase)

Raises:

InvalidGuessError – If the word is invalid

src.common.utils.validate_result_pattern(result, expected_length=5)

Validate result pattern ensuring it contains only valid color codes.

Parameters:

• result (str) – The result pattern to validate

• expected_length (int) – Expected pattern length (default: 5)

Return type:

str

Returns:

The validated and normalized result pattern (uppercase)

Raises:

InvalidResultError – If the result pattern is invalid

src.common.utils.safe_execute(operation_name='operation')

Decorator to safely execute operations and handle common exceptions.

Parameters:

operation_name (str) – Name of the operation for error messages

src.common.utils.format_guess_history(guesses_history)

Format guess history for display purposes.

Parameters:

guesses_history (list) – List of [guess, result, strategy] tuples

Return type:

str

Returns:

Formatted string representation of the guess history

src.common.utils.calculate_success_metrics(guesses_history, won)

Calculate various success metrics from guess history.

Parameters:

• guesses_history (list) – List of guess attempts

• won (bool) – Whether the game was won

Return type:

dict

Returns:

Dictionary containing success metrics

Cache

Caching utilities for performance optimization in the Wordle Solver.

class src.common.cache.TTLCache(max_size=128, ttl_seconds=300)

Bases: object

Time-to-live cache implementation.

__init__(max_size=128, ttl_seconds=300)

get(key)

Get value from cache if not expired.

Return type:

Optional[Any]

set(key, value)

Set value in cache with current timestamp.

Return type:

None

clear()

Clear all cache entries.

Return type:

None

size()

Get the current size of the cache (public method).

Return type:

int

src.common.cache.cache_word_frequency(func)

Decorator to cache word frequency calculations.

Return type:

Callable[..., TypeVar(T)]

src.common.cache.cache_strategy_results(func)

Decorator to cache strategy calculation results.

Return type:

Callable[..., TypeVar(T)]

src.common.cache.cache_pattern_calculation(func)

Decorator to cache pattern calculation results.

Return type:

Callable[..., TypeVar(T)]

src.common.cache.cached_word_pattern(guess, target)

Cached version of word pattern calculation. This is the most frequently called function in strategy calculations.

Return type:

str

src.common.cache.clear_all_caches()

Clear all performance caches.

Return type:

None

src.common.cache.get_cache_stats()

Get statistics about cache usage.

Return type:

Dict[str, Dict[str, Any]]

Dependency Injection Container

Dependency injection container for the Wordle Solver application.

class src.common.di_container.DIContainer

Bases: object

Simple dependency injection container.

__init__()

register_singleton(interface, factory)

Register a singleton factory.

Return type:

None

register_factory(interface, factory)

Register a factory that creates new instances each time.

Return type:

None

get(interface)

Get an instance of the requested type.

Return type:

TypeVar(T)

reset_singletons()

Reset all singleton instances (useful for testing).

Return type:

None

src.common.di_container.get_container()

Get the global container instance.

Return type:

DIContainer

src.common.di_container.configure_container_for_testing()

Configure a container specifically for testing with mocks.

Return type:

DIContainer

src.common.di_container.reset_container()

Reset the global container (useful for testing).

Return type:

None

Strategy Manager

Enhanced strategy management with improved factory pattern and performance optimizations.

class src.common.strategy_manager.StrategyManager

Bases: object

Enhanced strategy manager with caching and performance monitoring.

__init__()

register_strategy(name, strategy_class)

Register a new strategy class.

Return type:

None

get_strategy(name)

Get a strategy instance (cached for performance).

Return type:

StatelessSolverStrategy

get_suggestions_with_monitoring(strategy_name, possible_words, common_words, guesses_so_far, count=10, word_manager=None)

Get suggestions with performance monitoring.

Return type:

List[str]

get_available_strategies()

Get list of available strategy names.

Return type:

List[str]

get_performance_stats()

Get performance statistics for all strategies.

Return type:

Dict[str, Dict[str, Any]]

get_recommended_strategy(possible_words_count, guesses_made)

Recommend the best strategy based on game state.

Return type:

str

clear_instances()

Clear cached strategy instances (useful for testing).

Return type:

None

src.common.strategy_manager.get_strategy_manager()

Get the global strategy manager instance.

Return type:

StrategyManager

src.common.strategy_manager.reset_strategy_manager()

Reset the global strategy manager (useful for testing).

Return type:

None

Configuration Settings

Configuration settings for the Wordle solver application.

class src.config.settings.GameSettings(max_attempts=6, word_length=5)

Bases: object

Settings for the Wordle game.

max_attempts: int = 6

word_length: int = 5

__init__(max_attempts=6, word_length=5)

class src.config.settings.LoggingSettings(level='INFO', format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', file_handler=True, console_handler=True, backup_count=30)

Bases: object

Settings for logging configuration.

level: str = 'INFO'

format: str = '%(asctime)s - %(name)s - %(levelname)s - %(message)s'

file_handler: bool = True

console_handler: bool = True

backup_count: int = 30

__init__(level='INFO', format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', file_handler=True, console_handler=True, backup_count=30)

class src.config.settings.SolverSettings(default_strategy='entropy', suggestions_count=10, enable_memory_optimization=True, enable_performance_profiling=False)

Bases: object

Settings for the solver strategies.

default_strategy: str = 'entropy'

suggestions_count: int = 10

enable_memory_optimization: bool = True

enable_performance_profiling: bool = False

__init__(default_strategy='entropy', suggestions_count=10, enable_memory_optimization=True, enable_performance_profiling=False)

class src.config.settings.AppSettings(game=None, logging=None, solver=None)

Bases: object

Main application settings.

__init__(game=None, logging=None, solver=None)

game: GameSettings

logging: LoggingSettings

solver: SolverSettings

classmethod load_from_file(config_path)

Load settings from a YAML configuration file.

Return type:

AppSettings

to_dict()

Convert settings to dictionary format.

Return type:

Dict[str, Any]

src.config.settings.get_environment()

Get the current environment setting from the WORDLE_ENVIRONMENT variable.

If not set or empty, defaults to ‘PROD’. Valid values are ‘DEV’ and ‘PROD’.

Returns:

The current environment (‘DEV’ or ‘PROD’)

Return type:

str

src.config.settings.get_settings()

Get the global application settings instance.

Return type:

AppSettings

src.config.settings.initialize_config(config_path=None)

Initialize configuration from file or use defaults.

Parameters:

config_path (Optional[str]) – Optional path to configuration file

Return type:

AppSettings

Returns:

AppSettings instance

src.config.settings.reset_settings()

Reset the global settings instance (useful for testing).

Return type:

None