# Multilingual Hello-World State Machine - Implementation Plan

## Context

This plan addresses the requirement to implement a simple state machine that cycles through language states (English and Spanish) and produces localized "hello world" greetings. The machine will support transitions between states and include comprehensive unit tests using pytest.

The implementation will establish a professional Python project structure suitable for future expansion, with clear separation between production code (src/) and tests (tests/), standard project configuration files, and modern packaging standards.

## Recommended Approach

### Project Structure
Create a src/tests layout following Python packaging best practices:

```
project/
├── src/
│   └── hello_world/
│       ├── __init__.py
│       └── state_machine.py
├── tests/
│   ├── __init__.py
│   └── test_state_machine.py
├── pyproject.toml
├── pytest.ini
└── setup.py
```

### Core Design: StateMachine Class

**Location**: `src/hello_world/state_machine.py`

**Key Components**:
1. **Language Enum**: Represents supported languages (ENGLISH, SPANISH)
2. **StateMachine Class**: Manages current state and transitions
   - `__init__(initial_language=None)`: Initialize with optional starting language (defaults to ENGLISH)
   - `get_current_language()`: Returns current Language enum value
   - `get_greeting()`: Returns greeting string ("hello world" or "hola mundo")
   - `next()`: Transitions to next language in cycle, returns new state
   - `reset()`: Resets to initial state
   - `print_greeting()`: Prints and returns greeting string

**State Transition Model**:
- States cycle in order: ENGLISH → SPANISH → ENGLISH → ...
- Uses modulo-based index tracking for efficient cycling
- Always cycles forward (no conditional transitions)

**Design Rationale**:
- **Enum for states**: Type-safe, prevents invalid states, enables IDE autocompletion
- **Index-based cycling**: O(1) transitions, predictable modulo behavior
- **Return + Print pattern**: Allows tests to verify output without stdout capture

### Testing Strategy

**Location**: `tests/test_state_machine.py`

**Test Coverage** (17 comprehensive tests):

1. **Initialization** (3 tests)
   - Default state is ENGLISH
   - Custom initial state accepted
   - Initial greeting is correct

2. **State Transitions** (4 tests)
   - English → Spanish transition
   - Spanish → English (looping)
   - Multiple cycles work correctly
   - `next()` returns new state

3. **Greetings** (5 tests)
   - English greeting: "hello world"
   - Spanish greeting: "hola mundo"
   - Greeting changes after transition
   - `print_greeting()` returns string
   - `print_greeting()` prints to stdout

4. **Reset** (3 tests)
   - Reset from Spanish to English
   - Reset after multiple transitions
   - Reset respects custom initial state

5. **Integration** (2 tests)
   - Sequence of greetings in correct order
   - Replay sequence after reset

### Project Configuration

**pyproject.toml**: Modern Python project metadata
- Build system definition (setuptools)
- Project metadata (name, version, description)
- Python version requirement (>=3.8)
- Pytest configuration via tool.pytest.ini_options

**pytest.ini**: Pytest execution configuration
- Minimal version: 7.0
- Verbose output with short traceback format
- Test discovery: `tests/` directory
- Python path includes `src/` directory

**setup.py**: Traditional setup for editable installation
- Package discovery in `src/` directory
- Enables `pip install -e .` for development

## Critical Files to Modify/Create

1. **src/hello_world/__init__.py** - New file
   - Package initialization
   - Public API exports

2. **src/hello_world/state_machine.py** - New file
   - Language enum definition
   - StateMachine class with all methods
   - Greeting mappings

3. **tests/__init__.py** - New file
   - Test package marker (can be empty)

4. **tests/test_state_machine.py** - New file
   - 17 comprehensive unit tests
   - Uses pytest fixtures and stdout capture

5. **pyproject.toml** - New file
   - Modern Python project configuration
   - Build system and metadata
   - Pytest tool configuration

6. **pytest.ini** - New file
   - Pytest behavior configuration

7. **setup.py** - New file
   - Package installation configuration

## Verification & Testing Plan

### Step 1: Project Setup
```bash
pip install -e .
pip install pytest
```

### Step 2: Run All Tests
```bash
pytest tests/ -v
```
Expected: All 17 tests pass

### Step 3: Verify Test Coverage
Test each category:
- **Initialization**: Verify default ENGLISH state and custom initial states
- **Transitions**: Cycle through multiple transitions, confirm looping behavior
- **Greetings**: Confirm each language produces correct output
- **Reset**: Verify return to initial state after transitions
- **Integration**: Run full sequence of greetings and verify correct order

### Step 4: Interactive Verification (Optional)
Create a simple script to manually verify:
```python
from hello_world.state_machine import StateMachine

sm = StateMachine()
for i in range(4):
    print(f"State {i}: {sm.get_greeting()}")
    sm.next()
```
Expected output:
```
State 0: hello world
State 1: hola mundo
State 2: hello world
State 3: hola mundo
```

## Dependencies

**Runtime**: None (standard library only)
**Development**: pytest >= 7.0

## Implementation Order

1. Create directory structure (`src/hello_world/`, `tests/`)
2. Create configuration files (`pyproject.toml`, `pytest.ini`, `setup.py`)
3. Create package initialization (`src/hello_world/__init__.py`)
4. Implement StateMachine class (`src/hello_world/state_machine.py`)
5. Create test package marker (`tests/__init__.py`)
6. Implement comprehensive test suite (`tests/test_state_machine.py`)
7. Run tests and verify all pass