dedoku 0.3.0__py3-none-any.whl

dedoku/__init__.py

@@ -0,0 +1,38 @@
+"""A pure-Python Sudoku solver based on human-style logical deduction.
+
+The package exposes an object-oriented board model (:class:`Cell`,
+:class:`Row`, :class:`Column`, :class:`Subgrid`, :class:`Grid`) and a
+logic-only solving engine (:class:`SudokuSolver`) that never resorts to
+backtracking. It has no external dependencies.
+
+Individual techniques live in :mod:`dedoku.techniques`.
+"""
+
+from __future__ import annotations
+
+from .cell import DIGITS, Cell
+from .exceptions import ContradictionError, InvalidGridError, SudokuError
+from .grid import Grid
+from .solver import SolveResult, SudokuSolver
+from .techniques import Step, Technique
+from .units import Column, Row, Subgrid, Unit
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "DIGITS",
+    "Cell",
+    "Column",
+    "ContradictionError",
+    "Grid",
+    "InvalidGridError",
+    "Row",
+    "SolveResult",
+    "Step",
+    "Subgrid",
+    "SudokuError",
+    "SudokuSolver",
+    "Technique",
+    "Unit",
+    "__version__",
+]

dedoku/cell.py

@@ -0,0 +1,306 @@
+"""Cell model for the Sudoku board.
+
+This module defines :class:`Cell`, the smallest building block of a Sudoku
+grid. A cell knows its position, its solved value (if any), its remaining
+candidate digits, and holds references to the three houses it belongs to:
+its :class:`~dedoku.units.Row`, :class:`~dedoku.units.Column`,
+and :class:`~dedoku.units.Subgrid`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .exceptions import ContradictionError
+
+if TYPE_CHECKING:
+    from .units import Column, Row, Subgrid
+
+__all__ = ["DIGITS", "Cell"]
+
+DIGITS: frozenset[int] = frozenset(range(1, 10))
+"""frozenset[int]: The nine digits a Sudoku cell may contain."""
+
+
+class Cell:
+    """A single cell of a 9x9 Sudoku grid.
+
+    A cell starts unsolved with all nine digits as candidates. Placing a
+    value with :meth:`set_value` automatically removes that digit from the
+    candidates of every peer (the cells sharing a row, column, or subgrid).
+
+    :param row_index: Zero-based index of the row the cell lies in (0-8).
+    :type row_index: int
+    :param column_index: Zero-based index of the column the cell lies in (0-8).
+    :type column_index: int
+    :raises ValueError: If either index is outside the 0-8 range.
+    """
+
+    __slots__ = ("_row_index", "_column_index", "_value", "_candidates",
+                 "_row", "_column", "_subgrid", "_is_given",
+                 "_peers_cache", "_candidates_view")
+
+    def __init__(self, row_index: int, column_index: int) -> None:
+        if row_index not in range(9) or column_index not in range(9):
+            raise ValueError(
+                f"cell position must be within 0-8, "
+                f"got ({row_index}, {column_index})"
+            )
+        self._row_index = row_index
+        self._column_index = column_index
+        self._value: int | None = None
+        self._candidates: set[int] = set(DIGITS)
+        self._row: Row | None = None
+        self._column: Column | None = None
+        self._subgrid: Subgrid | None = None
+        self._is_given = False
+        self._peers_cache: tuple[Cell, ...] | None = None
+        self._candidates_view: frozenset[int] | None = None
+
+    # ------------------------------------------------------------------
+    # Wiring
+    # ------------------------------------------------------------------
+    def attach(self, row: Row, column: Column, subgrid: Subgrid) -> None:
+        """Wire the cell to its three houses and register it with each.
+
+        This is called once by :class:`~dedoku.grid.Grid` while the
+        board is being built and must not be called again afterwards.
+
+        :param row: The row the cell belongs to.
+        :type row: Row
+        :param column: The column the cell belongs to.
+        :type column: Column
+        :param subgrid: The 3x3 subgrid the cell belongs to.
+        :type subgrid: Subgrid
+        :raises RuntimeError: If the cell is already attached.
+        """
+        if self._row is not None:
+            raise RuntimeError(f"cell {self.label} is already attached")
+        self._row = row
+        self._column = column
+        self._subgrid = subgrid
+        for unit in (row, column, subgrid):
+            unit.register(self)
+
+    # ------------------------------------------------------------------
+    # Read-only state
+    # ------------------------------------------------------------------
+    @property
+    def row_index(self) -> int:
+        """int: Zero-based index of the cell's row."""
+        return self._row_index
+
+    @property
+    def column_index(self) -> int:
+        """int: Zero-based index of the cell's column."""
+        return self._column_index
+
+    @property
+    def position(self) -> tuple[int, int]:
+        """tuple[int, int]: The ``(row_index, column_index)`` pair."""
+        return (self._row_index, self._column_index)
+
+    @property
+    def label(self) -> str:
+        """str: Human-readable, one-based position label such as ``R4C7``."""
+        return f"R{self._row_index + 1}C{self._column_index + 1}"
+
+    @property
+    def row(self) -> Row:
+        """Row: The row the cell belongs to.
+
+        :raises RuntimeError: If the cell has not been attached to a grid.
+        """
+        if self._row is None:
+            raise RuntimeError(f"cell {self.label} is not attached to a grid")
+        return self._row
+
+    @property
+    def column(self) -> Column:
+        """Column: The column the cell belongs to.
+
+        :raises RuntimeError: If the cell has not been attached to a grid.
+        """
+        if self._column is None:
+            raise RuntimeError(f"cell {self.label} is not attached to a grid")
+        return self._column
+
+    @property
+    def subgrid(self) -> Subgrid:
+        """Subgrid: The 3x3 subgrid the cell belongs to.
+
+        :raises RuntimeError: If the cell has not been attached to a grid.
+        """
+        if self._subgrid is None:
+            raise RuntimeError(f"cell {self.label} is not attached to a grid")
+        return self._subgrid
+
+    @property
+    def value(self) -> int | None:
+        """int | None: The solved digit, or ``None`` while unsolved."""
+        return self._value
+
+    @property
+    def candidates(self) -> frozenset[int]:
+        """frozenset[int]: Immutable view of the remaining candidates.
+
+        A solved cell exposes an empty set. The view is cached between
+        mutations, so repeated reads are cheap.
+        """
+        if self._candidates_view is None:
+            self._candidates_view = frozenset(self._candidates)
+        return self._candidates_view
+
+    @property
+    def is_solved(self) -> bool:
+        """bool: Whether the cell holds a definitive value."""
+        return self._value is not None
+
+    @property
+    def is_given(self) -> bool:
+        """bool: Whether the value was part of the original puzzle.
+
+        Uniqueness-based techniques (such as avoidable rectangles) must
+        distinguish clues supplied by the puzzle from values deduced
+        during solving.
+        """
+        return self._is_given
+
+    @property
+    def is_bivalue(self) -> bool:
+        """bool: Whether the cell is unsolved with exactly two candidates.
+
+        Bivalue cells are the anchors of several advanced techniques
+        (remote pairs, W-Wing, Y-Wing, BUG, ...).
+        """
+        return self._value is None and len(self._candidates) == 2
+
+    @property
+    def peers(self) -> tuple[Cell, ...]:
+        """tuple[Cell, ...]: The 20 distinct cells sharing a house with this one.
+
+        Peers are returned sorted by position for deterministic iteration
+        and cached after the first access, since the wiring never changes.
+
+        :raises RuntimeError: If the cell has not been attached to a grid.
+        """
+        if self._peers_cache is None:
+            seen: dict[int, Cell] = {}
+            for unit in (self.row, self.column, self.subgrid):
+                for cell in unit.cells:
+                    if cell is not self:
+                        seen[id(cell)] = cell
+            self._peers_cache = tuple(
+                sorted(seen.values(), key=lambda cell: cell.position)
+            )
+        return self._peers_cache
+
+    def sees(self, other: Cell) -> bool:
+        """Report whether ``other`` shares a house with this cell.
+
+        A cell never sees itself.
+
+        :param other: The cell to test against.
+        :type other: Cell
+        :returns: ``True`` if the two cells share a row, column, or
+            subgrid.
+        :rtype: bool
+        """
+        return other is not self and (
+            self._row_index == other.row_index
+            or self._column_index == other.column_index
+            or self.subgrid.index == other.subgrid.index
+        )
+
+    # ------------------------------------------------------------------
+    # Mutation
+    # ------------------------------------------------------------------
+    def set_value(self, digit: int) -> None:
+        """Solve the cell with ``digit`` and propagate to all peers.
+
+        The digit is removed from the candidates of every peer, which may
+        in turn reveal a contradiction elsewhere on the board.
+
+        :param digit: The digit to place, between 1 and 9.
+        :type digit: int
+        :raises ValueError: If ``digit`` is not a digit between 1 and 9,
+            or the cell is already solved.
+        :raises ContradictionError: If ``digit`` is not among the cell's
+            candidates, or placing it strips the last candidate from an
+            unsolved peer.
+        """
+        _validate_digit(digit)
+        if self._value is not None:
+            raise ValueError(
+                f"cell {self.label} is already solved with {self._value}"
+            )
+        if digit not in self._candidates:
+            raise ContradictionError(
+                f"digit {digit} is not a candidate of cell {self.label}"
+            )
+        self._value = digit
+        self._candidates.clear()
+        self._candidates_view = None
+        for peer in self.peers:
+            peer.remove_candidate(digit)
+
+    def mark_as_given(self) -> None:
+        """Flag the cell's value as an original clue of the puzzle.
+
+        This is called by :meth:`dedoku.grid.Grid.from_string`
+        right after each given is placed.
+
+        :raises ValueError: If the cell has no value yet.
+        """
+        if self._value is None:
+            raise ValueError(
+                f"cell {self.label} is unsolved and cannot be a given"
+            )
+        self._is_given = True
+
+    def remove_candidate(self, digit: int) -> bool:
+        """Eliminate ``digit`` from the cell's candidates.
+
+        Removing a candidate from a solved cell, or a digit that is already
+        absent, is a harmless no-op.
+
+        :param digit: The digit to eliminate, between 1 and 9.
+        :type digit: int
+        :returns: ``True`` if the candidate was present and got removed.
+        :rtype: bool
+        :raises ValueError: If ``digit`` is not a digit between 1 and 9.
+        :raises ContradictionError: If the removal leaves an unsolved cell
+            with no candidates at all.
+        """
+        _validate_digit(digit)
+        if self._value is not None or digit not in self._candidates:
+            return False
+        self._candidates.discard(digit)
+        self._candidates_view = None
+        if not self._candidates:
+            raise ContradictionError(
+                f"cell {self.label} has no candidates left"
+            )
+        return True
+
+    def __repr__(self) -> str:
+        """Return a debugging representation of the cell.
+
+        :returns: A string such as ``<Cell R1C1 value=5>`` or
+            ``<Cell R1C2 candidates={1, 2}>``.
+        :rtype: str
+        """
+        if self._value is not None:
+            return f"<Cell {self.label} value={self._value}>"
+        return f"<Cell {self.label} candidates={sorted(self._candidates)}>"
+
+
+def _validate_digit(digit: int) -> None:
+    """Ensure ``digit`` is an integer between 1 and 9.
+
+    :param digit: The value to validate.
+    :type digit: int
+    :raises ValueError: If ``digit`` is not a valid Sudoku digit.
+    """
+    if not isinstance(digit, int) or digit not in DIGITS:
+        raise ValueError(f"digit must be an integer between 1 and 9, got {digit!r}")

dedoku/exceptions.py

@@ -0,0 +1,31 @@
+"""Exception hierarchy for the :mod:`dedoku` package.
+
+All exceptions raised by this library derive from :class:`SudokuError`,
+so callers can catch a single base class to handle any library failure.
+"""
+
+from __future__ import annotations
+
+__all__ = ["SudokuError", "InvalidGridError", "ContradictionError"]
+
+
+class SudokuError(Exception):
+    """Base class for every exception raised by :mod:`dedoku`."""
+
+
+class InvalidGridError(SudokuError):
+    """Raised when a puzzle description cannot be turned into a valid grid.
+
+    Typical causes are a wrong number of cells, characters outside the
+    accepted alphabet, or givens that immediately contradict each other
+    (for example two identical digits in the same row).
+    """
+
+
+class ContradictionError(SudokuError):
+    """Raised when the board reaches a logically impossible state.
+
+    This happens when an unsolved cell loses its last candidate or a digit
+    has no remaining home inside a unit. During solving it means the puzzle
+    (or the technique that produced the state) is inconsistent.
+    """

dedoku/grid.py

@@ -0,0 +1,229 @@
+"""The full 9x9 Sudoku board.
+
+:class:`Grid` builds the 81 :class:`~dedoku.cell.Cell` objects, wires
+each of them to its :class:`~dedoku.units.Row`,
+:class:`~dedoku.units.Column`, and
+:class:`~dedoku.units.Subgrid`, and offers parsing and serialisation
+helpers.
+"""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from .cell import Cell
+from .exceptions import ContradictionError, InvalidGridError
+from .units import Column, Row, Subgrid, Unit
+
+__all__ = ["Grid"]
+
+_EMPTY_CHARS = ".0"
+_IGNORED_CHARS = " \t\r\n|+-"
+
+
+class Grid:
+    """A 9x9 Sudoku board made of cells, rows, columns, and subgrids.
+
+    A freshly constructed grid is empty: every cell is unsolved with all
+    nine candidates. Use :meth:`from_string` to load a puzzle.
+    """
+
+    def __init__(self) -> None:
+        self._rows: tuple[Row, ...] = tuple(Row(i) for i in range(9))
+        self._columns: tuple[Column, ...] = tuple(Column(i) for i in range(9))
+        self._subgrids: tuple[Subgrid, ...] = tuple(Subgrid(i) for i in range(9))
+        cells: list[Cell] = []
+        for row_index in range(9):
+            for column_index in range(9):
+                cell = Cell(row_index, column_index)
+                cell.attach(
+                    self._rows[row_index],
+                    self._columns[column_index],
+                    self._subgrids[self.subgrid_index(row_index, column_index)],
+                )
+                cells.append(cell)
+        self._cells: tuple[Cell, ...] = tuple(cells)
+        self._units: tuple[Unit, ...] = (
+            self._rows + self._columns + self._subgrids
+        )
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_string(cls, text: str) -> Grid:
+        """Build a grid from an 81-character puzzle description.
+
+        Cells are read left to right, top to bottom. Digits ``1``-``9``
+        are givens, while ``0`` and ``.`` mark empty cells. Whitespace and
+        the decoration characters ``|``, ``+``, ``-`` are ignored, so the
+        output of :meth:`__str__` can be parsed back.
+
+        :param text: The puzzle description.
+        :type text: str
+        :returns: A grid with all givens placed and candidates propagated.
+        :rtype: Grid
+        :raises InvalidGridError: If the description does not contain
+            exactly 81 cells, uses unexpected characters, or its givens
+            contradict each other.
+        """
+        symbols: list[str] = []
+        for char in text:
+            if char in _IGNORED_CHARS:
+                continue
+            if char.isdigit() or char in _EMPTY_CHARS:
+                symbols.append(char)
+            else:
+                raise InvalidGridError(
+                    f"unexpected character {char!r} in puzzle description"
+                )
+        if len(symbols) != 81:
+            raise InvalidGridError(
+                f"puzzle must describe 81 cells, got {len(symbols)}"
+            )
+        grid = cls()
+        for position, symbol in enumerate(symbols):
+            if symbol in _EMPTY_CHARS:
+                continue
+            try:
+                grid._cells[position].set_value(int(symbol))
+            except ContradictionError as exc:
+                raise InvalidGridError(
+                    f"the givens contradict each other: {exc}"
+                ) from exc
+            grid._cells[position].mark_as_given()
+        return grid
+
+    # ------------------------------------------------------------------
+    # Geometry helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def subgrid_index(row_index: int, column_index: int) -> int:
+        """Return the subgrid index covering the given board position.
+
+        :param row_index: Zero-based row index (0-8).
+        :type row_index: int
+        :param column_index: Zero-based column index (0-8).
+        :type column_index: int
+        :returns: The zero-based subgrid index (0-8).
+        :rtype: int
+        """
+        return (row_index // 3) * 3 + column_index // 3
+
+    def cell(self, row_index: int, column_index: int) -> Cell:
+        """Return the cell at the given board position.
+
+        :param row_index: Zero-based row index (0-8).
+        :type row_index: int
+        :param column_index: Zero-based column index (0-8).
+        :type column_index: int
+        :returns: The requested cell.
+        :rtype: Cell
+        :raises ValueError: If either index is outside the 0-8 range.
+        """
+        if row_index not in range(9) or column_index not in range(9):
+            raise ValueError(
+                f"cell position must be within 0-8, "
+                f"got ({row_index}, {column_index})"
+            )
+        return self._cells[row_index * 9 + column_index]
+
+    # ------------------------------------------------------------------
+    # Collections
+    # ------------------------------------------------------------------
+    @property
+    def cells(self) -> tuple[Cell, ...]:
+        """tuple[Cell, ...]: All 81 cells, left to right, top to bottom."""
+        return self._cells
+
+    @property
+    def rows(self) -> tuple[Row, ...]:
+        """tuple[Row, ...]: The nine rows, top to bottom."""
+        return self._rows
+
+    @property
+    def columns(self) -> tuple[Column, ...]:
+        """tuple[Column, ...]: The nine columns, left to right."""
+        return self._columns
+
+    @property
+    def subgrids(self) -> tuple[Subgrid, ...]:
+        """tuple[Subgrid, ...]: The nine subgrids, left to right, top to bottom."""
+        return self._subgrids
+
+    @property
+    def units(self) -> tuple[Unit, ...]:
+        """tuple[Unit, ...]: All 27 houses: rows, then columns, then subgrids."""
+        return self._units
+
+    def __iter__(self) -> Iterator[Cell]:
+        """Iterate over all 81 cells in board order.
+
+        :returns: An iterator over the grid's cells.
+        :rtype: Iterator[Cell]
+        """
+        return iter(self._cells)
+
+    # ------------------------------------------------------------------
+    # Board state
+    # ------------------------------------------------------------------
+    def is_solved(self) -> bool:
+        """Check whether every cell holds a value and the board is valid.
+
+        :returns: ``True`` if the puzzle is completely and correctly solved.
+        :rtype: bool
+        """
+        return all(cell.is_solved for cell in self._cells) and self.is_valid()
+
+    def is_valid(self) -> bool:
+        """Check that no house contains a duplicated solved digit.
+
+        :returns: ``True`` if every row, column, and subgrid is valid.
+        :rtype: bool
+        """
+        return all(unit.is_valid() for unit in self.units)
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+    def to_string(self, empty: str = ".") -> str:
+        """Serialise the board to an 81-character single-line string.
+
+        :param empty: The character used for unsolved cells.
+        :type empty: str
+        :returns: The board, left to right, top to bottom.
+        :rtype: str
+        """
+        return "".join(
+            str(cell.value) if cell.is_solved else empty for cell in self._cells
+        )
+
+    def __str__(self) -> str:
+        """Render the board as a human-readable 9x9 diagram.
+
+        :returns: A pretty-printed board with subgrid separators.
+        :rtype: str
+        """
+        lines: list[str] = []
+        for row_index, row in enumerate(self._rows):
+            if row_index in (3, 6):
+                lines.append("------+-------+------")
+            chunks = []
+            for start in range(0, 9, 3):
+                chunks.append(
+                    " ".join(
+                        str(cell.value) if cell.is_solved else "."
+                        for cell in row.cells[start:start + 3]
+                    )
+                )
+            lines.append(" | ".join(chunks))
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        """Return a debugging representation of the grid.
+
+        :returns: A string reporting how many cells are solved.
+        :rtype: str
+        """
+        solved = sum(1 for cell in self._cells if cell.is_solved)
+        return f"<Grid {solved}/81 solved>"