py-sudoku

A simple Python package that generates and solves m x n Sudoku puzzles.

Install

# Python 2
pip install py-sudoku
Python 3
pip3 install py-sudoku

Usage

Basic usage

from sudoku import Sudoku
Initializes a Sudoku puzzle with 3 x 3 sub-grid and
generates a puzzle with half of the cells empty
puzzle = Sudoku(3).difficulty(0.5)
puzzle.show()
+-------+-------+-------+
| 4 1   | 3     | 7 6   |
|   9 3 |   7   | 4   1 |
| 2     | 1 4   |   8 3 |
+-------+-------+-------+
| 9 5 8 |       |     7 |
| 3 4   |     7 |   1   |
|   7 2 | 8 9 3 | 5 4   |
+-------+-------+-------+
|   8   | 2     | 3 7 4 |
|     4 |       | 1 9 5 |
|       |   5   | 6     |
+-------+-------+-------+
solution = puzzle.solve() solution.show() 
+-------+-------+-------+
 | 4 1 5 | 3 8 9 | 7 6 2 |
 | 8 9 3 | 6 7 2 | 4 5 1 |
 | 2 6 7 | 1 4 5 | 9 8 3 |
 +-------+-------+-------+
 | 9 5 8 | 4 1 6 | 2 3 7 |
 | 3 4 6 | 5 2 7 | 8 1 9 |
 | 1 7 2 | 8 9 3 | 5 4 6 |
 +-------+-------+-------+
 | 5 8 9 | 2 6 1 | 3 7 4 |
 | 6 2 4 | 7 3 8 | 1 9 5 |
 | 7 3 1 | 9 5 4 | 6 2 8 |
 +-------+-------+-------+

solution.board 
[[4, 1, 5, 3, 8, 9, 7, 6, 2],
  [8, 9, 3, 6, 7, 2, 4, 5, 1],
  [2, 6, 7, 1, 4, 5, 9, 8, 3],
  [9, 5, 8, 4, 1, 6, 2, 3, 7],
  [3, 4, 6, 5, 2, 7, 8, 1, 9],
  [1, 7, 2, 8, 9, 3, 5, 4, 6],
  [5, 8, 9, 2, 6, 1, 3, 7, 4],
  [6, 2, 4, 7, 3, 8, 1, 9, 5],
  [7, 3, 1, 9, 5, 4, 6, 2, 8]]

solution.width 
3

solution.height 3

Creating puzzles

m x n rectangular puzzles can be initialized using the Sudoku(width) or Sudoku(width, height) constructors.

# Initializes a 3 x 5 puzzle
puzzle = Sudoku(3, 5)
Initializes a 4 x 4 puzzle
puzzle = Sudoku(4)
puzzle = Sudoku(4, 4)

Use

()

to get a solved puzzle, or

(x)

to create a problem.

# Create a 3 x 5 sub-grid problem with 0.4 difficulty (40% of cells empty)
puzzle = Sudoku(3, 5).difficulty(0.4)
Create a solved 4 x 4 problem
puzzle = Sudoku(4).solve()

Displaying puzzles

solution = Sudoku(5, 3).solve()
Shows the puzzle only
solution.show()
+----------------+----------------+----------------+
| 09 10 11 04 06 | 05 01 03 12 13 | 08 14 15 02 07 |
| 03 05 07 08 01 | 02 14 15 09 04 | 06 10 11 12 13 |
| 12 02 13 14 15 | 07 10 06 11 08 | 01 03 04 05 09 |
+----------------+----------------+----------------+
| 13 14 06 11 08 | 15 07 09 02 12 | 10 01 05 03 04 |
| 10 03 15 05 02 | 13 04 08 14 01 | 12 09 07 11 06 |
| 01 07 04 09 12 | 03 05 10 06 11 | 13 02 08 15 14 |
+----------------+----------------+----------------+
| 07 13 08 15 05 | 12 11 04 10 03 | 14 06 09 01 02 |
| 06 01 12 03 09 | 08 02 07 15 14 | 11 13 10 04 05 |
| 04 11 10 02 14 | 06 09 01 13 05 | 15 08 12 07 03 |
+----------------+----------------+----------------+
| 08 12 02 06 10 | 01 13 11 05 07 | 03 04 14 09 15 |
| 05 15 09 13 11 | 14 03 12 04 10 | 02 07 06 08 01 |
| 14 04 01 07 03 | 09 06 02 08 15 | 05 11 13 10 12 |
+----------------+----------------+----------------+
| 11 09 03 12 13 | 10 15 14 07 02 | 04 05 01 06 08 |
| 15 06 14 01 04 | 11 08 05 03 09 | 07 12 02 13 10 |
| 02 08 05 10 07 | 04 12 13 01 06 | 09 15 03 14 11 |
+----------------+----------------+----------------+
Use print or show_full to display more information
print(solution)
solution.show_full()
---------------------------
15x15 (5x3) SUDOKU PUZZLE
Difficulty: SOLVED
---------------------------
+----------------+----------------+----------------+
| 09 10 11 04 06 | 05 01 03 12 13 | 08 14 15 02 07 |
| 03 05 07 08 01 | 02 14 15 09 04 | 06 10 11 12 13 |
| 12 02 13 14 15 | 07 10 06 11 08 | 01 03 04 05 09 |
+----------------+----------------+----------------+
| 13 14 06 11 08 | 15 07 09 02 12 | 10 01 05 03 04 |
| 10 03 15 05 02 | 13 04 08 14 01 | 12 09 07 11 06 |
| 01 07 04 09 12 | 03 05 10 06 11 | 13 02 08 15 14 |
+----------------+----------------+----------------+
| 07 13 08 15 05 | 12 11 04 10 03 | 14 06 09 01 02 |
| 06 01 12 03 09 | 08 02 07 15 14 | 11 13 10 04 05 |
| 04 11 10 02 14 | 06 09 01 13 05 | 15 08 12 07 03 |
+----------------+----------------+----------------+
| 08 12 02 06 10 | 01 13 11 05 07 | 03 04 14 09 15 |
| 05 15 09 13 11 | 14 03 12 04 10 | 02 07 06 08 01 |
| 14 04 01 07 03 | 09 06 02 08 15 | 05 11 13 10 12 |
+----------------+----------------+----------------+
| 11 09 03 12 13 | 10 15 14 07 02 | 04 05 01 06 08 |
| 15 06 14 01 04 | 11 08 05 03 09 | 07 12 02 13 10 |
| 02 08 05 10 07 | 04 12 13 01 06 | 09 15 03 14 11 |
+----------------+----------------+----------------+

Seeds

Problems can be generated with a certain seed.

# Generates a 3x2 puzzle with a given seed
Sudoku(3, 2, seed=100).solve().show()
+-------+-------+
| 5 6 3 | 1 2 4 |
| 2 1 4 | 5 3 6 |
+-------+-------+
| 1 5 2 | 6 4 3 |
| 3 4 6 | 2 5 1 |
+-------+-------+
| 6 3 5 | 4 1 2 |
| 4 2 1 | 3 6 5 |
+-------+-------+

Importing boards

Puzzle boards can also be imported.

board = [
    [0,0,7,0,4,0,0,0,0],
    [0,0,0,0,0,8,0,0,6],
    [0,4,1,0,0,0,9,0,0],
    [0,0,0,0,0,0,1,7,0],
    [0,0,0,0,0,6,0,0,0],
    [0,0,8,7,0,0,2,0,0],
    [3,0,0,0,0,0,0,0,0],
    [0,0,0,1,2,0,0,0,0],
    [8,6,0,0,7,0,0,0,5]
]
puzzle = Sudoku(3, 3, board=board)
print(puzzle) 
---------------------------
 9x9 (3x3) SUDOKU PUZZLE
 Difficulty: 0.74
 ---------------------------
 +-------+-------+-------+
 |     7 |   4   |       |
 |       |     8 |     6 |
 |   4 1 |       | 9     |
 +-------+-------+-------+
 |       |       | 1 7   |
 |       |     6 |       |
 |     8 | 7     | 2     |
 +-------+-------+-------+
 | 3     |       |       |
 |       | 1 2   |       |
 | 8 6   |   7 0 |     5 |
 +-------+-------+-------+

puzzle.solve().show_full() 
---------------------------
 9x9 (3x3) SUDOKU PUZZLE
 Difficulty: SOLVED
 ---------------------------
 +-------+-------+-------+
 | 9 8 7 | 6 4 2 | 5 3 1 |
 | 2 3 5 | 9 1 8 | 7 4 6 |
 | 6 4 1 | 5 3 7 | 9 8 2 |
 +-------+-------+-------+
 | 5 2 6 | 3 8 4 | 1 7 9 |
 | 1 7 3 | 2 9 6 | 8 5 4 |
 | 4 9 8 | 7 5 1 | 2 6 3 |
 +-------+-------+-------+
 | 3 1 9 | 8 6 5 | 4 2 7 |
 | 7 5 4 | 1 2 3 | 6 9 8 |
 | 8 6 2 | 4 7 9 | 3 1 5 |
 +-------+-------+-------+

Invalid boards

Invalid boards give errors when attempted to be solved.

board = [
    [0,0,7,0,4,0,0,0,0],
    [0,0,0,0,0,8,0,0,6],
    [0,4,1,0,0,0,9,0,0],
    [0,0,0,0,0,0,1,7,0],
    [0,0,0,0,0,6,0,0,0],
    [0,0,8,7,0,0,2,0,0],
    [3,0,0,0,0,0,0,0,0],
    [0,0,0,1,2,0,0,0,0],
    [8,6,0,0,7,6,0,0,5]
]
puzzle = Sudoku(3, 3, board=board)
puzzle.show_full() 
---------------------------
 9x9 (3x3) SUDOKU PUZZLE
 Difficulty: 0.74
 ---------------------------
 +-------+-------+-------+
 |     7 |   4   |       |
 |       |     8 |     6 |
 |   4 1 |       | 9     |
 +-------+-------+-------+
 |       |       | 1 7   |
 |       |     6 |       |
 |     8 | 7     | 2     |
 +-------+-------+-------+
 | 3     |       |       |
 |       | 1 2   |       |
 | 8 6   |   7 6 |     5 |
 +-------+-------+-------+

puzzle.solve().show_full() 
---------------------------
 9x9 (3x3) SUDOKU PUZZLE
 Difficulty: INVALID PUZZLE (GIVEN PUZZLE HAS NO SOLUTION)
 ---------------------------
 +-------+-------+-------+
 |       |       |       |
 |       |       |       |
 |       |       |       |
 +-------+-------+-------+
 |       |       |       |
 |       |       |       |
 |       |       |       |
 +-------+-------+-------+
 |       |       |       |
 |       |       |       |
 |       |       |       |
 +-------+-------+-------+

If you wish to raise an UnsolvableSudoku error when the board is invalid pass a raising=True parameter:

puzzle.solve(raising=True)

🔗 More in this category