含非Python文件的Python项目(src布局)开发运行及可编辑安装问题

方法1：动态识别环境调整路径 #

修改main.py的路径逻辑，自动判断当前处于开发环境还是安装后的环境，切换图标目录：

from os import path

BASE_FOLDER = path.dirname(__file__)
# 检查项目根目录的pyproject.toml是否存在，判断是否为开发环境
dev_project_root = path.dirname(path.dirname(path.dirname(BASE_FOLDER)))
DEV_MODE = path.exists(path.join(dev_project_root, "pyproject.toml"))

if DEV_MODE:
    # 开发环境下，图标指向项目根目录的icons文件夹
    ICONS = path.join(dev_project_root, "icons")
else:
    # 安装完成后，使用包目录下的icons
    ICONS = path.join(BASE_FOLDER, "icons")

这样直接执行python src/witty_name/main.py时会自动读取项目根目录的图标，安装后则使用包内的图标，无需重装。

方法2：可编辑安装+资源同步 #

如果使用setuptools作为构建后端，通过配置实现可编辑安装时的资源同步：

1. 在pyproject.toml中配置资源文件：

[project]
name = "witty_name"
# 补充其他项目配置（版本、作者等）

[tool.setuptools.package-data]
witty_name = ["icons/*"]

[tool.setuptools.package-dir]
witty_name = "src/witty_name"

2. 执行可编辑安装：

pip install -e . --no-build-isolation

3. 当icons目录有资源变更时，执行以下命令同步到site-packages的包目录：

python -m setuptools build_py

这种方式下代码修改无需重装，资源变更仅需执行一次同步命令，比全量重装高效很多。

方法3：环境变量指定路径 #

让程序优先读取环境变量中的图标路径，开发时手动设置环境变量即可：

from os import path, getenv

BASE_FOLDER = path.dirname(__file__)
# 优先使用环境变量指定的路径，默认用包内的icons
ICONS = getenv("WITTY_NAME_ICONS", path.join(BASE_FOLDER, "icons"))

• Windows开发时，先设置环境变量：

set WITTY_NAME_ICONS=C:\path\to\witty_name\icons

• Linux/macOS开发时：

export WITTY_NAME_ICONS=/path/to/witty_name/icons

之后直接运行python src/witty_name/main.py即可读取正确的图标路径，安装后无需设置环境变量，自动使用包内路径。

你的初始结构符合现代Python项目规范，对GUI项目完全合理：

• 采用src布局：源码集中在src/witty_name下，避免项目根目录的非源码文件被误导入，同时便于构建工具识别源码位置，这是PEP推荐的标准布局。
• 资源与源码分离：icons与src平级存放，符合“资源文件不属于源码”的分类逻辑，后续添加音效、样式等其他资源时，可轻松扩展出assets等目录，结构更清晰。
• 配置文件位置合规：pyproject.toml放在项目根目录，符合Python项目的配置惯例，构建工具能直接识别。

若要进一步优化，可将icons改为assets/icons，统一管理各类资源，但当前结构已完全满足GUI项目的需求。

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