02-模块管理

本章讲解 Python 模块的组织和管理。

---

导入系统

导入方式

# 1. 导入整个模块
import math
result = math.sqrt(16)

# 2. 导入特定成员
from math import sqrt, pi

# 3. 导入并重命名
from math import sqrt as square_root
import numpy as np

# 4. 相对导入（包内）
from . import sibling_module
from ..parent_package import module

init.py 的作用

my_package/
├── __init__.py      # 使目录成为包
├── module_a.py
└── subpackage/
    ├── __init__.py
    └── module_b.py

# __init__.py - 定义包的公共接口
from .module_a import public_function

__version__ = '1.0.0'
__all__ = ['public_function']  # 控制 * 导入

---

项目结构

标准项目结构

my_project/
├── pyproject.toml       # 项目配置和依赖
├── README.md            # 项目说明
├── src/
│   └── my_package/      # 源代码
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/               # 测试目录
│   └── test_core.py
└── docs/                # 文档目录

src 布局的优势

✅ src/my_package/    # 推荐
   - 避免导入本地目录而非安装包
   - 测试导入时使用已安装的包

❌ my_package/        # 避免（扁平布局）
   - 可能与本地目录冲突

---

包的组织

按功能分组

my_package/
├── database/        # 数据库相关
│   ├── connection.py
│   └── queries.py
├── api/            # API 相关
│   ├── routes.py
│   └── handlers.py
└── utils/          # 工具函数
    └── helpers.py

避免循环导入

# ❌ 错误：循环导入
# module_a.py
from module_b import func_b

# module_b.py
from module_a import func_a  # 循环导入！

# ✅ 解决：延迟导入
def func_a():
    from module_b import func_b  # 需要时再导入
    return func_b()

---

包的分发

构建和发布

# 1. 安装构建工具
uv add --dev build twine

# 2. 构建分发包
python -m build

# 3. 检查包
twine check dist/*

# 4. 上传到 PyPI
twine upload dist/*

---

本章小结

┌─────────────────────────────────────────────────────────────┐
│                    模块管理 知识要点                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   导入方式：                                                 │
│   ✓ import / from import / as 重命名                        │
│                                                             │
│   项目结构：                                                 │
│   ✓ 使用 src 布局                                           │
│   ✓ 按功能或业务领域分组                                    │
│                                                             │
│   最佳实践：                                                 │
│   ✓ 避免循环导入                                            │
│   ✓ 使用 __all__ 控制公共接口                               │
│                                                             │
└─────────────────────────────────────────────────────────────┘