Metadata-Version: 2.4
Name: paint-on-wordle
Version: 1.0.0
Summary: A reverse-engineering tool that turns your Wordle grid into a canvas. Tell it the colors you want, and it finds the exact words you need to type. Features an interactive CLI wizard and a smart flexible solver.
Author-email: Krzysztof Mizgała <krzysztof@mizgala.pl>
License-Expression: MIT
Project-URL: Homepage, https://github.com/KMChris/paint-on-wordle
Project-URL: Repository, https://github.com/KMChris/paint-on-wordle
Project-URL: Bug Tracker, https://github.com/KMChris/paint-on-wordle/issues
Keywords: python,cli,pixel-art,pattern-matching,reverse-engineering,tui,interactive-cli,wordle,terminal-game,puzzle-solver,wordle-solver
Classifier: Programming Language :: Python :: 3
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynput
Dynamic: license-file

# 🎨 Paint on Wordle

[![PyPI version](https://img.shields.io/pypi/v/paint-on-wordle?style=flat-square)](https://pypi.org/project/paint-on-wordle/)
[![PyPI downloads](https://img.shields.io/pypi/dm/paint-on-wordle?style=flat-square)](https://pypi.org/project/paint-on-wordle/)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg?style=flat-square)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/pypi/l/paint-on-wordle?style=flat-square)](https://opensource.org/licenses/MIT)

**Make Wordle look exactly how you want!**

Paint on Wordle is a powerful solver tool that allows you to reverse-engineer the game. Instead of guessing words to find a solution, you provide the **colors** (pattern) and the **solution word**, and the tool tells you exactly which words you need to type to create that pattern on the grid.

Perfect for creating specific shapes/pixel art on your Wordle grid or solving tricky scenarios.

## Features

*   **🧙 Interactive Wizard:** A step-by-step graphical terminal interface to build your grid visually.
*   **⚡ Instant Solution Mode:** Get immediate results by providing arguments directly in the command line.
*   **🧠 Flexible Matching:** Smart algorithm that prioritizes exact matches but can swap Yellow/Green colors to find the closest possible word for your pattern.
*   **🔍 Exhaustive Search:** Ability to list *all* valid candidates for a pattern, not just the best one.

## Installation

Install the package directly from PyPI:

```
pip install paint-on-wordle
```

## Usage

Once installed, you can run the tool using the command `paint-wordle`.

### 1. Interactive Wizard (Default)

Run without any arguments to start the interactive mode. The tool will guide you through setting the target word and painting the grid row by row.

```
paint-wordle
```

**Controls:**
*   **Arrows / WASD**: Move cursor between tiles.
*   **Space**: Toggle tile color (⬛ Gray -> 🟨 Yellow -> 🟩 Green).
*   **Enter**: Confirm current row pattern and find matching words.
*   **Esc**: Exit the program.

---

### 2. Instant Solution Mode

Use command-line arguments to skip the wizard and get immediate answers. This is useful for scripting or quick lookups.

**Required Arguments:**
*   `--word` / `-w`: The hidden target word (the solution) relative to which patterns are calculated.
*   `--pattern` / `-p`: One or more color patterns to match (e.g., `20010`).

**Pattern Legend:**
*   `0` = Gray (Miss)
*   `1` = Yellow (Wrong Spot)
*   `2` = Green (Exact Match)

#### Advanced Options:

*   **`--flexible` / `-f` (Smart Matching)**
    By default, the solver is strict. If you use this flag, it treats Green and Yellow as interchangeable hits while strictly enforcing Gray spots.
    
    *Logic:* It searches for an **exact match first**. If none exists, it finds the closest match by performing the minimum number of color swaps necessary.

*   **`--find-all` / `-a`**
    Lists **all** valid candidates found for each pattern instead of showing only the single best word.

### Examples

**Basic Exact Match:**
Find a word that generates "Green, Gray, Gray, Gray, Gray" when the solution is "apple":
```
paint-wordle --word apple --pattern 20000
```

**Multiple Patterns:**
Check three different rows at once:
```
paint-wordle -w apple -p 20000 00100 22222
```

**Using Flexible Mode:**
You want a specific pattern, but you don't care if some Yellows become Greens (or vice versa), as long as the Grays stay Gray:
```
paint-wordle -w apple -p 21001 --flexible
```

**List All Candidates:**
Show every single word that fits the pattern, not just the first one found:
```
paint-wordle -w apple -p 00000 --find-all
```

## Development

If you want to contribute or run the code from source:

1.  Clone the repository:
    ```
    git clone https://github.com/KMChris/paint-on-wordle.git
    cd paint-on-wordle
    ```

2.  Install dependencies:
    ```
    pip install -r requirements.txt
    ```

3.  Run via module:
    ```
    python -m src.main
    ```

## Project Structure

*   `src/main.py`: Entry point. Handles argument parsing and mode selection.
*   `src/cli.py`: Handles the interactive wizard interface and user input.
*   `src/solution.py`: Core logic, pattern calculation, and word filtering algorithms.
*   `src/data/words.txt`: The dictionary of valid 5-letter words.
