在 Python 中,模块通常就是一个以 .py 结尾的文件。文件里定义的变量、函数和类,都可以被其他 Python 文件导入和复用。
.py
你可以先把模块理解成一个有名字的代码文件:greeting.py 是一个模块,main.py 也是一个模块。模块名通常就是文件名去掉 .py 后的部分。
greeting.py
main.py
把代码拆成多个模块,有三个直接好处:
Python 自带的标准库和通过 uv 安装的第三方库,本质上也都是可以被导入的模块或模块集合。我们在 FastAPI 项目中导入 FastAPI,在 LangChain 项目中导入 ChatOpenAI,使用的就是同一套模块机制。
FastAPI
ChatOpenAI
先在项目根目录创建一个 greeting.py,在里面定义一个问候函数:
1def say_hello(name: str) -> str: 2 return f"你好,{name}!"
再创建 main.py,从 greeting 模块中导入这个函数:
greeting
1from greeting import say_hello 2 3message = say_hello("小微") 4print(message)
在项目根目录运行:
1uv run python main.py
程序会输出:
1你好,小微!
这句 from greeting import say_hello 可以拆成两部分理解:greeting 是模块名,say_hello 是要从模块中取出的函数。导入之后,main.py 就可以像使用本地函数一样调用它。
from greeting import say_hello
say_hello
我们来学习一下几种常见的导入模块的方式,第一种是导入整个模块
1import math 2 3radius = 3 4area = math.pi * radius ** 2 5print(area)
使用 import math 时,math 是一个模块对象。调用模块中的内容时,要写成 math.pi、math.sqrt(...) 这样的形式。这样写的好处是来源清楚:看到 math.sqrt 就知道这个函数来自 math 模块。
import math
math
math.pi
math.sqrt(...)
math.sqrt
第二种是只导入需要的内容
1from math import pi, sqrt 2 3radius = 3 4area = pi * radius ** 2 5distance = sqrt(16) 6print(area, distance)
这种写法可以少写一个模块前缀,但阅读代码时需要记住 pi 和 sqrt 从哪里来。导入内容较少、来源很明确时可以使用。
pi
sqrt
第三种是使用别名
1import datetime as dt 2 3today = dt.date.today() 4print(today)
as 为模块取一个更短的别名。别名只在当前模块有效,不会修改原模块的名字。常见的第三方库也会使用约定俗成的别名,例如 import numpy as np。
as
import numpy as np
还有一种通配导入写法,可以一次导入模块公开的名称:
1from math import *
import * 会把模块中的许多名字直接放进当前文件。这样虽然少写了前缀,却会让人很难判断一个名字来自哪里,还可能覆盖当前文件中已有的变量。实际项目中,优先使用 import math 或明确列出 from math import sqrt
import *
from math import sqrt
Python 没有 export 关键字。模块顶层的定义,以及实际执行到的赋值和导入,会把名称放进模块的命名空间中,因此其他代码可以显式导入这些名称。定义在函数内部的局部变量则不属于模块的公开名称。
export
1DEFAULT_GREETING = "你好" 2 3def say_hello(name: str) -> str: 4 return f"{DEFAULT_GREETING},{name}!" 5 6class Greeter: 7 def greet(self, name: str) -> str: 8 return say_hello(name)
上面的 DEFAULT_GREETING、say_hello 和 Greeter 都可以被导入:
DEFAULT_GREETING
Greeter
1from greeting import DEFAULT_GREETING, Greeter, say_hello 2 3print(DEFAULT_GREETING) 4print(say_hello("小微")) 5print(Greeter().greet("小明"))
所以,通常不需要额外声明「哪些内容可以导出」。只要名称存在于模块的顶层命名空间,就可以通过 from module import name 这种方式导入。这里的「导出」更准确地说,是其他模块能够访问当前模块的公开名称。
from module import name
用下划线表示内部实现
如果某个函数或变量只想作为模块内部的辅助实现,可以给它加一个前导下划线:
1def _normalize_name(name: str) -> str: 2 return name.strip() 3 4def say_hello(name: str) -> str: 5 return f"你好,{_normalize_name(name)}!"
前导下划线主要是一种约定,表示「这是内部使用的名称」。它不会真正阻止别人显式导入,下面的写法仍然可以工作:
1from greeting import _normalize_name
因此,下划线是可读性和协作约定,不是访问权限控制。
用 __all__ 控制通配导入
__all__
如果确实需要控制 from greeting import * 能够导入哪些名称,可以在模块中定义 __all__:
from greeting import *
1__all__ = ["DEFAULT_GREETING", "say_hello"] 2 3DEFAULT_GREETING = "你好" 4 5def say_hello(name: str) -> str: 6 return f"{DEFAULT_GREETING},{name}!" 7 8def _normalize_name(name: str) -> str: 9 return name.strip()
此时执行 from greeting import * 时,只会导入 __all__ 中列出的两个名称。没有定义 __all__ 时,通配导入通常会排除以下划线开头的名称。__all__ 不会阻止显式导入,也不会提供真正的权限控制;它主要用于约定模块的公开 API。实际项目中仍然建议显式导入名称,而不是依赖通配导入。
当 Python 第一次导入一个模块时,会创建模块对象,把它登记到 sys.modules 缓存中,再执行模块的顶层代码。成功加载后,再次导入同一个模块通常会复用缓存;如果加载失败,导入系统会移除这次加载失败的模块。
sys.modules
因此,模块的顶层位置适合放函数、类和常量定义,不适合放会在导入时自动执行的业务操作。例如,下面的打印语句会在同一个解释器第一次导入 greeting 时执行;后续普通导入通常会复用缓存,不会重复打印:
1print("greeting 模块正在加载") 2 3def say_hello(name: str) -> str: 4 return f"你好,{name}!"
更常见的做法是把可执行逻辑放进函数中,需要时再调用。这样可以让导入过程主要用于准备定义,避免在导入时启动服务、发送请求或修改数据。
另外,同一个 Python 文件既可以被直接运行,也可以被其他文件导入。Python 会根据使用方式设置特殊变量 __name__,来区分这两种情况:
__name__
python main.py
"__main__"
"greeting"
"app.agent"
利用这个差异,可以让一个模块同时支持「被导入」和「直接运行」两种方式:
1def say_hello(name: str) -> str: 2 return f"你好,{name}!" 3 4def main() -> None: 5 print(say_hello("小微")) 6 7if __name__ == "__main__": 8 main()
当执行 uv run python greeting.py 时,main() 会被调用;当 main.py 导入 say_hello 时,main() 不会自动执行。这一层判断是 Python 模块中非常常见的结构。
uv run python greeting.py
main()
当项目中的模块越来越多时,可以用包把相关模块组织在同一个目录中。对于初学者,可以先把包理解成「用目录组织起来的一组模块」。
例如,我们可以把项目整理成下面这样:
__init__.py 可以是空文件,它的作用是明确告诉 Python:这个目录可以作为一个包来组织代码。现代 Python 也支持不放这个文件的命名空间包,但在学习和普通应用项目中保留它更直观。
__init__.py
假设 prompts.py 中定义了一个提示词:
prompts.py
1SYSTEM_PROMPT = "你是一名温和、可靠的助手。"
在项目根目录的 main.py 中,可以使用包路径导入:
1from app.prompts import SYSTEM_PROMPT 2 3print(SYSTEM_PROMPT)
app.prompts 表示先找到 app 包,再找到其中的 prompts 模块。使用完整的包路径,能够让代码的来源更加清楚。
app.prompts
app
prompts
前面文章里的 main.py 为了方便入门,把 FastAPI、模型和 Agent 都写在了同一个文件。这一篇沿用相同的服务,再把问候函数、模型配置、提示词和 Agent 按职责放进不同模块。
切换到在线案例后,可以先点击运行,再发送默认的 GET /hello?name=小微。这个接口只调用项目中的问候模块,保留 xxxx 密钥也能使用。确认模块导入正常后,再配置模型并调用 /chat。
GET /hello?name=小微
xxxx
/chat
把前面介绍的常量、内部函数、类和 __name__ 判断组合成一个完整的 greeting.py:
01__all__ = ["DEFAULT_GREETING", "say_hello", "Greeter"] 02 03DEFAULT_GREETING = "你好" 04 05def _normalize_name(name: str) -> str: 06 return name.strip() or "朋友" 07 08def say_hello(name: str) -> str: 09 return f"{DEFAULT_GREETING},{_normalize_name(name)}!" 10 11class Greeter: 12 def greet(self, name: str) -> str: 13 return say_hello(name) 14 15def main() -> None: 16 print(say_hello("小微")) 17 18if __name__ == "__main__": 19 main()
_normalize_name 会去掉名字两端的空格,空名字则使用「朋友」。Greeter 复用同一个问候函数;显式导入 Greeter 或 say_hello 都不会触发最后的 main()。
_normalize_name
模型模块负责读取配置,并提供创建模型的函数。导入这个模块时只定义函数,等真正调用它时才读取环境变量:
01import os 02 03from langchain_openai import ChatOpenAI 04 05def create_model() -> ChatOpenAI: 06 return ChatOpenAI( 07 model=os.environ["DEEPSEEK_MODEL"], 08 api_key=os.environ["DEEPSEEK_API_KEY"], 09 base_url=os.environ.get("DEEPSEEK_BASE_URL", "https://api.deepseek.com"), 10 )
提示词也可以是独立模块里的常量。创建 app/prompts.py,写入:
app/prompts.py
1SYSTEM_PROMPT = "你是一名温和、可靠的 Python 学习助手。"
创建 app/agent.py,通过包内的相对导入组合模型和提示词:
app/agent.py
01from functools import cache 02 03from langchain.agents import create_agent 04 05from .model import create_model 06from .prompts import SYSTEM_PROMPT 07 08@cache 09def get_agent(): 10 return create_agent( 11 model=create_model(), 12 system_prompt=SYSTEM_PROMPT, 13 )
这里的点号表示相对当前包导入。agent.py、model.py 和 prompts.py 都在 app 包中,因此 from .model import create_model 可以找到同一个包里的模型模块。
agent.py
model.py
from .model import create_model
get_agent() 在第一次调用时才创建模型和 Agent。标准库的 @cache 会保存返回值,后续请求复用同一个 Agent;重新运行在线项目后,模块会重新加载,缓存也重新建立。这种做法避免了仅仅导入模块就创建模型实例。
get_agent()
@cache
相对导入需要包上下文,因此应从项目根目录启动 main.py,不要直接执行 python app/agent.py。需要单独执行包内模块时,可使用 uv run python -m app.agent;当前模块只定义函数,单独执行它不会自动发送模型请求。
python app/agent.py
uv run python -m app.agent
FastAPI 入口负责接收请求和返回响应。/hello 使用问候模块,/chat 则在收到问题后调用 Agent:
/hello
01from fastapi import FastAPI 02from pydantic import BaseModel 03 04from app.agent import get_agent 05from greeting import DEFAULT_GREETING, Greeter 06 07app = FastAPI() 08 09class ChatRequest(BaseModel): 10 question: str 11 12@app.get("/hello") 13async def hello(name: str = "小微") -> dict[str, str]: 14 return { 15 "message": Greeter().greet(name), 16 "default_greeting": DEFAULT_GREETING, 17 } 18 19@app.post("/chat") 20async def chat(request: ChatRequest) -> dict[str, str]: 21 result = await get_agent().ainvoke({ 22 "messages": [{"role": "user", "content": request.question}], 23 }) 24 return {"answer": result["messages"][-1].content}
此时模块依赖可以顺着代码读出来:main 导入 greeting 和 app.agent,app.agent 再导入 app.model 和 app.prompts。这些模块都不需要反过来导入 main,可以避免这组文件之间产生循环导入。
main
app.agent
app.model
在线案例默认发送 GET /hello?name=小微,返回:
1{ 2 "message": "你好,小微!", 3 "default_greeting": "你好" 4}
我们可以把 greeting.py 中的 DEFAULT_GREETING 改成 "欢迎",保存后重新运行,再发送请求。返回的问候语和常量都会变化,这就能看到入口如何复用另一个模块里的最新定义。
"欢迎"
调用模型之前,打开项目里的 .env:
.env
1DEEPSEEK_MODEL=deepseek-v4-flash 2DEEPSEEK_BASE_URL=https://api.deepseek.com 3# 请将 xxxx 替换为你自己的 DeepSeek API Key,保存后重新运行。 4DEEPSEEK_API_KEY=xxxx
将 DEEPSEEK_API_KEY 的 xxxx 替换为自己的密钥,保存并重新运行。然后把请求方法改成 POST、地址改成 /chat,请求体填写:
DEEPSEEK_API_KEY
POST
1{"question": "请用一句话介绍 Python 模块。"}
这个接口会使用真实的 LangChain create_agent 和 LangGraph ainvoke 执行图,再返回模型的回答。.env.example 只保留占位符,不要把真实密钥写进去或提交到 Git。
create_agent
ainvoke
.env.example
下载案例后,在项目根目录执行下面的命令启动本机服务:
1uv run --env-file .env fastapi dev main.py
然后发送请求:
1curl "http://127.0.0.1:8000/hello?name=Python" 2 3curl -X POST http://127.0.0.1:8000/chat \ 4 -H "Content-Type: application/json" \ 5 -d '{"question":"请用一句话介绍 Python 模块。"}'
浏览器案例会先加载 .env,再导入 main:app,通过内存中的 FastAPI 应用处理请求,不运行上述终端命令或监听本机端口。此时 main.py 的 __name__ 是 "main",因此不要把 FastAPI 路由定义放进 if __name__ == "__main__" 中。greeting.py 中的独立运行示例仍可以在本机通过 uv run python greeting.py 执行。
main:app
"main"
if __name__ == "__main__"
依赖声明在 pyproject.toml 中,在线案例复用前一篇已经适配浏览器的版本组合。相同依赖的下载缓存可以在本站文章之间复用,本篇的代码草稿和日志则独立保存。模型地址还需要允许网站的跨域请求;这里使用异步 ainvoke,以适配浏览器 Python 运行环境。
pyproject.toml
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 概述
在 Python 中,模块通常就是一个以
.py结尾的文件。文件里定义的变量、函数和类,都可以被其他 Python 文件导入和复用。你可以先把模块理解成一个有名字的代码文件:
greeting.py是一个模块,main.py也是一个模块。模块名通常就是文件名去掉.py后的部分。把代码拆成多个模块,有三个直接好处:
Python 自带的标准库和通过 uv 安装的第三方库,本质上也都是可以被导入的模块或模块集合。我们在 FastAPI 项目中导入
FastAPI,在 LangChain 项目中导入ChatOpenAI,使用的就是同一套模块机制。2. 创建第一个模块
先在项目根目录创建一个
greeting.py,在里面定义一个问候函数:再创建
main.py,从greeting模块中导入这个函数:在项目根目录运行:
程序会输出:
这句
from greeting import say_hello可以拆成两部分理解:greeting是模块名,say_hello是要从模块中取出的函数。导入之后,main.py就可以像使用本地函数一样调用它。3. 导入模块
我们来学习一下几种常见的导入模块的方式,第一种是导入整个模块
使用
import math时,math是一个模块对象。调用模块中的内容时,要写成math.pi、math.sqrt(...)这样的形式。这样写的好处是来源清楚:看到math.sqrt就知道这个函数来自math模块。第二种是只导入需要的内容
这种写法可以少写一个模块前缀,但阅读代码时需要记住
pi和sqrt从哪里来。导入内容较少、来源很明确时可以使用。第三种是使用别名
as为模块取一个更短的别名。别名只在当前模块有效,不会修改原模块的名字。常见的第三方库也会使用约定俗成的别名,例如import numpy as np。还有一种通配导入写法,可以一次导入模块公开的名称:
import *会把模块中的许多名字直接放进当前文件。这样虽然少写了前缀,却会让人很难判断一个名字来自哪里,还可能覆盖当前文件中已有的变量。实际项目中,优先使用import math或明确列出from math import sqrt4. 导出
Python 没有
export关键字。模块顶层的定义,以及实际执行到的赋值和导入,会把名称放进模块的命名空间中,因此其他代码可以显式导入这些名称。定义在函数内部的局部变量则不属于模块的公开名称。上面的
DEFAULT_GREETING、say_hello和Greeter都可以被导入:所以,通常不需要额外声明「哪些内容可以导出」。只要名称存在于模块的顶层命名空间,就可以通过
from module import name这种方式导入。这里的「导出」更准确地说,是其他模块能够访问当前模块的公开名称。用下划线表示内部实现
如果某个函数或变量只想作为模块内部的辅助实现,可以给它加一个前导下划线:
前导下划线主要是一种约定,表示「这是内部使用的名称」。它不会真正阻止别人显式导入,下面的写法仍然可以工作:
因此,下划线是可读性和协作约定,不是访问权限控制。
用
__all__控制通配导入如果确实需要控制
from greeting import *能够导入哪些名称,可以在模块中定义__all__:此时执行
from greeting import *时,只会导入__all__中列出的两个名称。没有定义__all__时,通配导入通常会排除以下划线开头的名称。__all__不会阻止显式导入,也不会提供真正的权限控制;它主要用于约定模块的公开 API。实际项目中仍然建议显式导入名称,而不是依赖通配导入。5. 机制剖析
当 Python 第一次导入一个模块时,会创建模块对象,把它登记到
sys.modules缓存中,再执行模块的顶层代码。成功加载后,再次导入同一个模块通常会复用缓存;如果加载失败,导入系统会移除这次加载失败的模块。因此,模块的顶层位置适合放函数、类和常量定义,不适合放会在导入时自动执行的业务操作。例如,下面的打印语句会在同一个解释器第一次导入
greeting时执行;后续普通导入通常会复用缓存,不会重复打印:更常见的做法是把可执行逻辑放进函数中,需要时再调用。这样可以让导入过程主要用于准备定义,避免在导入时启动服务、发送请求或修改数据。
另外,同一个 Python 文件既可以被直接运行,也可以被其他文件导入。Python 会根据使用方式设置特殊变量
__name__,来区分这两种情况:python main.py时,__name__的值是"__main__";__name__的值是导入使用的模块名,例如"greeting";包内模块则可能是"app.agent"。利用这个差异,可以让一个模块同时支持「被导入」和「直接运行」两种方式:
当执行
uv run python greeting.py时,main()会被调用;当main.py导入say_hello时,main()不会自动执行。这一层判断是 Python 模块中非常常见的结构。6. 从模块到包
当项目中的模块越来越多时,可以用包把相关模块组织在同一个目录中。对于初学者,可以先把包理解成「用目录组织起来的一组模块」。
例如,我们可以把项目整理成下面这样:
__init__.py可以是空文件,它的作用是明确告诉 Python:这个目录可以作为一个包来组织代码。现代 Python 也支持不放这个文件的命名空间包,但在学习和普通应用项目中保留它更直观。假设
prompts.py中定义了一个提示词:在项目根目录的
main.py中,可以使用包路径导入:app.prompts表示先找到app包,再找到其中的prompts模块。使用完整的包路径,能够让代码的来源更加清楚。7. 在 FastAPI 和 LangChain 中拆分模块
前面文章里的
main.py为了方便入门,把 FastAPI、模型和 Agent 都写在了同一个文件。这一篇沿用相同的服务,再把问候函数、模型配置、提示词和 Agent 按职责放进不同模块。切换到在线案例后,可以先点击运行,再发送默认的
GET /hello?name=小微。这个接口只调用项目中的问候模块,保留xxxx密钥也能使用。确认模块导入正常后,再配置模型并调用/chat。7.1 准备问候模块
把前面介绍的常量、内部函数、类和
__name__判断组合成一个完整的greeting.py:_normalize_name会去掉名字两端的空格,空名字则使用「朋友」。Greeter复用同一个问候函数;显式导入Greeter或say_hello都不会触发最后的main()。7.2 拆分模型和提示词
模型模块负责读取配置,并提供创建模型的函数。导入这个模块时只定义函数,等真正调用它时才读取环境变量:
提示词也可以是独立模块里的常量。创建
app/prompts.py,写入:7.3 组装 Agent
创建
app/agent.py,通过包内的相对导入组合模型和提示词:这里的点号表示相对当前包导入。
agent.py、model.py和prompts.py都在app包中,因此from .model import create_model可以找到同一个包里的模型模块。get_agent()在第一次调用时才创建模型和 Agent。标准库的@cache会保存返回值,后续请求复用同一个 Agent;重新运行在线项目后,模块会重新加载,缓存也重新建立。这种做法避免了仅仅导入模块就创建模型实例。相对导入需要包上下文,因此应从项目根目录启动
main.py,不要直接执行python app/agent.py。需要单独执行包内模块时,可使用uv run python -m app.agent;当前模块只定义函数,单独执行它不会自动发送模型请求。7.4 保留服务入口
FastAPI 入口负责接收请求和返回响应。
/hello使用问候模块,/chat则在收到问题后调用 Agent:此时模块依赖可以顺着代码读出来:
main导入greeting和app.agent,app.agent再导入app.model和app.prompts。这些模块都不需要反过来导入main,可以避免这组文件之间产生循环导入。7.5 运行与修改
在线案例默认发送
GET /hello?name=小微,返回:我们可以把
greeting.py中的DEFAULT_GREETING改成"欢迎",保存后重新运行,再发送请求。返回的问候语和常量都会变化,这就能看到入口如何复用另一个模块里的最新定义。调用模型之前,打开项目里的
.env:将
DEEPSEEK_API_KEY的xxxx替换为自己的密钥,保存并重新运行。然后把请求方法改成POST、地址改成/chat,请求体填写:这个接口会使用真实的 LangChain
create_agent和 LangGraphainvoke执行图,再返回模型的回答。.env.example只保留占位符,不要把真实密钥写进去或提交到 Git。下载案例后,在项目根目录执行下面的命令启动本机服务:
然后发送请求:
浏览器案例会先加载
.env,再导入main:app,通过内存中的 FastAPI 应用处理请求,不运行上述终端命令或监听本机端口。此时main.py的__name__是"main",因此不要把 FastAPI 路由定义放进if __name__ == "__main__"中。greeting.py中的独立运行示例仍可以在本机通过uv run python greeting.py执行。依赖声明在
pyproject.toml中,在线案例复用前一篇已经适配浏览器的版本组合。相同依赖的下载缓存可以在本站文章之间复用,本篇的代码草稿和日志则独立保存。模型地址还需要允许网站的跨域请求;这里使用异步ainvoke,以适配浏览器 Python 运行环境。