如何无需指定根包导入子包并为根包设置别名？

问题描述 #

项目结构 #

project_root_directory
├── pyproject.toml
└── src/
    └── root/
        ├── __init__.py
        ├── module.py
        │
        ├── nested_a/
        │   ├── __init__.py
        │   ├── ...
        │   └── module.py
        │
        └── nested_b/
            ├── __init__.py
            ├── ...
            └── module.py

当前pyproject.toml配置 #

[project]
dependencies = []
description = "Friends"
name = "demo"
requires-python = ">=3.11"
version = "0.0.1"

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

[[project.authors]]
name = "Ross Geller"

当前导入方式 #

import root

import root.nested_a
import root.nested_b

import root.nested_a.module
import root.nested_b.module

期望实现的导入方式 #

需求1：直接导入子包

import root

import nested_a
import nested_b

import nested_a.module
import nested_b.module

需求2：包别名（保留原包名可用）

import my_pretty_root_name  # 替代 import root
import root  # 同时仍可正常使用

解决方案 #

解决需求1：直接导入nested_a/nested_b #

在src目录下分别创建nested_a和nested_b目录，并添加对应__init__.py文件：

1. 创建src/nested_a/__init__.py，内容如下：

from root.nested_a import *
from root.nested_a import __all__

2. 创建src/nested_b/__init__.py，内容如下：

from root.nested_b import *
from root.nested_b import __all__

3. 更新pyproject.toml，让setuptools识别这些新包：

[project]
# 保留原有配置，新增packages字段
packages = ["root", "nested_a", "nested_b"]

或者用自动发现规则：

[tool.setuptools.packages.find]
where = ["src"]
include = ["root*", "nested_a", "nested_b"]

安装后，import nested_a就等价于导入root.nested_a的全部内容，子模块如nested_a.module也能直接导入。

解决需求2：包别名（保留原包名） #

在src目录下创建my_pretty_root_name目录并添加__init__.py：

1. 创建src/my_pretty_root_name/__init__.py，内容如下：

from root import *
from root import __all__

2. 更新pyproject.toml的packages配置，加入别名包：

[project]
# 保留原有配置，更新packages字段
packages = ["root", "nested_a", "nested_b", "my_pretty_root_name"]

或者更新自动发现规则：

[tool.setuptools.packages.find]
where = ["src"]
include = ["root*", "nested_a", "nested_b", "my_pretty_root_name"]

安装后，import my_pretty_root_name会直接导入root包的全部内容，同时import root依然可以正常使用。

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