如何组织Python项目实现类似Django的模块全局访问方式？

我完全懂你的痛点——之前我也折腾过好一阵，想不用改环境变量就能像Django那样用顶级包名导入模块。其实核心问题不是加几个__init__.py，而是要把你的项目变成可安装的Python包，这样Python就能自动识别Project这个顶级模块了。下面一步步来解决：

第一步：调整项目结构 #

首先把你的现有代码放到一个和项目同名的子文件夹里，同时加入独立的tests目录和打包配置文件。最终结构应该是这样：

Project/
├── Project/                # 核心代码目录（和项目根目录同名）
│   ├── __init__.py         # 必须有，标记为Python包
│   ├── utils/
│   │   ├── __init__.py
│   │   └── log.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── get_data_from_api.py
│   └── main.py
├── tests/                  # 独立的测试目录
│   ├── __init__.py
│   ├── test_api.py
│   └── test_utils.py
└── pyproject.toml          # 打包配置文件（替代旧的setup.py）

第二步：添加打包配置文件 #

在项目根目录创建pyproject.toml，内容如下：

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "Project"
version = "0.1.0"
packages = ["Project"]

这个文件告诉Python，你的Project文件夹是一个可安装的包，setuptools会帮你自动处理模块路径的问题。

第三步：安装为可编辑模式 #

打开终端，进入项目根目录（也就是包含pyproject.toml的那个Project文件夹），运行以下命令：

pip install -e .

-e代表"可编辑"模式，这样你修改项目代码时，不需要重新安装就能生效，非常适合开发阶段。

第四步：验证导入是否生效 #

现在你在get_data_from_api.py里就可以这样写了：

import Project.utils.log

# 或者更简洁的写法
from Project.utils import log

运行main.py或者测试文件时，Python会自动找到Project这个顶级包，完全不需要修改PYTHONPATH。

关于tests目录的配置 #

因为你已经把Project安装为可编辑包了，tests目录里的测试文件可以直接导入项目模块，比如在test_api.py里：

from Project.api.get_data_from_api import some_function
from Project.utils.log import setup_logger

# 编写测试用例
def test_some_function():
    assert some_function() == expected_result

如果你用pytest之类的测试框架，直接在项目根目录运行pytest即可，它会自动发现tests目录下的测试文件。

为什么Django不需要改PYTHONPATH？ #

其实Django本身是作为第三方包安装到Python的site-packages目录里的，Python启动时会自动扫描这个目录，自然能找到django这个顶级模块。我们上面的操作就是把自己的项目也放到了Python的可识别路径里（通过可编辑安装），原理和Django是完全一致的。

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