import语句放在模块顶部会触发循环导入，因为python自上而下执行模块体，a.py顶部import b时若b.py也顶部import a，会导致a处于“正在初始化但未完成”的中间态而报错。
为什么import语句放在模块顶部会触发循环导入？
Python在导入模块时是自上而下执行模块体的。如果A.py顶部import B，而B.py顶部又import A，解释器会在A未定义完时就跳进B，B又回头找A——此时A处于“正在初始化但未完成”的中间态，抛出ImportError: cannot import name 'X' from partially initialized module 'A'。
常见诱因包括：
- 把
from A import func写在B.py最上面，而A.py里又反过来引用B里的类 - 用
<strong>init</strong>.py做聚合导入（如from .a import X; from .b import Y），而a和b互相依赖
把import挪到函数/方法内部能解决问题吗？
能，而且是最轻量、最安全的解法之一。只要不执行到那行代码，就不会触发导入。
适用场景：
- 工具函数只在特定路径下才用到另一个模块（比如错误处理时才需
logging配置） - 类方法中需要调用另一模块的构造器或工具（如
def to_dict(self): from json import dumps; return dumps(self.<strong>dict</strong>)）
注意点：
- 不能用于模块级变量赋值（
CONFIG = require('config')这种不行） - 频繁调用的函数里反复
import会有轻微开销，但一般可忽略 - IDE可能无法静态推导类型，需加
# type: ignore或用typing.TYPE_CHECKING配合
用typing.TYPE_CHECKING做前向声明够用吗？
够用，但仅限类型提示场景。它不会真正导入模块，只是让类型检查器（mypy/pyright）知道名字存在。
python-docx Skill功能概述python-docx Skill是一项面向实际任务的技能，主要用于本Skill提供使用python-docx生成专业Word文档的标准方法和最佳实践；生成安全服务方案文档；核心要点生成技术架构设计文档；生成任何需要专业排版的Word文档；核心库 : python-docx；使用与执行辅助库 : docx.shared , docx.enum , docx.oxml.ns；标准代码模板；1. 文档初始化；2. 字体设置（必须！它将相关步骤、工具调用和结果整理方式集
典型写法：
from typing import TYPE_CHECKING <p>if TYPE_CHECKING: from .models import User</p><p>def get_user_by_id(id: int) -> "User": # 字符串字面量避免运行时解析 ... </p>
关键约束：
-
TYPE_CHECKING只在静态检查时为True，运行时不生效 - 返回值/参数类型必须用字符串（如
"User"），否则运行时报NameError - 不能解决运行时的实例创建、函数调用等真实依赖
重构模块职责才是根治办法
循环导入本质是设计问题：两个模块耦合太紧，职责没切分清楚。
可行方向：
- 提取公共逻辑到第三个模块（如
core/utils.py），A和B都只依赖它 - 将被频繁交叉引用的类/函数上提到父包层级（比如A和B同属
package/，把共享接口放package/<strong>init</strong>.py或package/interfaces.py） - 用协议（
Protocol）或抽象基类替代具体类型依赖，降低硬引用
最容易被忽略的一点：循环导入常伴随“模块变大后才暴露”。一开始A和B都很小，互相引用没问题；等B加了数据库操作、A加了API序列化，导入链变长，就突然崩。所以别等报错再动，看到from . import X和from .. import Y交错出现，就该停下来画个依赖图。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
