在 Python 中，包（Package）是一种管理模块（Module）的方式，
通过将相关模块组织在一个目录结构下，形成层次化的命名空间



1. 包的基本结构
包是一个包含 __init__.py 文件的目录，该目录下可以包含多个模块（.py 文件）或子包

示例结构：
my_package/
├── __init__.py       # 包初始化文件（Python 3.3+ 后可选，但推荐保留）
├── module1.py        # 模块文件
├── subpackage/       # 子包
│   ├── __init__.py
│   └── module2.py



2. __init__.py 的作用
标识目录为包：Python 通过该文件识别目录为包
初始化代码：可包含包加载时执行的代码
控制导入行为：通过 __all__ 变量指定 from package import * 导入的模块

示例 __init__.py：

# 导入子模块，使它们可直接通过包名访问
from .module1 import func1
from .subpackage.module2 import func2

# 指定当使用 `from my_package import *` 时导入的内容
__all__ = ['func1', 'func2']


3. 模块导入方式
绝对导入
从包的根目录开始指定完整路径：
from my_package.module1 import func1
from my_package.subpackage.module2 import ClassA

相对导入
在包内部使用 . 表示当前包，.. 表示父包：

# 在 module2.py 中
from . import helper  # 导入同级模块
from ..module1 import func1  # 导入上级包的模块



4. 包的命名空间
避免命名冲突：使用唯一的顶级包名（如公司名、项目名）
PEP 8 规范：包名建议使用小写字母，避免使用下划线（如 myproject 而非 my_project）



5. 发布包
将包发布到 PyPI 供他人使用，需创建：
setup.py 或 pyproject.toml：配置包的元数据（名称、版本、依赖等）
MANIFEST.in：指定需包含的非代码文件（如文档、配置）

示例 setup.py：
from setuptools import setup, find_packages

setup(
    name='my_package',
    version='1.0.0',
    packages=find_packages(),  # 自动发现所有包和子包
    install_requires=[
        'requests>=2.25.1',  # 依赖包
    ],
)



6. 包管理工具
pip：安装 / 卸载包，如 pip install my_package
检查包是否已安装 pip list |grep  my_package
virtualenv/venv：创建隔离的 Python 环境，避免依赖冲突
** Poetry/Pipenv**：高级依赖管理工具，自动生成锁定文件



7. 最佳实践
明确依赖关系：在 requirements.txt 或 pyproject.toml 中列出所有依赖
文档与测试：为包编写文档（如使用 Sphinx）和单元测试（如 unittest 或 pytest）
避免循环导入：重构代码以消除模块间的循环依赖
版本控制：使用语义化版本（SemVer）管理包版本


8. 常见问题
ModuleNotFoundError：检查 __init__.py 是否存在，路径是否正确
相对导入错误：相对导入只能在包内部使用，直接运行脚本会报错（需使用 -m 选项）
命名冲突：确保包名在全局环境中唯一