11.模块 (module)
1 模块化 (module) 程序设计理念
1.1 模块和包概念的进化史
模块的本质：在 Python 中，模块的本质就是一个 Python 的独立文件（后缀名.py），里面可以包含全局变量、函数以及类。
- Python 程序由模块组成。一个模块对应一个 Python 源文件，一般后缀名是：
.py - 模块由语句组成。运行 Python 程序时，按照模块中语句的顺序依次执行
- 语句是 Python 程序的构造单元，用于创建对象、变量赋值、调用函数、控制语句等
1.2 标准库模块 (standard library)
与函数类似，模块也分为标准库模块（内置系统模块）和用户自定义模块。
Python 标准库提供了操作系统功能、网络通信、文本处理、文件处理、数学运算等基本的功能。比如：random(随机数)、math(数学运算)、time(时间处理)、file(文件处理)、os(和操作系统交互)、sys(和解释器交互) 等。
另外，Python 还提供了海量的第三方模块，使用方式和标准库类似。功能覆盖了我们能想象到的所有领域，比如：科学计算、WEB 开发、大数据、人工智能、图形系统等。
1.3 为什么需要模块化编程
模块（module）对应于 Python 源代码文件（.py 文件）。模块中可以定义变量、函数、类、普通语句。这样，我们可以将一个 Python 程序分解成多个模块，便于后期的重复应用。
模块化编程（Modular Programming）将一个任务分解成多个模块。每个模块就像一个积木一样，便于后期的反复使用、反复搭建。
模块化编程有如下几个重要优势：
- 便于将一个任务分解成多个模块，实现团队协同开发，完成大规模程序
- 实现代码复用。一个模块实现后，可以被反复调用。
- 可维护性增强。
1.4 模块化编程的流程
模块化编程的一般流程：
- 设计 API，进行功能描述。
- 编码实现 API 中描述的功能。
- 在模块中编写测试代码，并消除全局代码。
- 使用私有函数实现不被外部客户端调用的模块函数。
1.5 模块的 API 和功能描述要点
API（Application Programming Interface 应用程序编程接口）是模块中提供的函数和类的功能描述和使用方式的描述。
模块化编程中，首先设计的就是模块的 API（即要实现的功能描述），然后开始编码实现 API 中描述的功能。最后，在其他模块中导入本模块进行调用。
我们可以通过 help（模块名）查看模块的 API。一般使用时先导入模块，然后通过 help 函数查看。
案例：导入 math 模块，并通过 help() 查看 math 模块的 API：
import math
help(math)
也可以在 Python 的 API 文档中查询。首先进入 Python 安装目录下的 docs 子目录：
双击打开 chm 文档，即可通过索引输入 math查询到对应的 API 内容：
案例：设计计算薪水模块的 API
"""
本模块用于计门派弟子的薪资
"""
company = "古墓派"
def yearSalary(monthSalary):
"""根据传入的月薪，计算出年薪"""
pass
def daySalary(monthSalary):
"""根据传入的月薪，计算出每天的薪资"""
pass
如上模块只有功能描述和规范，需要编码人员按照要求实现编码。
我们可以通过 __doc__ 可以获得模块的文档字符串的内容。
import salary
help(salary)
help(salary.daySalary)
print(salary.__doc__)
print(salary.daySalary.__doc__)
1.6 模块的创建和测试代码
每个模块都有一个名称，通过特殊变量 __name__ 可以获取模块的名称。在正常情况下，模块名字对应源文件名。仅有一个例外，就是当一个模块被作为程序入口时（主程序、交互式提示符下），它的 __name__ 的值为 __main__。我们可以根据这个特点，将模块源代码文件中的测试代码进行独立的处理。例如：
import math
# 输出 'math'
math.__name__
案例：通过 __name__ == "__main__" 独立处理模块的测试代码
"""
本模块用于计门派弟子的薪资
"""
company = "古墓派"
def yearSalary(monthSalary):
"""根据传入的月薪，计算出年薪"""
return monthSalary * 12
def daySalary(monthSalary):
"""根据传入的月薪，计算出每天的薪资"""
# 国家规定每个月的平均工作日是 22.5
return monthSalary / 22.5
if __name__ == "__main__": # 测试代码
print(yearSalary(3000))
print(daySalary(3000))
1.7 模块文档字符串和 API 设计
我们可以在模块的第一行增加一个文档字符串，用于描述模块的相关功能。然后，通过 __doc__ 可以获得文档字符串的内容。
案例：模块文档字符串示例以及导入后如何读取文档字符串
import salary
# help(salary)
# help(salary.daySalary)
print(salary.__doc__)
print(salary.daySalary.__doc__)
2 模块的导入
2.1 import 语句导入
import 语句的基本语法格式如下：
import 模块名 # 导入一个模块
import 模块 1，模块 2… # 导入多个模块
import 模块名 as 模块别名 # 导入模块并使用新名字
import 加载的模块分为四个通用类别：
- 使用 Python 编写的代码（
.py文件）； - 已被编译为共享库或
DLL的 C 或 C++ 扩展； - 一组模块的包
- 使用 C 编写并链接到 Python 解释器的内置模块；
我们一般通过 import 语句实现模块的导入和使用，import 本质上是使用了内置函数 __import__()。
当我们通过 import 导入一个模块时，Python 解释器会执行它，最终生成一个对象，该对象就代表被加载的模块。
import math
print(f"type(math)：{type(math)}")
print(f"id(math)：{id(math)}")
print(math.pi) # 通过 math.成员名 来访问模块中的成员
由上，我们可以看到 math 模块被加载后，实际会生成一个 module 类的对象，该对象被 math 变量引用。我们可以通过 math 变量引用模块中所有的内容。
我们通过 import 导入多个模块，本质上也是生成多个 module 类的对象而已。
有时候，我们也需要给模块起个别名，本质上，这个别名仅仅是新创建一个变量引用加载的模块对象而已。
import math as m
# 等价于
"""
import math
m = math
"""
print(m.sqrt(4)) # 开方运算
2.2 from … import 导入
提问：已经有了 import 导入模块，为什么还需要使用 from 模块名 import 功能名 这样的导入方式？
答：import 会导入模块中的全部功能；但有些情况下我们只想用其中某些方法，无需全部导入，这时就建议采用 from 模块名 import 功能名。
Python 中可以使用 from … import 导入模块中的成员。基本语法格式如下：
from 模块名 import 成员 1, 成员 2, …
如果希望导入一个模块中的所有成员，则可以采用如下方式：
from 模块名 import *
案例：使用 from … import 导入模块指定的成员
from math import pi, sin
print(sin(pi / 2)) # 输出 1.0
2.3 import 语句和 from … import 语句的区别
import 导入的是模块。 from … import 导入的是模块中的一个函数/一个类。
我们自定义一个模块 calculator.py：
"""一个实现四则运算的计算器"""
def add(a, b):
return a + b
def minus(a, b):
return a - b
class MyNum():
def print123(self):
print(123)
我们在另一个模块 test.py 测试：
import calculator
a = calculator.add(30, 40)
# add(100,200) # 不加模块名无法识别
print(a)
from calculator import *
a = add(100, 200) # 无需模块名，可以直接引用里面的函数/类
print(a)
b = MyNum()
b.print123()
2.4 __import__() 动态导入
import 语句本质上就是调用内置函数 __import__()，我们可以通过它实现动态导入。给 __import__() 动态传递不同的参数值，就能导入不同的模块。
案例：使用 __import__() 动态导入指定的模块
s = "math"
# 导入后生成的模块对象的引用给变量 m
m = __import__(s)
print(m.pi)
import importlib
a = importlib.import_module("math")
print(a.pi)
2.5 模块的加载问题
当导入一个模块时，模块中的代码都会被执行。不过，如果再次导入这个模块，则不会再次执行。
Python 的设计者为什么这么设计？因为导入模块多数时候只是为了得到其中的变量、函数、对象等定义，并不需要反复定义和执行。于是「只导入一次」（import-only-once）就成了一种优化。
一个模块无论导入多少次，这个模块在整个解释器进程内有且仅有一个实例对象。
test02.py 的源代码：
print("test 模块被加载了 ...")
test03.py 的源代码：
# 会执行 test02 模块中的语句
import test02
# 不会再执行 test02 模块中的语句
import test02
重新加载
有时确实需要重新加载一个模块，这时可以用 importlib.reload() 方法：
import test02
import test02
print("####")
import importlib
importlib.reload(test02)
3 包 package 的使用
3.1 包 (package) 的概念和结构
当一个项目中有很多个模块时，需要再进行组织。我们将功能类似的模块放到一起，形成了「包」。本质上，「包」就是一个必须有 __init__.py 的文件夹。典型结构如下：
包下面可以包含「模块 (module)」，也可以再包含「子包 (subpackage)」。就像文件夹下面可以有文件，也可以有子文件夹一样。
上图中，a 是上层的包，下面有一个子包：aa。可以看到每个包里面都有 __init__.py 文件。
3.2 PyCharm 中创建包
在 PyCharm 开发环境中创建包非常简单。在要创建包的位置单击右键：New-->Python package 即可，PyCharm 会自动生成带有 __init__.py 文件的包。
3.3 导入包操作和本质
上一节中的包结构，我们需要导入 module_AA.py。方式如下：
import a.aa.module_AA
在使用时，必须加完整名称来引用。比如：a.aa.module_AA.fun_AA()from a.aa import module_AA
在使用时，直接可以使用模块名。比如：module_AA.fun_AA()from a.aa.module_AA import fun_AA直接导入函数
在使用时，直接可以使用函数名。比如：fun_AA()
导入包的本质其实是导入了包的 __init__.py 文件。也就是说，import pack1 意味着执行了包 pack1 下面的 __init__.py 文件。这样，可以在 __init__.py 中批量导入我们需要的模块，而不再需要一个个导入。
__init__.py 的三个核心作用：
- 作为包的标识，不能删除。
- 用来实现模糊导入
- 导入包实质是执行
__init__.py文件，可以在__init__.py文件中做这个包的初始化、以及需要统一执行代码、批量导入。
示例：测试包的 __init__.py 文件本质用法
a 包下的 __init__.py 文件内容：
import turtle
import math
print("导入 a 包")
b 包下的 module_B1.py 文件中导入 a 包，代码如下：
import a
print(a.math.pi)
3.4 用 * 导入包
import * 这样的语句理论上是希望文件系统找出包中所有的子模块，然后导入它们。这可能会花长时间等。Python 解决方案是提供一个明确的包索引。
这个索引由 __init__.py 定义 __all__ 变量，该变量为一列表，如上例 a 包下的 __init__.py 中，可定义 __all__ = ["module_A", "module_A2"]
这意味着，from a import * 会从对应的包中导入以上两个子模块。
3.5 包内引用
如果是子包内的引用，可以按相对位置引入子模块。
以 aa 包下的 module_AA 导入 a 包内容为例：
from .. import module_A # .. 表示上级目录 .表示同级目录
from . import module_A2 # . 表示同级目录
3.6 sys.path 和模块搜索路径
导入某个模块文件时，Python 解释器去哪里找它？只有找到这个文件，才能读取、装载并运行该模块。它一般按如下路径依次查找（按顺序查找，找到即停，不再往下）：
- 内置模块
- 当前目录
- 程序的主目录
pythonpath目录（如果已经设置了pythonpath环境变量）- 标准链接库目录
- 第三方库目录（
site-packages目录） .pth文件的内容（如果存在的话）sys.path.append()临时添加的目录
任何一个 Python 程序启动时，都会把这些搜索路径（内置模块除外）收集起来，放进 sys 模块的 path 属性（sys.path）。
1、使用 sys.path 查看和临时修改搜索路径
我们在项目的 b 目录下建立测试模块：
import sys
sys.path.append("d:/")
print(sys.path)
执行结果：
2、pythonpath 环境变量的设置
windows 系统中通过如下操作添加和设置 pythonpath 环境变量。
3、.pth 文件的写法
我们可以在 site-packages 目录下添加 .pth 文件。并在文件中增加内容：
#一行一个目录
g:\a
g:\b
g:\c
4 模块发布和安装
4.1 模块的本地发布
当我们完成了某个模块开发后，可以将它对外发布，其他开发者也可以以「第三方扩展库」的方式使用我们的模块。我们按照如下步骤即可实现模块的发布：
-
为模块文件创建如下结构的文件夹（一般，文件夹的名字和模块的名字一样）：
-
在文件夹中创建一个名为
setup.py的文件，内容如下：from distutils.core import setup setup( name='baizhan Math 2', # 对外我们模块的名字 version='1.0', # 版本号 description='这是第一个对外发布的模块，测试哦', # 描述 author='gaoqi', # 作者 author_email='gaoqi110@163.com', py_modules=['baizhanMath2.demo1', 'baizhan Math 2.demo2'] # 要发布的模块 ) -
构建一个发布文件。通过终端，
cd到模块文件夹c下面，再键入命令：python setup.py sdist执行完毕后，目录结构变为：
4.2 本地安装模块
将发布安装到你的本地计算机上。仍在 cmd 命令行模式下操作，进 setup.py 所在目录，键入命令：
python setup.py install
安装成功后，进入 Python 目录下的 /Lib/site-packages 目录（第三方模块都安装在这里，Python 解释器执行时也会搜索这个路径）：
安装成功后，直接使用 import 导入即可。
import baizhanMath2.demo1
4.3 上传模块到 PyPI
将自己开发好的模块上传到 PyPI 网站上，将成为公开的资源，可以让全球用户自由使用。按照如下步骤做，很容易就实现上传模块操作。
1、注册 PyPI 网站
注册 PyPI 网站：http://pypi.python.org
注意：会发送一封邮件到你的邮箱。请点击验证后继续下面的步骤。
2、创建用户信息文件 .pypirc
方式 1：使用命令 (适用 Linux)
输入并执行后 python setup.py register，然后输入用户名和密码，即可。
方式 2：使用文件（适用 windows,Linux）
在用户的家目录里创建一个文件名为 .pypirc，内容为：
[distutils]
index-servers=pypi
[pypi]
repository = https://upload.pypi.org/legacy/
username = 账户名
password = 你自己的密码
3、上传并远程发布
进入 setup.py 文件所在目录，使用命令 python setup.py sdist upload，即可以将模块代码上传并发布：
4、管理你的模块
我们登录 pypi 官网，可以看到：
如果你的模块已经上传成功，那么当你登录 PyPI 网站后应该能在右侧导航栏看到管理入口。
点击包名进去后你可以对你的模块进行管理，当然你也可以从这里删除这个模块。
4.4 让别人使用你的模块
模块发布完成后，其他人只需要使用 pip install 就可以安装你的模块文件。比如：
pip install package-name
如果你更新了模块，别人可以通过 --upgrade 参数来更新：
5 库 (Library)
「库」是借用其他编程语言的概念，在 Python 中没有特别具体的定义。
模块和包侧重于代码组织，有明确的定义；库则强调功能性，而不是代码组织。
我们通常把某个功能的模块集合称为库。
5.1 标准库 (Standard Library)
Python 拥有一个强大的标准库。Python 语言的核心只包含数字、字符串、列表、字典、文件等常见类型和函数，而 Python 标准库则提供了系统管理、网络通信、文本处理、数据库接口、图形系统、XML 处理等额外的功能。
Python 标准库的主要功能有：
- 文本处理，包含文本格式化、正则表达式匹配、文本差异计算与合并、Unicode 支持，二进制数据处理等功能
- 文件处理，包含文件操作、创建临时文件、文件压缩与归档、操作配置文件等功能
- 操作系统功能，包含线程与进程支持、IO 复用、日期与时间处理、调用系统函数、日志（logging）等功能
- 网络通信，包含网络套接字，SSL 加密通信、异步网络通信等功能
- 网络协议，支持 HTTP，FTP，SMTP，POP，IMAP，NNTP，XMLRPC 等多种网络协议，并提供了编写网络服务器的框架
- W3C 格式支持，包含 HTML，SGML，XML 的处理
- 其它功能，包括国际化支持、数学运算、HASH、Tkinter 等
5.2 第三方扩展库的介绍
强大的标准库奠定了 Python 发展的基石，丰富且不断扩展的第三方库则是 Python 壮大的保证。可以进入 PyPI 官网：https://pypi.org
我们可以看到发布的第三方库达到了十多万种，众多的开发者为 Python 贡献了自己的力量。
常用第三方库大汇总
5.3 PyPI 网站和 PIP 模块管理工具
PyPI（Python Package Index）是 Python 官方的第三方库仓库，所有人都可以下载第三方库，或上传自己开发的库到 PyPI。PyPI 推荐使用 pip 包管理器来下载第三方库。
pip 是一个现代、通用的 Python 包管理工具，提供对 Python 包的查找、下载、安装、卸载功能。pip 可运行在 Windows、Mac OS、Unix/Linux 等操作系统上，但需要至少 2.6+ 和 3.2+ 的 CPython 或 PyPy 支持。Python 2.7.9 和 3.4 以后的版本已内置 pip 程序，无需单独安装。
5.4 安装第三方扩展库的 2 种方式
第三方库有数十万种之多，以 pymysql 库为例讲解第三方扩展库的安装。
第一种方式：命令行下远程安装
- pip 更换数据源 (由于访问国外网站慢，建议更换)：
- 其他数据源：
- 以安装第三方
pymysql库为例，在命令行提示符下输入：pip install pymysql即可。
第二种方式：PyCharm 中直接安装到项目中
在 PyCharm 中，依次点击：file-->setting-->Project 本项目名-->Project Interpreter
点击 +，然后输入要安装的第三方库 pymysql，再点击按钮 Install Package，等待安装即可，几秒钟后，即提示安装成功：
这样就可以在项目中直接使用第三方库 pymysql 了。
6 术语表（重要英文单词）
6.1 模块与包基础
| 术语 | 全拼/说明 | 释义 |
|---|---|---|
| module | —— | 模块；一个 .py 文件就是一个模块，是代码组织的最小单位 |
| package | —— | 包；一个含 __init__.py 的目录（推荐做法），用于组织多个模块 |
| subpackage | —— | 子包；包内部的包，层层嵌套 |
| standard library | —— | 标准库；随 Python 一起安装的官方模块集合 |
| library | —— | 库；强调功能性的一组模块集合 |
__init__.py |
—— | 包的初始化文件，导入包时被执行，承载初始化与批量导入 |
| regular package | —— | 常规包；含 __init__.py 的包 |
| namespace package | —— | 命名空间包（PEP 420）；无 __init__.py，仅共享目录命名空间 |
__all__ |
—— | 包/模块中定义的公开名单列表，控制 from x import * 导入范围 |
| modular programming | —— | 模块化编程；把任务拆成多个模块来组织 |
6.2 导入机制
| 术语 | 全拼/说明 | 释义 |
|---|---|---|
import |
—— | 导入语句；导入模块对象，使用需加模块名前缀 |
from … import |
—— | 从模块中导入指定成员，使用无需前缀 |
import … as … |
—— | 导入并起别名；仅创建新的变量引用 |
__import__() |
—— | 内置函数；import 语句的底层实现，可动态导入 |
importlib |
import library | 导入机制的标准库模块，提供 import_module / reload |
importlib.import_module() |
—— | 按字符串动态导入，直接返回目标模块（含子模块） |
importlib.reload() |
—— | 重新加载已导入的模块，会再次执行模块顶层代码 |
| import-only-once | —— | 只导入一次；同一进程内重复导入不重复执行模块体 |
sys.modules |
—— | 已加载模块的缓存字典，import-only-once 的载体 |
sys.path |
—— | 模块搜索路径列表，决定解释器去哪找模块 |
sys.builtin_module_names |
—— | 编译进解释器的内置模块名元组 |
| PYTHONPATH | —— | 环境变量；其路径会被插入 sys.path 前部 |
| site-packages | —— | 第三方库安装目录，也在 sys.path 上 |
.pth file |
path file | site-packages 下的路径配置文件，每行一个目录追加进 sys.path |
| relative import | —— | 相对导入；用 .（同级）/ ..（上级）定位包内模块 |
| API | Application Programming Interface | 应用程序编程接口；模块对外提供的功能描述与调用方式 |
| PyPI | Python Package Index | Python 官方第三方库仓库（https://pypi.org） |
6.3 分发与安装
| 术语 | 全拼/说明 | 释义 |
|---|---|---|
setup.py |
—— | 传统打包脚本；调用 setup() 声明包元数据 |
setup() |
—— | 打包函数；声明 name/version/author/py_modules 等 |
distutils |
distribution utilities | 旧标准库打包工具，Python 3.12 起已移除（PEP 632） |
setuptools |
—— | 现代打包工具，内置 distutils 副本，setup() 现由它提供 |
pyproject.toml |
—— | 现代项目配置文件；声明构建后端与项目元数据（PEP 517/518/621） |
| sdist | source distribution | 源码分发包（.tar.gz） |
| wheel | —— | 二进制分发格式（.whl），pip 优先安装 |
python -m build |
—— | 现代构建命令，按 pyproject.toml 产出 sdist 与 wheel |
| twine | —— | 官方推荐的上传工具，替代已移除的 setup.py upload |
.pypirc |
—— | 上传凭据配置文件；现代用法建议改用 API Token |
| API token | —— | PyPI 作用域令牌；替代账户密码用于上传 |
pip |
pip installs packages | Python 包管理工具；查找/下载/安装/卸载 |
-i / --index-url |
—— | pip 指定数据源（镜像源）参数 |
-U / --upgrade |
—— | pip 升级已安装包到最新版（不是 --update） |
7 系列导航
8 参考链接
- Python 官方文档 · 模块（
import系统、importlib、搜索路径）：https://docs.python.org/zh-cn/3/reference/import.html - Python 官方教程 · 模块：https://docs.python.org/zh-cn/3/tutorial/modules.html
- Python 官方文档 ·
importlib模块：https://docs.python.org/zh-cn/3/library/importlib.html - Python 官方文档 ·
sys模块（sys.path/sys.modules）：https://docs.python.org/zh-cn/3/library/sys.html - Python 官方文档 ·
site模块（.pth文件机制）：https://docs.python.org/zh-cn/3/library/site.html - PEP 420 · 隐式命名空间包：https://peps.python.org/pep-0420/
- PEP 632 · 弃用
distutils（3.12 移除）：https://peps.python.org/pep-0632/ - PEP 517 / 518 · 构建系统与
pyproject.toml：https://peps.python.org/pep-0517/ - Python Packaging 官方指南 ·
setup.py是否已弃用：https://packaging.python.org/en/latest/discussions/setup-py-deprecated/ - 打包与分发 · 上传到 PyPI（twine）：https://packaging.python.org/en/latest/tutorials/packaging-projects/
- PyPI 官网：https://pypi.org
- os 模块详解（本库笔记）
分类：Python
浙公网安备 33010602011771号