# queens.py

#

# ICS $33$ Winter $2024$

# Project $0$: History of Modern

#

# A module containing tools that could assist in solving variants of the

# well$-$known $"$n$-$queens" problem. Note that we're only implementing one part

# of the problem: immutably managing the "state" of the board $($i$.$e$.,$ which

# queens are arranged in which cells$).$ The rest of the problem $--$ determining

# a valid solution for it $--$ is not our focus here.

#

# Your goal is to complete the QueensState class described below, though

# you'll need to build it incrementally, as well as test it incrementally by

# writing unit tests in test$\_$queens.py$.$ Make sure you've read the project

# write$-$up before you proceed, as it will explain the requirements around

# following $($and documenting$)$ an incremental process of solving this problem.

#

# DO NOT MODIFY THE Position NAMEDTUPLE OR THE PROVIDED EXCEPTION CLASSES.

from collections import namedtuple

from typing import Self

Position $=$ namedtuple$(\text{'}$Position$\text{'},[\text{'}$row$\text{'},$ 'column'$])$

# Ordinarily, we would write docstrings within classes or their methods.

# Since a namedtuple builds those classes and methods for us$,$ we instead

# add the documentation by hand afterward.

Position.$\_\_$doc$\_\_=$ 'A position on a chessboard, specified by zero$-$based row and column numbers.$\text{'}$

Position.row.$\_\_$doc$\_\_=$ 'A zero$-$based row number'

Position.column.$\_\_$doc$\_\_=$ 'A zero$-$based column number'

class DuplicateQueenError$($Exception$)$:

$"""$An exception indicating an attempt to add a queen where one is already present."""

def $\_\_$init$\_\_($self$,$ position: Position$)$:

$"""$Initializes the exception, given a position where the duplicate queen exists."""

self.$\_$position $=$ position

def $\_\_$str$\_\_($self$)->$ str:

return f'duplicate queen in row $\{$self$.\_$position.row$\}$ column $\{$self$.\_$position.column$\}\text{'}$

class MissingQueenError$($Exception$)$:

$"""$An exception indicating an attempt to remove a queen where one is not present."""

def $\_\_$init$\_\_($self$,$ position: Position$)$:

$"""$Initializes the exception, given a position where a queen is missing."""

self.$\_$position $=$ position

def $\_\_$str$\_\_($self$)->$ str:

return f'missing queen in row $\{$self$.\_$position.row$\}$ column $\{$self$.\_$position.column$\}\text{'}$

class QueensState:

$"""$Immutably represents the state of a chessboard being used to assist in

solving the n$-$queens problem."""

def $\_\_$init$\_\_($self$,$ rows: int, columns: int$)$:

$"""$Initializes the chessboard to have the given numbers of rows and columns,

with no queens occupying any of its cells."""

pass

def queen$\_$count$($self$)->$ int:

$"""$Returns the number of queens on the chessboard."""

pass

def queens$($self$)->$ list$[$Position$]$:

$"""$Returns a list of the positions in which queens appear on the chessboard,

arranged in no particular order."""

pass

def has$\_$queen$($self$,$ position: Position$)->$ bool:

$"""$Returns True if a queen occupies the given position on the chessboard, or

False otherwise."""

pass

def any$\_$queens$\_$unsafe$($self$)->$ bool:

$"""$Returns True if any queens on the chessboard are unsafe $($i$.$e$.,$ they can

be captured by at least one other queen on the chessboard$),$ or False otherwise."""

pass

def with$\_$queens$\_$added$($self$,$ positions: list$[$Position$])->$ Self:

$"""$Builds a new QueensState with queens added in the given positions.

Raises a DuplicateQueenException when there is already a queen in at

least one of the given positions."""

pass

def with$\_$queens$\_$removed$($self$,$ positions: list$[$Position$])->$ Self:

$"""$Builds a new QueensState with queens removed from the given positions.

Raises a MissingQueenException when there is no queen in at least one of

the given positions."""

pass