拆分Python代码时为何持续出现循环导入引发的AttributeError？

问题场景 #

拆分代码到多个文件时，持续出现AttributeError，提示大概率是循环导入问题，目标是在distances.py中编写函数并在main.py中调用。

main.py 代码 #

from tkinter import *
from tkinter import ttk
import distances as dc

root = Tk()
root.geometry("500x300")
root.title("UnitConverter - Main Menu")

global headLabel
headLabel = Label(master=root, text="UnitConverter", font=("Aptos Semibold", 20))
headLabel.pack()

global subLabel
subLabel = Label(master=root,text="Select what you would like to convert:",
                 font=("Aptos SemiBold", 15))
subLabel.pack()

buttons=[
    {"text": "Distances", "x": 50, "y": 100, "command": dc.distance_cmd},
    {"text": "Weights", "x": 209, "y": 100},
    {"text": "Fluids", "x": 360, "y": 100},
    {"text": "Currencies", "x": 50, "y": 200},
    {"text": "Time", "x": 209, "y": 200}
]

buttonStyle = ttk.Style()
buttonStyle.configure("my.TButton", font=("Aptos SemiBold", 13))

for button_info in buttons:
    button = ttk.Button(root, text=button_info["text"], style="my.TButton",
                        command=button_info["command"])
    button.place(x=button_info["x"], y=button_info["y"])

root.mainloop()

def hideButtons():
    for button_info in buttons:
        button.place_forget()

distances.py 代码 #

import main_copy as mc

def distance_cmd():
    mc.root.title("UnitConverter - Distances")

报错信息 #

Traceback (most recent call last):
  File "c:\Users\simon\OneDrive\Documents\Programming\Distance Converter\main_copy.py", line 3, in <module>
    import distances as dc
  File "c:\Users\simon\OneDrive\Documents\Programming\Distance Converter\distances.py", line 1, in <module>
    import main_copy as mc
  File "c:\Users\simon\OneDrive\Documents\Programming\Distance Converter\main_copy.py", line 19, in <module>
    {"text": "Distances", "x": 50, "y": 100, "command": dc.distance_cmd},
AttributeError: partially initialized module 'distances' has no attribute 'distance_cmd' (most likely due to a circular import)
PS C:\Users\simon\OneDrive\Documents\Programming\Distance Converter> 

问题原因 #

代码存在循环导入：main.py导入distances模块，distances.py又导入main模块。当main.py执行到定义buttons列表并引用dc.distance_cmd时，distances模块尚未完成初始化（它正在等待main模块导入完成），因此无法找到distance_cmd属性，触发报错。

解决方案 #

方案1：通过参数传递共享对象（推荐） #

打破循环导入，让distances.py的函数通过参数接收需要操作的对象，而非导入整个main模块。

修改distances.py：

def distance_cmd(root):
    root.title("UnitConverter - Distances")

修改main.py中按钮的command配置，用lambda传递root参数：

buttons=[
    {"text": "Distances", "x": 50, "y": 100, "command": lambda: dc.distance_cmd(root)},
    # 其他按钮信息不变
]

方案2：延迟导入 #

将distances.py中的导入语句移到函数内部，避免模块级别的循环导入。

修改distances.py：

def distance_cmd():
    import main_copy as mc
    mc.root.title("UnitConverter - Distances")

这种方法能临时解决问题，但每次调用函数都会执行导入操作，性能和代码可读性不如方案1。

方案3：重构代码结构，拆分共享模块 #

将全局共享对象（如root）提取到单独的模块中，让main和distances都导入该模块，彻底消除循环依赖。

1. 创建config.py：

from tkinter import Tk
root = Tk()

2. 修改main.py：

from tkinter import *
from tkinter import ttk
import config
import distances as dc

config.root.geometry("500x300")
config.root.title("UnitConverter - Main Menu")

# 后续代码中所有用到root的地方替换为config.root
global headLabel
headLabel = Label(master=config.root, text="UnitConverter", font=("Aptos Semibold", 20))
headLabel.pack()

# ... 其他代码同理修改 ...

buttons=[
    {"text": "Distances", "x": 50, "y": 100, "command": dc.distance_cmd},
    # 其他按钮信息不变
]

config.root.mainloop()

3. 修改distances.py：

import config

def distance_cmd():
    config.root.title("UnitConverter - Distances")

这种方案适合后续功能扩展，代码结构更清晰。

内容的提问来源于stack exchange，提问作者Simon Vanderstraete Reel