如何配置pyproject.toml使共享Django应用支持pip安装？

问题原因 #

你的仓库采用扁平结构，根目录下存在多个被识别为顶级Python包的目录（如templatetags、tests，甚至可能包含migrations、management），同时根目录自身也是一个包（存在__init__.py）。setuptools的扁平布局模式不允许同时存在多个顶级包，因此触发安装错误。

另外，当前结构也不符合Django应用的标准规范（Django应用的templatetags、static、templates应作为应用包的子目录），会导致Django无法正确加载资源。

解决方案 #

方案1：重构目录结构（推荐，符合Django规范） #

将所有应用代码迁移到一个单独的子包目录中，调整后结构如下：

|- .gitignore
|- pyproject.toml
|- README.md
|- shared_django_app/
    |- __init__.py
    |- models.py
    |- views.py
    |- static/
        |- shared-django-app/
            |- # 静态文件
    |- templates/
        |- shared-django-app/
            |- # 模板文件
    |- templatetags/
        |- __init__.py
        |- # 自定义模板标签文件
    |- tests/
        |- __init__.py
        |- # 测试文件

然后更新pyproject.toml配置：

[build-system]
requires = ["setuptools"]

[project]
name = "django-shared-app"
version = "1.0.0"
# 指定依赖Django，确保安装时自动拉取兼容版本
dependencies = [
    "Django>=3.2"
]

[packages]
# 自动查找所有Python包（这里只会找到shared_django_app）
packages = [find_packages()]

# 配置要包含的非Python文件（静态资源、模板等）
[tool.setuptools.package-data]
shared_django_app = [
    "static/shared-django-app/**/*",
    "templates/shared-django-app/**/*",
    "templatetags/**/*"
]

# 排除测试目录（可选，避免将测试代码打包到发布版本）
[tool.setuptools.exclude-package-data]
shared_django_app = ["tests/**/*"]

方案2：不修改目录结构，强制指定包范围 #

如果暂时不想调整目录结构，可以修改pyproject.toml，明确只将根目录作为单个顶级包，并指定需要包含的资源文件：

[build-system]
requires = ["setuptools"]

[project]
name = "django-shared-app"
version = "1.0.0"
dependencies = [
    "Django>=3.2"
]

[packages]
# 只将根目录作为顶级包
packages = ["."]

# 配置包数据，包含静态资源、模板和模板标签
[tool.setuptools.package-data]
"." = [
    "static/shared-django-app/**/*",
    "templates/shared-django-app/**/*",
    "templatetags/**/*",
    "models.py",
    "views.py"
]

# 排除测试目录和无关文件
[tool.setuptools.exclude-package-data]
"." = ["tests/**/*", ".gitignore", "README.md"]

验证安装 #

修改配置后，重新执行安装命令：

pip install git+ssh://git@bitbucket.org:<org>/shared-django-app.git@dev

安装完成后，在Django项目的INSTALLED_APPS中添加shared_django_app（方案1）或django-shared-app（方案2，注意包名对应），即可正常使用该共享应用的功能。

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