1.1.1. 什么是模块#

Python 模块（module）指的是一个 .py 文件。

一个模块中可以包含：

1. 变量。
2. 函数。
3. 类。
4. 可执行代码。

简单来说：

一个 Python 文件就是一个模块，模块是 Python 程序的基本组织单位。

例如，定义一个 circle_fun.py 文件：

1
# 根据半径计算圆的面积
2
def circle_area(r):
3
    pi = 3.14
4
    area = pi * r * r
5
    return area
6

7
# 根据半径计算圆的周长
8
def circle_perimeter(r):
9
    pi = 3.14
10
    perimeter = 2 * pi * r
11
    return perimeter

这个 circle_fun.py 文件就可以看作一个模块。

1.1.2. 为什么要使用模块#

当代码量比较少时，可以把所有代码写在一个文件中。

但是随着项目变复杂，如果所有代码都写在一个文件中，会出现以下问题：

1. 代码太长，不方便阅读。
2. 功能混在一起，不方便维护。
3. 相同功能无法复用。
4. 多人协作时容易互相影响。

使用模块可以把不同功能拆分到不同文件中，从而让代码结构更加清晰。

模块的主要作用如下：

1.1.3. 常见内置模块#

Python 提供了很多常用的内置模块，例如：

例如，使用 random 模块实现随机点名：

1
import random
2

3
names = [
4
    "王林", "李慕婉",
5
    "许立国", "韩立",
6
    "涛哥", "莫厉海",
7
    "十三", "虎咆",
8
    "红蝶", "天运子"
9
]
10

11
print(random.choice(names))

其中：

• import random 表示导入 random 模块。
• random.choice(names) 表示从列表中随机选择一个元素。

1.1.4. 模块导入的基本原则#

在使用模块中提供的功能之前，必须先导入模块。

也就是：

先导入，再使用。

模块导入语句一般写在 .py 文件的开头。

1.1.5. import 模块名#

第一种方式是直接导入模块。

语法：

1
import 模块名

示例：

1
import random
2

3
num = random.randint(10, 100)
4
print(num)

说明：

• import random 表示导入 random 模块。
• 调用模块中的功能时，需要使用 模块名.功能名 的形式。
• random.randint(10, 100) 表示生成 10 到 100 之间的随机整数。

也可以一次导入多个模块：

1
import random, os
2

3
print(random.randint(1, 10))
4
print(os.getcwd())

不过在实际开发中，更推荐分多行导入，代码更清晰：

1
import random
2
import os

1.1.6. import 模块名 as 别名#

如果模块名比较长，或者想让代码更简洁，可以给模块起别名。

语法：

1
import 模块名 as 别名

示例：

1
import random as rd
2

3
num = rd.randint(10, 100)
4
print(num)

说明：

• rd 是 random 模块的别名。
• 使用别名后，调用功能时要写 rd.randint()，不能再写 random.randint()。

1.1.7. from 模块名 import 功能名#

如果只想使用模块中的某几个功能，可以只导入指定功能。

语法：

1
from 模块名 import 功能名

示例：

1
from random import randint, choice
2

3
num = randint(10, 100)
4
print(num)
5

6
names = ["张三", "李四", "王五"]
7
print(choice(names))

说明：

• from random import randint, choice 表示从 random 模块中导入 randint 和 choice。
• 导入后可以直接使用功能名，不需要再写 random.。

1.1.8. from 模块名 import 功能名 as 别名#

也可以给导入的某个功能起别名。

语法：

1
from 模块名 import 功能名 as 别名

示例：

1
from random import randint as rint
2

3
num = rint(10, 100)
4
print(num)

说明：

• rint 是 randint 的别名。
• 使用别名后，直接调用 rint() 即可。

1.1.9. from 模块名 import *#

* 表示导入模块中的所有功能。

语法：

1
from 模块名 import *

示例：

1
from random import *
2

3
num = randint(10, 100)
4
print(num)
5

6
names = ["张三", "李四", "王五"]
7
print(choice(names))

这种写法虽然简洁，但是不推荐在大型项目中大量使用。

原因是：

1. 不容易看出某个功能来自哪个模块。
2. 容易造成命名冲突。
3. 不利于代码维护。

1.1.10. 模块导入方式总结#

常用语法可以概括为：

1
import 模块名 [as 别名]
2

3
from 模块名 import 功能名 [as 别名]
4

5
from 模块名 import *

1.2.1. 什么是自定义模块#

自定义模块就是程序员自己创建的 .py 文件。

在实际开发中，当项目比较复杂时，为了让代码结构更清晰、更便于维护和复用，通常会把一个项目拆分为多个模块。

例如，一个完整的项目中可能包含：

1
config.py
2
session.py
3
ai_partner.py

其中：

注意：

每一个 Python 文件都可以作为一个模块，模块名就是文件名。

例如：

1
circle_fun.py

这个模块的模块名就是：

1
circle_fun

导入时不要写 .py 后缀：

1
import circle_fun

1.2.2. 自定义模块命名规范#

自定义模块的文件名建议遵守 Python 标识符命名规范：

1. 使用英文、数字、下划线。
2. 不能以数字开头。
3. 不要使用 Python 关键字。
4. 建议全部小写。
5. 多个单词之间使用下划线连接。

推荐写法：

1
circle_fun.py
2
data_query.py
3
web_service.py
4
my_config.py

不推荐写法：

1
CircleFun.py
2
2test.py
3
my-module.py
4
class.py

1.2.3. 自定义模块示例#

假设有一个 circle_fun.py 文件，内容如下：

1
# 根据半径计算圆的面积
2
def circle_area(r):
3
    pi = 3.14
4
    area = pi * r * r
5
    return area
6

7
# 根据半径计算圆的周长
8
def circle_perimeter(r):
9
    pi = 3.14
10
    perimeter = 2 * pi * r
11
    return perimeter

然后在 main.py 中导入并使用：

1
import circle_fun
2

3
area = circle_fun.circle_area(10)
4
perimeter = circle_fun.circle_perimeter(10)
5

6
print(area)
7
print(perimeter)

输出结果：

1
314.0
2
62.800000000000004

也可以只导入指定功能：

1
from circle_fun import circle_area, circle_perimeter
2

3
area = circle_area(10)
4
perimeter = circle_perimeter(10)
5

6
print(area)
7
print(perimeter)

1.2.4. 项目拆分示例#

假设我们要开发一个“AI树洞”项目，如果把所有代码都写在一个文件中，代码会非常混乱。

可以把不同功能拆分到不同模块中。

1
PAGE_TITLE = "AI树洞"
2
PAGE_ICON = "🤖"
3
LAYOUT = "wide"
4
INITIAL_SIDEBAR_STATE = "expanded"
5
HELP_URL = "https://www.extremelycoolapp.com/help"
6
SESSION_LOCATION = "sessions/"

1
import os
2

3
def load_sessions():
4
    sessions = []
5
    if os.path.exists("sessions"):
6
        for filename in os.listdir("sessions"):
7
            if filename.endswith(".json"):
8
                sessions.append(filename[:-5])
9
    return sorted(sessions, reverse=True)
10

11
def save_session(session_name):
12
    if session_name:
13
        # 这里省略保存会话的具体逻辑
14
        pass

1
from session import load_sessions, save_session
2

3
# 新建会话按钮
4
if st.button("新建会话", icon="✏️", use_container_width=True):
5
    if st.session_state.current_session:
6
        save_session(st.session_state.current_session)
7

8
    new_session_name = generate_new_session_name()
9
    st.session_state.current_session = new_session_name
10
    st.session_state.messages = []
11

12
    save_session(new_session_name)
13
    st.session_state.sessions = load_sessions()
14
    st.rerun()

1.2.5. all 变量#

__all__ 是一个模块级别的特殊变量。

它的作用是：

控制 from 模块名 import * 时会导入哪些功能。

例如，创建一个 my.py 文件：

1
__all__ = ["log_separator1", "log_separator3", "PI"]
2

3
PI = 3.1415926
4
NAME = "黑马☆涛哥"
5

6
def log_separator1():
7
    print("- " * 30)
8

9
def log_separator2():
10
    print("+ " * 30)
11

12
def log_separator3():
13
    print("# " * 30)
14

15
def log_separator4():
16
    print("* " * 30)

然后在 test.py 中使用：

1
from my import *
2

3
log_separator1()
4
log_separator3()
5

6
print(PI)

此时可以使用：

1
log_separator1
2
log_separator3
3
PI

但是不能直接使用：

1
log_separator2
2
log_separator4
3
NAME

因为它们没有写在 __all__ 中。

1.2.6. all 的注意事项#

__all__ 只控制这种导入方式：

1
from 模块名 import *

它不会影响直接导入指定功能。

例如，即使 NAME 没有写入 __all__，下面这种写法仍然可以使用：

1
from my import NAME
2

3
print(NAME)

所以，__all__ 的作用并不是彻底隐藏模块中的功能，而是控制 import * 时通配导入的范围。

1.2.7. name 变量#

__name__ 是 Python 中非常重要的内置变量，表示当前模块的名称。

它有两种常见情况：

例如，创建一个 my.py 文件：

1
def test():
2
    print("这是测试代码")
3

4
print(__name__)

如果直接运行 my.py，输出结果是：

1
__main__

如果在其他文件中导入 my.py：

1
import my

此时 my.py 中的 __name__ 输出结果是：

1
my

1.2.8. if name == “main”#

在自定义模块中，经常会看到下面这种写法：

1
if __name__ == "__main__":
2
    # 测试代码
3
    pass

它的作用是：

只有当前文件被直接运行时，下面的代码才会执行；如果当前文件被其他模块导入，下面的代码不会执行。

示例：

1
def circle_area(r):
2
    return 3.14 * r * r
3

4
def circle_perimeter(r):
5
    return 2 * 3.14 * r
6

7
if __name__ == "__main__":
8
    print(circle_area(10))
9
    print(circle_perimeter(10))

这样写的好处是：

1. 可以在模块内部编写测试代码。
2. 测试代码不会在模块被导入时自动执行。
3. 更适合代码复用和项目开发。

1.2.9. 自定义模块小结#

自定义模块的核心要点如下：

1. 一个 .py 文件就是一个模块。
2. 模块名就是文件名，不包含 .py 后缀。
3. 模块中可以定义变量、函数、类和可执行代码。
4. 使用模块前需要先导入。
5. 自定义模块可以提高代码复用性和项目可维护性。
6. __all__ 用于控制 from 模块名 import * 时导入哪些功能。
7. __name__ 用于判断模块是被直接运行，还是被其他模块导入。

1.3.1. 为什么需要软件包#

当项目规模变大时，模块文件会越来越多。

例如，一个项目中可能有很多模块：

1
data_query.py
2
data_handle.py
3
data_model.py
4
data_analysis.py
5
web_routes.py
6
web_auth.py
7
helpers.py
8
file.py
9
format.py
10
token.py
11
log.py
12
web_service.py

如果所有模块都放在同一个目录下，就容易造成混乱，不方便管理和维护。

这时就可以使用软件包（package）来组织模块。

1.3.2. 什么是包#

包的本质是一个文件夹。

这个文件夹中可以包含多个 Python 模块，也就是多个 .py 文件。

同时，包文件夹下通常还会包含一个特殊文件：

1
__init__.py

因此，可以简单理解为：

包就是用来管理多个模块的文件夹。

例如：

1
utils/
2
    __init__.py
3
    my_var.py
4
    my_config.py
5
    my_fun.py

其中：

1.3.3. 包的作用#

包的主要作用是：

1. 管理多个模块。
2. 对模块进行分类。
3. 让项目结构更加清晰。
4. 提高代码维护性。
5. 避免模块过多造成混乱。

例如，可以按照功能把模块放入不同包中：

1
project/
2
    data/
3
        __init__.py
4
        data_query.py
5
        data_handle.py
6
        data_model.py
7

8
    web/
9
        __init__.py
10
        web_routes.py
11
        web_auth.py
12
        web_service.py
13

14
    utils/
15
        __init__.py
16
        file.py
17
        format.py
18
        log.py

这样就能清楚地区分数据处理、网页服务和工具函数等不同功能。

1.3.4. init.py 的作用#

__init__.py 是包中的特殊文件。

它的主要作用包括：

1. 标识当前文件夹是一个 Python 包。
2. 可以描述当前包的信息。
3. 可以编写包初始化代码。
4. 可以通过 __all__ 控制 from 包名 import * 时允许导入的模块列表。

例如，在 utils/__init__.py 中写入：

1
__all__ = ["my_fun", "my_var"]

表示当执行下面代码时：

1
from utils import *

只会导入：

1
my_fun
2
my_var

不会导入其他未写入 __all__ 的模块。

1.3.5. 包的导入方式1：import 包名.模块名#

语法：

1
import 包名.模块名

示例：

1
import utils.my_fun
2

3
utils.my_fun.log_separator1()

说明：

• utils 是包名。
• my_fun 是包中的模块名。
• 调用功能时，需要写完整路径：包名.模块名.功能名。

1.3.6. 包的导入方式2：from 包名 import 模块名#

语法：

1
from 包名 import 模块名

示例：

1
from utils import my_fun
2

3
my_fun.log_separator1()

说明：

• 从 utils 包中导入 my_fun 模块。
• 调用时可以直接使用 模块名.功能名。

1.3.7. 包的导入方式3：from 包名 import *#

语法：

1
from 包名 import *

示例：

1
from utils import *
2

3
my_fun.log_separator1()

注意：

使用 from 包名 import * 时，需要在包的 __init__.py 文件中添加 __all__，控制允许导入的模块列表。

例如：

1
__all__ = ["my_fun", "my_var"]

1.3.8. 包的导入方式4：from 包名.模块名 import 功能名#

语法：

1
from 包名.模块名 import 功能名

示例：

1
from utils.my_fun import log_separator1
2

3
log_separator1()

说明：

• 直接从包中的某个模块导入指定功能。
• 使用时可以直接调用功能名。

1.3.9. 包的导入方式5：from 包名.模块名 import *#

语法：

1
from 包名.模块名 import *

示例：

1
from utils.my_fun import *
2

3
log_separator1()

说明：

• 从包中的某个模块导入全部允许导入的功能。
• 如果模块内部定义了 __all__，则只导入 __all__ 中指定的功能。

1.3.10. 包的导入方式总结#

1.3.11. 包小结#

关于包，需要掌握以下内容：

1. 包本质上是一个文件夹。
2. 包中可以存放多个 Python 模块。
3. 包通常包含一个 __init__.py 文件。
4. __init__.py 可以标识这是一个包，而不是普通文件夹。
5. 当模块较多时，可以用包来分类管理模块。
6. from 包名 import * 时，可以通过 __init__.py 中的 __all__ 控制导入范围。