本文介绍如何通过继承 collections.abc.MutableSequence 构建一个类型安全、规则校验完备的 9×9 数独数组类 SudokuArray，支持坐标索引、自动冲突检测与人性化输出，完全基于标准库，零外部依赖。
本文介绍如何通过继承 `collections.abc.mutablesequence` 构建一个类型安全、规则校验完备的 9×9 数独数组类 `sudokuarray`，支持坐标索引、自动冲突检测与人性化输出，完全基于标准库，零外部依赖。
在开发轻量级数独游戏或逻辑验证工具时，我们常需要一个既能按行列访问、又能实时校验数字唯一性的二维容器。虽然 numpy.array 功能强大，但对于固定尺寸（如标准 9×9）、强业务约束（行/列/宫内无重复）的场景，自定义类反而更清晰、可控且无依赖。本教程将带你从零构建 SudokuArray 类——它不是简单二维列表的封装，而是真正遵循 MutableSequence 协议、具备完整语义和 Sudoku 逻辑校验的专业实现。
✅ 核心设计原则
- 协议合规：严格实现 MutableSequence 所需的 5 个抽象方法（__len__, __getitem__, __setitem__, __delitem__, insert），确保与 Python 内置序列操作兼容。
- 坐标即索引：__getitem__、__setitem__ 等接收单个参数（如 (row, col) 元组），而非两个独立参数，符合 Python 序列协议规范。
- 尺寸统一化：Sudoku 必为 n×n 方阵（n=9），故构造函数仅需 size 参数，避免冗余配置。
- 规则内嵌校验：__setitem__ 自动调用 check()，确保填入数字不违反行、列、3×3 宫（nonet）唯一性约束。
? 关键代码实现
from collections.abc import MutableSequence
from math import isqrt
class ExistentNumberError(Exception):
def __init__(self, message, number, row, col):
super().__init__(message)
self.number = number
self.row = row
self.col = col
class SudokuArray(MutableSequence):
def __init__(self, size=9, init_value=None):
if size <= 0 or isqrt(size) ** 2 != size:
raise ValueError("size must be a perfect square (e.g., 4, 9, 16)")
self.size = size
self.array = [[init_value for _ in range(size)] for _ in range(size)]
def check(self, row, col, number):
if (number in self.get_row_values(row) or
number in self.get_column_values(col) or
number in self.get_nonet_values(row, col)):
raise ExistentNumberError(
f"Number {number} already exists in row {row}, column {col}, or its 3×3 block",
number, row, col
)
def __len__(self):
return self.size * self.size # total cells, required by MutableSequence
def __getitem__(self, coords):
row, col = coords
if not (0 <= row < self.size and 0 <= col < self.size):
raise IndexError(f"Index {coords} out of bounds for {self.size}×{self.size} grid")
return self.array[row][col]
def __setitem__(self, coords, value):
row, col = coords
if not (0 <= row < self.size and 0 <= col < self.size):
raise IndexError(f"Index {coords} out of bounds for {self.size}×{self.size} grid")
self.check(row, col, value)
self.array[row][col] = value
def __delitem__(self, coords):
row, col = coords
self.array[row][col] = None # logical deletion; preserves grid structure
def insert(self, index, value):
# Not meaningful for fixed-grid Sudoku — but required by MutableSequence
# We interpret `index` as (row, col) and delegate to __setitem__
if isinstance(index, tuple) and len(index) == 2:
self.__setitem__(index, value)
else:
raise TypeError("insert() expects a (row, col) tuple")
def __str__(self):
# Pretty-print: replace None with '.' for readability
lines = []
for row in self.array:
line = " ".join(str(x) if x is not None else "." for x in row)
lines.append(line)
return "\n".join(lines)
def get_row_values(self, row):
return [x for x in self.array[row] if x is not None]
def get_column_values(self, col):
return [self.array[r][col] for r in range(self.size) if self.array[r][col] is not None]
def get_nonet_values(self, row, col):
width = isqrt(self.size) # e.g., 3 for 9×9
top = (row // width) * width
left = (col // width) * width
values = []
for r in range(top, top + width):
for c in range(left, left + width):
if self.array[r][c] is not None:
values.append(self.array[r][c])
return values? 使用示例与注意事项
# 初始化空数独板（9×9，默认值为 None）
sudoku = SudokuArray()
# 安全赋值：支持元组索引
sudoku[0, 0] = 5
sudoku[1, 2] = 7
sudoku[8, 8] = 1
# 尝试违反规则 → 抛出 ExistentNumberError
try:
sudoku[0, 1] = 5 # 同行重复 → 失败
except ExistentNumberError as e:
print(e) # 输出：Number 5 already exists in row 0, column 1, or its 3×3 block
# 友好打印
print(sudoku)
# 输出示例：
# 5 . . . . . . . .
# . . 7 . . . . . .
# . . . . . . . . .
# ...⚠️ 重要注意事项：
- __delitem__ 在 Sudoku 场景中语义应为“清空格子”（设为 None），而非物理删除元素（会破坏网格结构），因此我们覆盖其行为以保持矩阵完整性。
- insert() 方法虽被协议要求实现，但对固定尺寸数独无实际意义；此处将其重定向为 __setitem__ 的别名，避免误用。
- get_*_values() 方法自动过滤 None，确保校验仅基于已填数字。
- 构造时校验 size 是否为完全平方数（如 4、9、16），保障 nonet 划分有效性。
通过此实现，你获得了一个兼具 Python 序列协议兼容性、Sudoku 业务逻辑内聚性与调试友好性的专业工具类——无需 NumPy，不牺牲健壮性，是教学、原型开发与轻量游戏引擎的理想选择。
