Sudoku Plus 🧩

Sudoku Plus is a complete Python toolkit for Sudoku enthusiasts, hobbyists, and developers. Whether you want to generate challenging puzzles, solve them programmatically, or validate solutions, this project provides all the tools you need.

With a clean CLI interface, modular Python code, and a full test suite, Sudoku Plus is perfect for learning algorithms, experimenting with puzzle generation techniques, or integrating Sudoku features into your own projects.

A complete Sudoku toolkit in Python featuring:

Sudoku board generator
Sudoku solver (backtracking + optional advanced heuristics)
Validator (check if a Sudoku is valid)
CLI interface for generating and solving puzzles
Test suite for all modules

📂 Project Structure

sudoku_plus/
│── src/
│   └── sudoku_plus/
│       ├── __init__.py
│       ├── board.py
│       ├── generator.py
│       ├── solver.py
│       ├── validator.py
│       └── cli.py
│
│── tests/
│   ├── test_board.py
│   ├── test_generator.py
│   ├── test_solver.py
│   ├── test_validator.py
│
│── main.py
│── requirements.txt
│── README.md

⚡ Installation

Clone this repository:

git clone https://github.com/BaseMax/sudoku_plus.git
cd sudoku_plus

(Optional) Create a virtual environment:

python3 -m venv venv

On Linux:

source venv/bin/activate

On Windows:

venv\Scripts\activate

Install requirements:

pip install -r requirements.txt

Install your project in editable mode

From project root:

pip install -e .

-e = editable → you can edit source code without reinstalling.

After this, sudoku_plus is recognized as a proper Python package.

Run your CLI anywhere

Now you can do:

python -m sudoku_plus.cli gen --size 9 --difficulty medium

Or, because we added [project.scripts], you can also run directly:

sudoku gen --size 9 --difficulty medium

🔹 Generate a Sudoku Puzzle

python -m sudoku_plus.cli gen --size 9 --difficulty medium

--size → board size (default: 9)
--difficulty → easy | medium | hard

Example:

python -m sudoku_plus.cli gen --size 9 --difficulty hard

🔹 Solve a Sudoku Puzzle

Provide a puzzle as a string (0 = empty):

python -m sudoku_plus.cli solve "530070000600195000098000060800060003400803001700020006060000280000419005000080079"

Or read from file:

python -m sudoku_plus.cli solve --file puzzle.txt

🔹 Validate a Sudoku Board

python -m sudoku_plus.cli validate <puzzle_string> <solution_string>

For example:

python -m sudoku_plus.cli validate "530070000600195000098000060800060003400803001700020006060000280000419005000080079" "534678912672195348198342567859761423426853791713924856961537284287419635345286179"

🧪 Running Tests

Tests are written with pytest. To run all tests:

pytest tests/

Run a specific test file:

pytest tests/test_solver.py

BaseMax/sudoku_plus