模块、包与工程化

6 minIntermediate

模块导入、包结构、虚拟环境与依赖管理。

1. 模块导入 (Importing)

模块是包含 Python 代码的 .py 文件，它可以包含函数、类和变量。

1.1 基本导入方式

 # 导入整个模块
 import math
 print(math.pi) # 输出: 3.141592653589793
 print(math.sqrt(16)) # 输出: 4.0
 # 导入模块并使用别名
 import math as m
 print(m.pi) # 输出: 3.141592653589793
 # 导入模块中的特定成员
 from math import pi, sqrt
 print(pi) # 输出: 3.141592653589793
 print(sqrt(16)) # 输出: 4.0
 # 导入模块中的所有成员
 from math import *
 print(pi) # 输出: 3.141592653589793
 print(sin(0)) # 输出: 0.0

1.2 导入路径 (Search Path)

Python 解释器在导入模块时，会按照以下顺序查找：

当前目录
PYTHONPATH 环境变量中指定的目录
标准库目录
第三方库目录 (site-packages)

 import sys
 # 查看导入路径
 print(sys.path)
 # 添加自定义目录到导入路径
 sys.path.append("/path/to/custom/modules")

1.3 相对导入

在包内部，可以使用相对导入来导入同一包中的其他模块。

 # 假设目录结构如下:
 # mypackage/
 # ├── __init__.py
 # ├── module1.py
 # └── subpackage/
 # ├── __init__.py
 # └── module2.py
 # 在 module2.py 中导入 module1.py
 from .. import module1
 # 在 module1.py 中导入 subpackage.module2
 from .subpackage import module2

1.4 动态导入

使用 importlib 模块可以动态导入模块。

 import importlib
 # 动态导入模块
 math_module = importlib.import_module("math")
 print(math_module.pi) # 输出: 3.141592653589793
 # 动态导入包中的模块
 os_path = importlib.import_module("os.path")
 print(os_path.abspath(".")) # 输出当前目录的绝对路径

2. 包 (Packages)

包是包含多个模块的目录，它必须包含一个 __init__.py 文件。

2.1 包的结构

 mypackage/
 ├── __init__.py
 ├── module1.py
 ├── module2.py
 └── subpackage/
  ├── __init__.py
  └── module3.py

2.2 `init.py` 文件

__init__.py 文件用于标识一个目录为包，它可以包含包的初始化代码。

 # mypackage/__init__.py
 # 包的版本
 _
 # 从包中导出成员
 from .module1 import function1
 from .module2 import function2
 # 定义包级别的变量
 package_variable = "This is a package variable"
 # 包的初始化代码
 print("Initializing mypackage")

2.3 导入包

 # 导入整个包
 import mypackage
 print(mypackage.__version__) # 输出: 1.0.0
 print(mypackage.package_variable) # 输出: This is a package variable
 print(mypackage.function1()) # 调用从 module1 导出的函数
 # 导入包中的模块
 from mypackage import module1
 print(module1.function1()) # 调用 module1 中的函数
 # 导入子包
 from mypackage.subpackage import module3
 print(module3.function3()) # 调用 module3 中的函数

2.4 命名空间包

Python 3.3+ 支持命名空间包，它允许将多个目录作为同一个包的一部分，而不需要 __init__.py 文件。

3. 命名空间与 `name`

3.1 命名空间

每个模块都有自己的命名空间，用于存储模块中的变量、函数和类。

 # module1.py
 x = 10
 def function():
  pass
 class MyClass:
  pass
 # 在另一个模块中
 import module1
 print(module1.x) # 访问 module1 的命名空间中的变量

3.2 `name` 属性

每个模块都有一个 __name__ 属性，用于标识模块的名称。

当模块作为主程序运行时，__name__ 的值为 "__main__"
当模块被导入时，__name__ 的值为模块的名称

 # module.py
 print(f"Module name: {__name__}")
 if __name__ == "__main__":
  print("Running as main program")
 else:
  print("Being imported as a module")
 # 运行 module.py 直接执行
 # 输出:
 # Module name: __main__
 # Running as main program
 # 在另一个模块中导入 module.py
 # 输出:
 # Module name: module
 # Being imported as a module

3.3 示例：模块的测试代码

 # utils.py
 def add(a, b):
  """加法函数"""
  return a + b
 def multiply(a, b):
  """乘法函数"""
  return a * b
 # 测试代码
 if __name__ == "__main__":
  print("Testing utils module")
  print(f"add(2, 3) = {add(2, 3)}")
  print(f"multiply(2, 3) = {multiply(2, 3)}")

4. 第三方库管理 (pip)

4.1 基本命令

 # 安装包
 pip install package_name
 # 安装指定版本的包
 pip install package_name==1.0.0
 # 升级包
 pip install --upgrade package_name
 # 卸载包
 pip uninstall package_name
 # 列出已安装的包
 pip list
 # 查看包的详细信息
 pip show package_name
 # 导出依赖
 pip freeze > requirements.txt
 # 安装依赖
 pip install -r requirements.txt
 # 检查包的更新
 pip list --outdated

4.2 虚拟环境中的 pip

在虚拟环境中使用 pip 安装的包只对该虚拟环境有效，不会影响系统全局的包。

4.3 国内镜像源

使用国内镜像源可以加快包的下载速度：

 # 临时使用
 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple package_name
 # 永久设置
 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

常用的国内镜像源：

清华大学: https://pypi.tuna.tsinghua.edu.cn/simple
阿里云: https://mirrors.aliyun.com/pypi/simple
豆瓣: https://pypi.douban.com/simple

5. 虚拟环境 (Virtual Environments)

5.1 虚拟环境的作用

隔离依赖: 不同项目可以使用不同版本的包
避免冲突: 防止包版本冲突
便于管理: 每个项目的依赖都独立管理
便于部署: 可以轻松导出和安装依赖

5.2 使用 `venv` 创建虚拟环境

 # 创建虚拟环境
 python -m venv venv
 # 激活虚拟环境（Windows）
 venv\Scripts\activate.bat
 # 激活虚拟环境（Linux/Mac）
 source venv/bin/activate
 # 退出虚拟环境
 deactivate

5.3 使用 `conda` 创建虚拟环境

 # 创建虚拟环境
 conda create -n myenv python=3.8
 # 激活虚拟环境
 conda activate myenv
 # 退出虚拟环境
 conda deactivate
 # 删除虚拟环境
 conda remove -n myenv --all

5.4 使用 `poetry` 管理依赖

 # 初始化项目
 poetry init
 # 添加依赖
 poetry add package_name
 # 安装依赖
 poetry install
 # 激活虚拟环境
 poetry shell
 # 运行命令
 poetry run python script.py

5.5 虚拟环境的最佳实践

每个项目使用独立的虚拟环境
使用 requirements.txt 或 pyproject.toml 管理依赖
将虚拟环境目录添加到 .gitignore
定期更新依赖
在部署前测试依赖

6. 模块和包的最佳实践

6.1 模块设计

单一职责: 每个模块应该只负责一个功能
命名规范: 模块名应该小写，使用下划线分隔单词
文档: 为模块添加文档字符串
导入顺序: 按标准库、第三方库、本地模块的顺序导入
避免循环导入: 合理设计模块间的依赖关系

6.2 包设计

层次清晰: 包的结构应该层次清晰，易于理解
__init__.py: 合理使用 __init__.py 文件，导出重要的成员
相对导入: 在包内部使用相对导入
版本管理: 在包中包含版本信息
测试: 为包添加测试代码

6.3 导入规范

避免使用 from module import *: 可能导致命名冲突
使用别名: 对于长模块名，使用简洁的别名
分组导入: 按功能分组导入
显式导入: 明确导入需要的成员

7. 实际应用示例

7.1 创建和使用自定义模块

 # utils.py
 """工具模块"""
 def calculate_area(radius):
  """计算圆的面积"""
  import math
  return math.pi * radius ** 2
 def calculate_perimeter(radius):
  """计算圆的周长"""
  import math
  return 2 * math.pi * radius
 # 使用模块
 import utils
 radius = 5
 print(f"Radius: {radius}")
 print(f"Area: {utils.calculate_area(radius):.2f}")
 print(f"Perimeter: {utils.calculate_perimeter(radius):.2f}")

7.2 创建和使用包

 # 包结构
 mymath/
 ├── __init__.py
 ├── geometry.py
 └── algebra.py

 # mymath/__init__.py
 """数学包"""
 _
 from .geometry import calculate_area, calculate_perimeter
 from .algebra import add, subtract, multiply, divide
 # mymath/geometry.py
 """几何模块"""
 import math
 def calculate_area(radius):
  """计算圆的面积"""
  return math.pi * radius ** 2
 def calculate_perimeter(radius):
  """计算圆的周长"""
  return 2 * math.pi * radius
 # mymath/algebra.py
 """代数模块"""
 def add(a, b):
  """加法"""
  return a + b
 def subtract(a, b):
  """减法"""
  return a - b
 def multiply(a, b):
  """乘法"""
  return a * b
 def divide(a, b):
  """除法"""
  if b == 0:
  raise ZeroDivisionError("Cannot divide by zero")
  return a / b
 # 使用包
 import mymath
 print(f"Package version: {mymath.__version__}")
 # 使用几何模块
 radius = 5
 print(f"Circle with radius {radius}:")
 print(f"Area: {mymath.calculate_area(radius):.2f}")
 print(f"Perimeter: {mymath.calculate_perimeter(radius):.2f}")
 # 使用代数模块
 print("\nAlgebra operations:")
 print(f"2 + 3 = {mymath.add(2, 3)}")
 print(f"5 - 2 = {mymath.subtract(5, 2)}")
 print(f"3 * 4 = {mymath.multiply(3, 4)}")
 print(f"10 / 2 = {mymath.divide(10, 2)}")

7.3 管理项目依赖

 # 创建虚拟环境
 python -m venv venv
 # 激活虚拟环境
 venv\Scripts\activate.bat
 # 安装依赖
 pip install requests
 pip install pandas
 pip install matplotlib
 # 导出依赖
 pip freeze > requirements.txt
 # 查看依赖
 cat requirements.txt
 # 安装依赖（在另一台机器上）
 pip install -r requirements.txt

7.4 项目结构示例

 myproject/
 ├── venv/ # 虚拟环境
 ├── mypackage/ # 主包
 │ ├── __init__.py
 │ ├── module1.py
 │ ├── module2.py
 │ └── subpackage/
 │ ├── __init__.py
 │ └── module3.py
 ├── tests/ # 测试目录
 │ ├── __init__.py
 │ └── test_module1.py
 ├── scripts/ # 脚本目录
 │ └── run.py
 ├── requirements.txt # 依赖文件
 └── README.md # 项目说明

8. 高级话题

8.1 模块的 reload

使用 importlib 模块可以重新加载已经导入的模块。

 import importlib
 import mymodule
 # 修改 mymodule.py 后重新加载
 importlib.reload(mymodule)

8.2 模块的缓存

Python 会缓存导入的模块，以提高性能。

 import sys
 # 查看已导入的模块
 print(list(sys.modules.keys()))
 # 移除模块缓存
 del sys.modules["mymodule"]
 # 再次导入时会重新加载
 import mymodule

8.3 包的分发

使用 setuptools 可以将包分发给其他人。

 # setup.py
 from setuptools import setup, find_packages
 setup(
  name="mymath",
  version="1.0.0",
  description="A simple math package",
  packages=find_packages(),
  install_requires=[],
  entry_points={
  "console_scripts": [
  "mymath = mymath.cli:main"
  ]
  }
 )

8.4 包的安装方式

开发模式安装: pip install -e .
构建分发包: python setup.py sdist bdist_wheel
上传到 PyPI: twine upload dist/*

更新日志 (Changelog)

2026-04-05: 补充 Python 包管理与虚拟环境细节。
2026-04-05: 扩写内容，增加详细的模块导入、包结构、命名空间、第三方库管理、虚拟环境和实际示例等内容。