如何配置setuptools.setup将examples作为mypkg的子包安装？

项目结构 #

project_root_directory
├── setup.py
├── examples
    ├── __init__.py
    ├── ...
├── src
    └── mypkg/
        ├── __init__.py
        ├── subpkg1/
        │   ├── __init__.py
        │   ├── ...
        │   └── module1.py
        └── subpkg2/
            ├── __init__.py
            ├── ...
            └── module2.py

需求 #

执行pip install [-e] .后，在Python解释器中能通过import mypkg访问mypkg.examples，即运行以下代码能显示examples包中的可用对象：

import mypkg
print(dir(mypkg.examples))

尝试的配置（无效） #

以下setup.py配置安装无报错，但无法访问mypkg.examples：

import os.path
from glob import glob

from setuptools import find_packages, setup

setup(
   name = 'mypkg',
   ...
   packages = find_packages('src') + ['mypkg.examples'],
   package_dir = {
      'mypkg': 'src/mypkg',
      'mypkg.examples': 'examples',
   },
   py_modules = [
        os.path.splitext(os.path.basename(path))[0] for path in glob("src/*.py")
    ],
   ...
)

解决方法 #

核心问题是包路径映射逻辑错误，调整setup.py如下：

from setuptools import find_packages, setup

setup(
    name='mypkg',
    # 保留你的其他元信息（version、author、description等）
    packages=find_packages('src') + ['mypkg.examples'],
    package_dir={
        '': 'src',  # 告知setuptools顶级包的根目录为src
        'mypkg.examples': '../examples'  # 相对src目录指向外部的examples文件夹
    },
    # 移除原py_modules配置——src目录下没有独立的.py模块，无需配置
)

关键说明 #

1. package_dir中'' : 'src'是基础配置，让setuptools默认从src目录查找所有顶级包（比如mypkg）
2. mypkg.examples的路径使用../examples，是相对于src目录的相对路径，确保setuptools将外部examples目录的内容识别为mypkg的子包
3. 确保examples目录下的__init__.py存在，若需要导出特定对象，可以在该文件中添加from . import 模块名或__all__ = ['对象名']

验证 #

重新执行pip install -e .，在Python解释器中运行：

import mypkg
print(dir(mypkg.examples))

此时应该能正常显示examples包中的可用对象。

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