如何解决复杂Python项目结构中的循环导入错误？

我在开发一个Python国际象棋项目时，为了合理规划结构、避免所有类堆在同一个文件里拆分了模块，结果触发了循环导入的ImportError。希望能在保留现有项目结构的前提下解决这个问题。

项目结构 #

• main.py
• src（已标记为Sources Root）
  • chess
    • init.py
    • board.py
    • chess_class.py
    • pieces（目录）
      • init.py
      • piece_base.py
      • pieces_classes.py

各文件代码 #

main.py

from chess import Chess

if __name__ == "__main__":
    Chess().play()

src/chess/init.py

from .chess_class import Chess

src/chess/board.py

from .pieces import *

class Board:
    ...

src/chess/chess_class.py

from .board import Board

class Chess:
    def play(self):
        print("hi")

src/chess/pieces/init.py

from .pieces_classes import Queen, Rook

src/chess/pieces/piece_base.py

from ..board import Board

class Piece:
    """Base class for all pieces."""
    ...

src/chess/pieces/pieces_classes.py

from .piece_base import Piece
from ..board import Board

class Queen(Piece):
    ...

class Rook(Piece):
    ...

报错情况 #

运行main.py时触发导入错误，导入顺序如下：

1. from chess import Chess
2. from .chess_class import Chess
3. from .board import Board
4. from .pieces import *
5. from .pieces_classes import Queen, Rook
6. from .piece_base import Piece
7. from ..board import Board

报错信息：

ImportError: cannot import name Board from partially initialized module chess.board        (most likely due to a circular import)

我试过在piece_base.py和pieces_classes.py中导入整个board模块（import chess.board）但无效；网上建议的类内部导入方案又担心影响性能，合并类到同一文件的方案也不符合我保留现有结构的需求。

解决方案 #

这个问题本质是设计层面的问题：棋子类根本不需要导入Board类——跟踪棋盘状态是Board的职责，而非棋子的职责。只需要移除piece_base.py和pieces_classes.py中对Board的导入，就能彻底解决循环导入错误，同时也符合代码职责分离的设计原则。

内容的提问来源于stack exchange，提问作者Vladislav Ryzhikh