模块化开发前奏(基础部分)

和函数用来实现代码复用一样，Python 模块化开发目的也是实现代码解耦、提高可维护性和复用性。实现方法是将代码拆分为独立、可复用的模块，通过模块的导入与导出来实现代码解耦、可维护性和复用性。其底层逻辑是基于 Python 的模块搜索路径和命名空间机制，从基础的单文件模块到复杂的包结构，形成了一套完整的模块化体系。

本篇讨论模块化开发基础部分，包括：模块的基础概念、模块导入、导出的几种方式、包的概念，以及如何规划包。 下一篇讨论 import 的核心细节，也许不是你理解的import、模块的搜索路径、Python如何临时操作环境变量。

一、核心概念：模块（Module）

1. 什么是模块？

我们先来简单粗略的有个概念，后面会逐个话题展开细节。一个以 .py 为后缀的 Python 文件就是一个模块，是组织代码的基本单元。模块内可以包含：变量、函数、类、以及可执行代码这四类内容。

变量模块中可以定义全局变量（基本数据类型、容器类型等），这些变量可以被其他导入该模块的文件访问使用。

# 示例（模块内的变量定义）# 模块名：my_module.py# 基本类型变量num = 100str_info = "这是一个Python模块"# 容器类型变量user_list = ["Allen", "Mark"]user_dict = {"name": "Allen", "age": 25}

函数模块中可以通过 def 关键字定义函数，这是模块封装功能的核心方式之一，导入模块后可调用这些函数。

# 模块名：my_module.py# 定义一个求和函数defadd(a, b):return a + b# 定义一个打印信息的函数defprint_info():print("来自my_module模块的信息")

类模块中可以通过 def 关键字定义函数，这是模块封装功能的核心方式之一，导入模块后可调用这些函数。

# 模块名：my_module.pyclassPerson:# 类属性    species = "人类"# 构造方法def__init__(self, name, age):self.name = name  # 实例属性self.age = age# 实例方法defintroduce(self):print(f"我叫{self.name}，今年{self.age}岁")

可执行代码模块中可以存在不包含在函数或类中的 “直接可执行代码”。这些代码的运行时机：在模块被导入或直接运行时执行。 详细如下：

当模块直接运行时（命令行执行 python my_module.py），可执行代码会直接执行；当模块被其他文件导入时（import my_module），可执行代码也会自动执行（这是很多初学者容易忽略的点）若想让可执行代码仅在模块直接运行时执行，可通过 if name == "main" ：包裹，这是 Python 的最佳实践

# 示例：模块顶层的可执行代码# 模块名：my_module.py# 直接可执行的打印语句print("my_module模块被加载了！")import sys# 定义模块要求的最低Python版本MIN_PYTHON_VERSION = (3, 8)if sys.version_info < MIN_PYTHON_VERSION:raise ImportError(f"该模块要求Python {MIN_PYTHON_VERSION[0]}.{MIN_PYTHON_VERSION[1]} 及以上版本，"f"当前使用的Python版本为 {sys.version_info.major}.{sys.version_info.minor}"    )# 版本满足时，执行模块初始化逻辑print("Python版本校验通过，模块初始化中...")# 导入模块内部组件等# from .core import xxx

2. 模块的作用

1. 1. 代码复用：一次编写，多处导入使用。
2. 2. 代码解耦：将不同功能的代码分离到不同模块，降低耦合度。
3. 3. 命名空间隔离：模块内的变量/函数不会与全局或其他模块的同名元素冲突。
4. 4. 提高可维护性：单个模块功能单一，便于修改和测试。

二、模块的基础使用：定义与导入、导出

在上面对什么是模块，模块内都有什么，有了一个初步的认识，现在开始细节的学习如何定义一个模块，如何导入和导出模块的内容来实现代码的复用。

1. 定义模块

模块分为：基础单文件模块、复杂包模块，本节讨论最基础、最核心的单文件模块。往下滑是复杂包模块的细节。

基础单文件模块本质就是创建一个后缀为 .py 的 Python 文件，文件内写入你需要的变量、函数、类等内容即可

创建一个简单的模块 math_utils.py，实现数学工具函数：

# math_utils.py（模块文件）PI = 3.1415926defadd(a: float, b: float) -> float:"""两数相加"""return a + bdefcircle_area(radius: float) -> float:"""计算圆的面积"""return PI * radius ** 2# 模块内的可执行代码（导入时会自动运行）print("math_utils 模块被导入了")

2. 导入模块的 4 种方式

（1）导入整个模块

最基础，最常用的导入方式，用于完整导入一个模块，使用模块内的成员（函数、类、变量等）时需要添加「模块名前缀」。语法：import 模块名。

# main.py（主程序文件）import math_utils# 使用模块名.变量/函数 访问print(math_utils.PI)  # 输出：3.1415926print(math_utils.add(2, 3))  # 输出：5print(math_utils.circle_area(2))  # 输出：12.5663704

• • 特点：通过模块名.成员访问，最安全，不会污染当前命名空间。

（2）导入模块并指定别名

在导入模块的同时给模块起一个简短的别名，后续使用时通过「别名前缀」访问成员，简化代码书写。

import math_utils as mu  # 别名 mu 更简洁print(mu.PI)print(mu.add(2, 3))

• • 适用场景：模块名较长（如 numpy 常用 np 作为别名，pandas 常用 pd 作为别名）。

（3）从模块中导入指定成员

不导入整个模块，仅导入模块中需要的特定成员（函数、类、变量），使用时无需添加模块名前缀，直接使用成员名即可

from math_utils import PI, addprint(PI)  # 直接访问，无需模块名print(add(2, 3))

• • 特点：直接将成员导入当前命名空间，使用方便，但可能与现有变量冲突。

（4）从模块中导入所有成员（不推荐）

一次性导入模块中的所有公开成员，使用时直接调用成员名，无需模块名前缀，是最便捷但风险较高的导入方式。

from math_utils import *print(PI)print(add(2, 3))

缺点：

1. 1. 污染当前命名空间，容易引发同名冲突。
2. 2. 无法明确知道导入了哪些成员，降低代码可读性。

导入方式总结

1. 1. 直接导入（import 模块名）：基础安全，不污染命名空间，通用场景首选。
2. 2. 别名导入（import 模块名 as 别名）：简化书写，行业通用，长模块名必备。
3. 3. 精准导入（from 模块名 import 成员）：便捷高效，仅导入需要的成员，无多余冗余。
4. 4. 批量导入（from 模块名 import *）：便捷但危险，污染命名空间，仅临时使用。

3. 导出模块的方法

在其他语言中有显式的 export 关键字来导出函数、对象、类等，但是Python 中没有export关键字，实现该功能无需关键字，有两种核心方式：

1. 默认导出规则（无需额外配置）

Python 模块中，模块顶层成员（变量、函数、类），默认都是可导出的，可以被其他模块通过import语句导入使用。

这里有一个约定的命名规则，不是语法约束：Python 模块中，所有不以单下划线_开头的顶层成员（变量、函数、类），默认都是可以通过 4 种导入方式被其他模块导入，单_开头的视为私有成员，默认不被 from x import *导入，但是可以强制用 from x import _priate_var 导入

示例：

模块文件：mymodule.py

# 可导出（无下划线开头）public_var = "公开变量"def public_func():return"公开函数"class PublicClass:pass#（单下划线开头，视为私有成员）# 可被别的模块强制导入，但是不被import* 导入_private_var = "私有变量"def _private_func():return"私有函数"

其他文件导入使用：

import mymodule# 可以正常访问公开成员print(mymodule.public_var)print(mymodule.public_func())obj = mymodule.PublicClass()# 无法通过「import*」访问私有成员（虽强行访问可实现，但不推荐）# print(mymodule._private_var)  # 不建议这样使用

2. 显式指定导出成员（__all__特殊变量）

__all__ 仅用来约束 import* 时候的行为。

当使用 from module import * 时，Python 只会导入满足以下条件的顶层对象：若模块未定义特殊变量名字 __all__，则不以下划线 _ 开头的变量、函数、类。若模块定义了特殊变量 __all__，则只导入 __all__ 列表中明确列出的名字（无论名字是否以下划线开头）。

如果需要更精确地控制「当使用from 模块名 import *时」能导入的成员，Python 提供了特殊变量__all__（这是一个字符串列表，存放需要暴露的成员名称），这是 Python 中显式声明模块导出成员的标准方式。定义__all__仅是为了影响from module import *时候的导入行为，仅更精确地控制导入列表内列出的内容。

示例修改mymodule.py：

# 定义公开成员var1 = "变量1"var2 = "变量2"func1 = lambda: "函数1"func2 = lambda: "函数2"# 显式指定：使用from mymodule import * 时，仅能导入这些成员__all__ = ["var1", "func1"]

• • 导入测试：

from mymodule import *print(var1)  # 正常输出：变量1print(func1())  # 正常输出：函数1# print(var2)  # 报错：NameError: name 'var2' is not defined（未被导出）

使用 from 模块名 import *（all 唯一生效的场景）除了from 模块 import *之外，其他导入方式（如 import 模块、from 模块 import 具体成员）完全不受__all__的影响，顶层变量的默认导出规则依然有效。

4. name 变量与主程序入口

__name__ 是 Python 每个模块（.py 文件）自带的内置特殊变量，无需手动定义，它的核心作用是标识模块的运行状态——判断当前模块是「被直接运行」，还是「被其他模块导入使用」。Python 解释器会在加载模块时自动为其赋值。

__name__ 的值只有两种情况，取决于模块的运行方式：

取值 1：__main__（模块被直接运行时），主程序入口

当你直接通过 python 模块名.py 命令执行某个.py 文件时，该文件（主模块）的 __name__ 变量会被 Python 解释器自动赋值为字符串 "__main__"。

取值 2：模块名（模块被其他模块导入时）

当某个.py 文件作为模块，被其他.py 文件通过 import 语句导入时，被导入模块的 __name__ 变量会被赋值为该模块的文件名（即模块名，不含.py 后缀）。

总结：主程序入口：if __name__ == "__main__":

这是 Python 中实现主程序入口的标准语法，它利用 __name__ 变量的特性，实现「模块自身运行时执行指定代码，被导入时不执行该代码」的效果。

当模块直接运行时：__name__ == "__main__" 条件成立，执行判断语句块内的代码（通常是程序启动逻辑、自测代码等）。

当模块被导入时：__name__ == "__main__" 条件不成立，不执行判断语句块内的代码，仅对外暴露模块中的函数、类、变量等成员。

5. 导入时的注意事项

1. 1. 模块的执行：导入模块时，模块内的所有可执行代码（如 print、变量赋值）都会被运行一次。
2. 2. 模块的搜索路径：Python 导入模块时，会按以下顺序搜索：
• • 当前目录（运行 python 命令的目录）。
• • 系统环境变量 PYTHONPATH 指定的目录。
• • Python 安装目录下的 site-packages（第三方库目录）。
• • 可通过 sys.path 查看当前模块搜索路径：

  import sysprint(sys.path)

3. 3. 模块的缓存：模块被导入一次后，会被缓存到 sys.modules 中，后续导入不会重新执行模块代码，提升效率。

四、包（Package）：模块的集合

当功能复杂，模块数量较多时，需要用包来组织模块，包是一个包含 __init__.py 文件的文件夹。作为模块的集合，是组织大型 Python 项目代码的核心结构。

1. 包的核心本质与标识

1. 1. 本质：Python 包是存放多个模块（.py 文件）的文件夹，其核心作用是将功能相关的模块归类整合，避免模块名冲突，让项目代码结构更清晰、更易于维护（尤其适用于大型项目）。
2. 2. 核心标识：一个普通文件夹要成为 Python 可识别的包，必须包含一个特殊文件 —— __init__.py（早期 Python 版本强制要求，Python3.3+支持无该文件的「命名空间包」，但常规开发仍推荐保留__init__.py，用于包的初始化配置）。__init__.py 可以是空文件，也可以包含包的初始化逻辑（如版本校验、批量导出模块成员等）。

2. 包的目录结构

填充模块内容（为后续导入做准备）

1. 1. my_package/core.py（核心功能模块）：

   # 定义核心业务函数defcalculate_sum(a, b):"""计算两个数的和"""return a + b# 定义核心业务类classCalculator:"""简单计算器类"""defmultiply(self, a, b):return a * b

2. 2. my_package/utils.py（工具功能模块）：

   # 定义工具函数defformat_result(value):"""格式化输出结果"""returnf"结果：{value}"# 定义工具变量MAX_NUM = 1000# 最大支持数值

3. 3. my_package/__init__.py（先保留为空，后续讲解其功能时再填充内容）：

   # 暂时为空，仅作为包的标识pass

3. __init__.py 的作用

1. 1. 标识目录为 Python 包：没有该文件的目录，Python 会视为普通目录，无法导入。
2. 2. 包的初始化代码：导入包时，会自动执行该文件中的代码。
3. 3. 控制包的导出成员：通过 __all__ 变量指定 from 包 import * 时要导出的成员。

示例：game_tools/__init__.py

# 包的初始化代码print("game_tools 包被导入了")# 从子模块导入常用成员，方便外部直接访问from .input_utils import key_pressfrom .graphics_utils import draw_sprite# 指定 from game_tools import * 时要导出的成员__all__ = ["key_press", "draw_sprite", "audio"]

4. 包的导入方式

方式 1：导入包内指定模块（需加模块前缀使用）

# main.py 文件# 导入my_package包内的core模块和utils模块import my_package.coreimport my_package.utils as pkg_utils  # 给模块指定别名，简化使用# 使用方式：包名.模块名.成员名 （或 别名.成员名）# 调用core模块的函数和类sum_result = my_package.core.calculate_sum(10, 20)print(sum_result)  # 输出：30calc = my_package.core.Calculator()multiply_result = calc.multiply(10, 20)print(multiply_result)  # 输出：200# 调用utils模块的函数和变量（使用别名）formatted_str = pkg_utils.format_result(multiply_result)print(formatted_str)  # 输出：结果：200print(pkg_utils.MAX_NUM)  # 输出：1000

方式 2：从包中直接导入指定模块

# main.py 文件# 从my_package包中导入core和utils模块from my_package import core, utils# 使用方式：模块名.成员名sum_result = core.calculate_sum(5, 6)formatted_str = utils.format_result(sum_result)print(formatted_str)  # 输出：结果：11print(utils.MAX_NUM)  # 输出：1000

方式 3：从包的指定模块中导入特定成员（精准导入）

这是最常用的方式，直接导入需要的函数/类/变量，无需多层前缀：

# main.py 文件# 从my_package的core模块导入calculate_sum函数和Calculator类from my_package.core import calculate_sum, Calculator# 从my_package的utils模块导入format_result函数和MAX_NUM变量from my_package.utils import format_result, MAX_NUM# 使用方式：直接调用成员，无任何前缀result = calculate_sum(3, 4)print(format_result(result))  # 输出：结果：7calc = Calculator()print(format_result(calc.multiply(3, 4)))  # 输出：结果：12print(MAX_NUM)  # 输出：1000

方式 4：批量导入包内模块/成员（借助__init__.py）

上面多次说到了，通过配置包的 __init__.py 文件，可实现 from 包名 import * 的精准批量导入。

5、嵌套包（子包）

实际项目中，包可以嵌套使用（即包内包含子包），形成多层级的代码结构，核心规则与普通包一致，只需遵循「包名.子包名.模块名」的层级访问格式。

1. 嵌套包目录结构

my_project/├── main.py└── my_package/          # 父包    ├── __init__.py    ├── core.py    ├── utils.py    └── sub_package/     # 子包（嵌套在my_package内）        ├── __init__.py        └── helper.py    # 子包内的模块

2. 子包模块内容（my_package/sub_package/helper.py）

defprint_info(msg):"""子包工具函数：打印信息"""print(f"【辅助信息】{msg}")

3. 嵌套包的导入方式

# main.py 文件# 方式1：导入子包模块import my_package.sub_package.helper as helperhelper.print_info("嵌套包导入成功")  # 输出：【辅助信息】嵌套包导入成功# 方式2：从父包导入子包模块from my_package.sub_package import helperhelper.print_info("简化嵌套包导入")  # 输出：【辅助信息】简化嵌套包导入# 方式3：从子包模块导入特定成员from my_package.sub_package.helper import print_infoprint_info("精准导入子包成员")  # 输出：【辅助信息】精准导入子包成员

下一篇详解 import

如果觉着本篇对您有点帮助，可以点一个在看和红心，是对我最大的鼓舞，如果对您有帮助或者篇中内容有纰漏，也请您留言告知。感谢！

往期经典