Represents the Sudoku puzzle model itself. More...

Public Member Functions
def	__init__ (self)
	Creates an empty Puzzle with the grid and Fields set up. More...

str	__str__ (self)
	The str(Puzzle) More...

str	__repr__ (self)
	The repr(Puzzle) Internal usage of repr(Field) More...

tuple[int\|None]	serialize (self)
	Serializes the puzzle as a tuple. More...

Field	getField (self, int row, int col)
	Core Functions. More...

list[Field]	getFlatGrid (self)
	Returns the flat grid (flat copy) NOTE: Use this function, when iterating over full grid. More...

def	iterGrid (self)
	Generator over the grid. More...

list[Field]	getRow (self, *int row)
	Returns a row of the puzzle. More...

list[Field]	getColumn (self, *int col)
	Returns a column of the puzzle. More...

list[Field]	getBlock (self, *int row, int col)
	Returns the block of the puzzle. More...

bool	isFinished (self)
	Properties. More...

int\|None	getValue (self, int row, int col)
	Value-Functions. More...

bool	setValue (self, int row, int col, int value)
	Checks and sets the value. More...

bool	clearValue (self, int row, int col)
	Clears a non-empty, non-fixed Field. More...

bool	addNote (self, int row, int col, int value)
	Note-Functions. More...

bool	removeNote (self, int row, int col, int value)
	Removes a Note, if exists. More...

None	clearNotes (self, int row, int col)
	Remove all the Notes from a Field. More...

None	autoNotes (self)
	Creates Notes for emtpy Fields automatically. More...

None	clearAllNotes (self)
	clears all the notes for empty Fields. More...

bool	usedInRow (self, *int row, int value)
	Row-, Column-, Block-Functions. More...

bool	usedInColumn (self, *int col, int value)
	checks if value exists in column. More...

bool	usedInBlock (self, *int row, int col, int value)
	Checks if value exists in block. More...

bool	isValidCell (self, int row, int col, int value)
	The standard sudoku rules - If value not in row, column or block, then True. More...

bool	hasValidCandidates (self)
	Check if one cell has no Candidates. More...

bool	hasNoDuplicateValues (self)
	Checks for duplicate values in the puzzle regarding row, column and block. More...

bool	isValid (self)
	A puzzle is valid if there are no duplicate values in row, column and block and every cell has at least one candidate. More...

list[Field]	getEmptyFields (self, bool sortByNotesLength=False)
	Get specific Fields and other. More...

list[Field]	getNonEmptyFields (self)
	Returns all the non-empty Fields in a single list. More...

list[Field]	getFixedFields (self)
	Returns all the fixed Fields in a single list. More...

list[Field]	getNonFixedFields (self)
	Returns all the fixed Fields in a single list. More...

None	lockValues (self)
	Set all Non-Empty Fields to fixed, so they cannot be edited. More...

"Puzzle"	clone (cls, "Puzzle" original)
	New Puzzles - Functions. More...

"Puzzle"	loadFromSerialized (cls, tuple[int\|None] serialized)
	(classmethod) Creates a Puzzle from a serialized tuple. More...

"Puzzle"	loadFromList (cls, list[list[int\|None]] grid)
	(classmethod) Creates a Puzzle from a nested list. More...

"Puzzle"	generateSolution (cls, bool verbose=True)
	(classmethod) Creates an empty Puzzle and generates a Solution Fills the diagonal Blocks from top left to bottom right with random Digits (independent to each other). More...

Detailed Description

Represents the Sudoku puzzle model itself.

The Puzzle stores the grid as an internal 2D structure of Field objects
and provides a defensive public API to safely access and manipulate them.
Direct access to the internal storage is intentionally restricted in
order to preserve consistency and validation.

This class contains no higher-level game flow logic. Its responsibility is
limited to:
    - enforcing standard Sudoku rules
    - managing values and notes
    - querying rows, columns, and blocks
    - validating puzzle states
    - generating a solution and cloning puzzles

The Puzzle exposes utility functions to retrieve specific groups of fields,
such as empty, fixed, or non-fixed cells, and provides helper methods for
serialization and loading external puzzle data.

The generation logic focuses on readability and maintainability rather than
heavy optimization. Nevertheless, valid Sudoku solutions can be generated
efficiently using recursive filling strategies.

This class acts as the core data model within the application's
Model-View-Controller architecture.

Constructor & Destructor Documentation

◆ init()

def puzzle.Puzzle.__init__ ( self )

Creates an empty Puzzle with the grid and Fields set up.

Member Function Documentation

◆ repr()

str puzzle.Puzzle.__repr__ ( self )

The repr(Puzzle) Internal usage of repr(Field)

◆ str()

str puzzle.Puzzle.__str__ ( self )

The str(Puzzle)

See also: _print(_str=True), so internal

◆ addNote()

bool puzzle.Puzzle.addNote	(		self,
		int	row,
		int	col,
		int	value
	)

Note-Functions.

Adds a Note to an empty, non-fixed Field.

   @param row: int - the row of a Field
   @param col: int - the column of a Field
   @param value: int   - the value to set as note
   @return bool    - if successfull

◆ autoNotes()

None puzzle.Puzzle.autoNotes ( self )

Creates Notes for emtpy Fields automatically.

Foundation to solve puzzle with advanced strategies. NOTE: Old Notes will be overwritten!

Returns: None

◆ clearAllNotes()

None puzzle.Puzzle.clearAllNotes ( self )

clears all the notes for empty Fields.

NOTE: Non-Empty Fields do not have notes anyway

Returns: None

◆ clearNotes()

None puzzle.Puzzle.clearNotes	(		self,
		int	row,
		int	col
	)

Remove all the Notes from a Field.

   @param row: int - the row of a Field
   @param col: int - the column of a Field
   @return None

◆ clearValue()

bool puzzle.Puzzle.clearValue	(		self,
		int	row,
		int	col
	)

Clears a non-empty, non-fixed Field.

NOTE: Only way to unset a value from a Field, in other words to make it empty.

Parameters

row	int - the row of a Field
col	int - the column of a Field

Returns: bool - if successfull

◆ clone()

"Puzzle" puzzle.Puzzle.clone	(		cls,
		"Puzzle"	original
	)

New Puzzles - Functions.

(classmethod) Creates a new Puzzle with the attributes as the original Puzzle. Function uses Call-By-Value, so the Copy can be edited without changing the Original Usage: newPuzzle = Puzzle.clone(puzzleToCopy)

Parameters

original Puzzle - the puzzle to copy by value

Returns: Puzzle

◆ generateSolution()

"Puzzle" puzzle.Puzzle.generateSolution	(		cls,
		bool	verbose = `True`
	)

(classmethod) Creates an empty Puzzle and generates a Solution Fills the diagonal Blocks from top left to bottom right with random Digits (independent to each other).

Tries to fill the remaining blocks using recursion.

Returns: Puzzle - where all Fields have a valid value

◆ getBlock()

list[Field] puzzle.Puzzle.getBlock	(		self,
		*int	row,
		int	col
	)

Returns the block of the puzzle.

NOTE: kwargs required!

Parameters

row	int - the row
col	int - the column

Exceptions

IndexError - if (row,col) is not in grid

Returns: list[Field]

◆ getColumn()

list[Field] puzzle.Puzzle.getColumn	(		self,
		*int	col
	)

Returns a column of the puzzle.

NOTE: kwargs required!

Parameters

col	int - the column in question

Exceptions

IndexError - if col is not in grid

Returns: list[Field]

◆ getEmptyFields()

list[Field] puzzle.Puzzle.getEmptyFields	(		self,
		bool	sortByNotesLength = `False`
	)

Get specific Fields and other.

returns a list of empty Fields

Parameters

sortByNotesLength bool - if the list is sorted by the length of Notes per Field

Returns: list[Field] - if Field.isEmpty

◆ getField()

Field puzzle.Puzzle.getField	(		self,
		int	row,
		int	col
	)

Core Functions.

functions grant access to the grid with param validation use these core-function below the get the fields

Returns the Field from coordinates

   @param row: int - the row of the field
   @param col: int - the column of the field
   @exception IndexError   - if (row,col) is not in grid
   @return Field

◆ getFixedFields()

list[Field] puzzle.Puzzle.getFixedFields ( self )

Returns all the fixed Fields in a single list.

Returns: list[Field] - if Field.fixed

◆ getFlatGrid()

list[Field] puzzle.Puzzle.getFlatGrid ( self )

Returns the flat grid (flat copy) NOTE: Use this function, when iterating over full grid.

Returns: list[Field]

◆ getNonEmptyFields()

list[Field] puzzle.Puzzle.getNonEmptyFields ( self )

Returns all the non-empty Fields in a single list.

Returns: list[Field] - if not Field.isEmpty

◆ getNonFixedFields()

list[Field] puzzle.Puzzle.getNonFixedFields ( self )

Returns all the fixed Fields in a single list.

Returns: list[Field] - if not Field.fixed

◆ getRow()

list[Field] puzzle.Puzzle.getRow	(		self,
		*int	row
	)

Returns a row of the puzzle.

NOTE: kwargs required!

Parameters

row	int - the row in question

Exceptions

IndexError - if row is not in grid

Returns: list[Field]

◆ getValue()

int \| None puzzle.Puzzle.getValue	(		self,
		int	row,
		int	col
	)

Value-Functions.

Returns the value of Field. The value is the digit in the cell of a puzzle. NOTE: value can be None if Field is empty!

Parameters

row	int - the row of a Field
col	int - the column of a Field

Returns: int | None

◆ hasNoDuplicateValues()

bool puzzle.Puzzle.hasNoDuplicateValues ( self )

Checks for duplicate values in the puzzle regarding row, column and block.

NOTE: Should return True, otherwise there is a fundamental problem!

Returns: bool

◆ hasValidCandidates()

bool puzzle.Puzzle.hasValidCandidates ( self )

Check if one cell has no Candidates.

This would result in an unsolvable puzzle. NOTE: Should return True, otherwise there is a fundamental problem!

Returns: bool

◆ isFinished()

bool puzzle.Puzzle.isFinished ( self )

Properties.

(readonly property) indicates if Puzzle is solved

Returns: bool

◆ isValid()

bool puzzle.Puzzle.isValid ( self )

A puzzle is valid if there are no duplicate values in row, column and block and every cell has at least one candidate.

NOTE: Should return True, otherwise there is a fundamental problem!

Returns: bool

◆ isValidCell()

bool puzzle.Puzzle.isValidCell	(		self,
		int	row,
		int	col,
		int	value
	)

The standard sudoku rules - If value not in row, column or block, then True.

NOTE: The field defined by row and col will be ignored. NOTE: This does not necessarily checks for a correct solution move!!

Parameters

row	int - the row of the field
col	int - the column of the field
value	int - the value in question

Returns: bool - if rules violated or not

◆ iterGrid()

def puzzle.Puzzle.iterGrid ( self )

Generator over the grid.

◆ loadFromList()

"Puzzle" puzzle.Puzzle.loadFromList	(		cls,
		list[list[int \| None]]	grid
	)

(classmethod) Creates a Puzzle from a nested list.

NOTE: the Non-Empty values in the puzzle will be locked NOTE: accepts 0 and None as not-set-value

Parameters

grid	list[list[int \| None]]

Exceptions

ValueError	- if serialized has invalid values
Exception	- if the puzzle is not valid
IndexError	- if grid does not have the same dimension as a puzzle

Returns: Puzzle

◆ loadFromSerialized()

"Puzzle" puzzle.Puzzle.loadFromSerialized	(		cls,
		tuple[int \| None]	serialized
	)

(classmethod) Creates a Puzzle from a serialized tuple.

NOTE: the Non-Empty values in the puzzle will be locked NOTE: accepts 0 and None as not-set-value

Parameters

serialized tuple[int | None]

Exceptions

ValueError	- if serialized has invalid values
Exception	- if the puzzle is not valid
IndexError	- if serialized does not have the same length as a flat puzzle

Returns: Puzzle

◆ lockValues()

None puzzle.Puzzle.lockValues ( self )

Set all Non-Empty Fields to fixed, so they cannot be edited.

Usefull, if a solvable puzzle is found, so the initial grid cannot be edited. NOTE: This action cannot be undone

Returns: None

◆ removeNote()

bool puzzle.Puzzle.removeNote	(		self,
		int	row,
		int	col,
		int	value
	)

Removes a Note, if exists.

   @param row: int - the row of a Field
   @param col: int - the column of a Field
   @param value: int   - the value to set as note
   @return bool    - if successfull

◆ serialize()

tuple[int | None] puzzle.Puzzle.serialize ( self )

Serializes the puzzle as a tuple.

Usefull to compare two puzzles with each other.

Returns: set[list[int | None]]

◆ setValue()

bool puzzle.Puzzle.setValue	(		self,
		int	row,
		int	col,
		int	value
	)

Checks and sets the value.

The value is the digit in the cell of a puzzle. NOTE: Return True does not necessarily mean a correct solution move!!

Parameters

row	int - the row of a Field
col	int - the column of a Field
value	int - the value to set

Returns: bool - if not violating sudoku rules

◆ usedInBlock()

bool puzzle.Puzzle.usedInBlock	(		self,
		*int	row,
		int	col,
		int	value
	)

Checks if value exists in block.

NOTE: kwargs required!

Parameters

row	int - the row of a Field
col	int - the column of a Field
value	int - the value to check

Returns: bool - if exists or not

◆ usedInColumn()

bool puzzle.Puzzle.usedInColumn	(		self,
		*int	col,
		int	value
	)

checks if value exists in column.

NOTE: kwargs required!

Parameters

col	int - the column of a Field
value	int - the value to check

Returns: bool - if exists or not

◆ usedInRow()

bool puzzle.Puzzle.usedInRow	(		self,
		*int	row,
		int	value
	)

Row-, Column-, Block-Functions.

Checks if value exists in row. NOTE: kwargs required!

Parameters

row	int - the row of a Field
value	int - the value to check

Returns: bool - if exists or not

The documentation for this class was generated from the following file:

puzzle.py

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ __repr__()

◆ __str__()

◆ addNote()

◆ autoNotes()

◆ clearAllNotes()

◆ clearNotes()

◆ clearValue()

◆ clone()

◆ generateSolution()

◆ getBlock()

◆ getColumn()

◆ getEmptyFields()

◆ getField()

◆ getFixedFields()

◆ getFlatGrid()

◆ getNonEmptyFields()

◆ getNonFixedFields()

◆ getRow()

◆ getValue()

◆ hasNoDuplicateValues()

◆ hasValidCandidates()

◆ isFinished()

◆ isValid()

◆ isValidCell()

◆ iterGrid()

◆ loadFromList()

◆ loadFromSerialized()

◆ lockValues()

◆ removeNote()

◆ serialize()

◆ setValue()

◆ usedInBlock()

◆ usedInColumn()

◆ usedInRow()

◆ init()

◆ repr()

◆ str()