Python 文件名需要遵循一些基本规则，同时遵循一些行业公认的惯例，这会让你的代码更专业、更易读、更易维护。
硬性规则 (必须遵守)
这些是 Python 解释器和操作系统强制要求的规则,违反它们会导致程序无法运行或出现严重错误。
-
只能使用字母、数字和下划线 (
_)- 文件名中不能包含空格、特殊字符（如 , , , , ,
^,&, , , , , , , , ,[,], ,\, , , , ,<,>, , , 等）。 - 错误示例:
my script.py,data#1.py,user-info.py
- 文件名中不能包含空格、特殊字符（如 , , , , ,
-
不能以数字开头
- 文件名必须以字母或下划线开头。
- 错误示例:
123main.py,1test.py
-
区分大小写
- 在 Linux 和 macOS 等类 Unix 系统中，文件名是区分大小写的。
MyScript.py和myscript.py是两个不同的文件。 - 在 Windows 系统中，文件名默认不区分大小写，但强烈建议你始终按照区分大小写的方式来命名,以保证跨平台兼容性。
- 在 Linux 和 macOS 等类 Unix 系统中，文件名是区分大小写的。
-
避免使用 Python 的关键字
- 文件名不能与 Python 的保留关键字（如
if,else,for,while,class,def,try,import等）相同。 - 错误示例:
for.py,class.py
- 文件名不能与 Python 的保留关键字（如
-
避免使用与标准库或常用库名相同的名字
- 如果你的文件名和 Python 自带的标准库（如
os.py,sys.py,json.py）或你安装的第三方库（如requests.py,numpy.py）相同，你的程序将无法正确导入该库，Python 会优先导入当前目录下的文件,而不是已安装的库。 - 错误示例:
os.py,config.py(除非你确定这是你自己的配置模块)
- 如果你的文件名和 Python 自带的标准库（如
最佳实践与惯例 (强烈推荐)
这些是 Python 社区普遍遵循的约定,遵循它们能让你的代码更具可读性和协作性。
使用小写字母
- 推荐: 使用全小写字母。
- 示例:
utils.py,database_handler.py - 理由: 这是 PEP 8 (Python 官方风格指南) 的建议，简单、统一、不易出错。
使用下划线作为单词分隔符 (Snake Case)
- 推荐: 当文件名由多个单词组成时，用下划线 (
_) 分隔它们，这种命名方式被称为 "snake_case"。 - 示例:
user_profile.py,calculate_area.py,api_client.py - 理由: 这是 Python 中最常用、最推荐的命名方式,清晰易读。
模块文件名
- 推荐: 模块（
.py文件）的命名应该与其功能相关,并且通常是名词形式。 - 示例:
- 处理数据的模块:
data_processor.py - 存放用户相关函数的模块:
user_utils.py - 配置文件:
config.py
- 处理数据的模块:
脚本文件名
- 推荐: 如果一个文件是直接执行的脚本（而不是被导入的模块），其命名也应该清晰描述其功能,通常也使用小写和下划线。
- 示例:
- 一个数据清理脚本:
clean_data.py - 一个启动服务脚本:
run_server.py - 一个测试脚本:
test_main_feature.py
- 一个数据清理脚本:
包的目录名
- 推荐: 包的目录名遵循与模块文件名相同的规则：全小写,用下划线分隔。
- 示例:
my_project/,online_store/,payment_handlers/
特殊情况与高级用法
测试文件
- 惯例: 测试文件通常以
test_开头，或者以_test.py- 示例:
test_user_model.py,test_api_endpoints.py,user_model_test.py- 理由: 这样可以方便测试运行器（如
pytest,unittest）自动发现并执行测试。 - 示例:
C 扩展模块
- 惯例: 如果你的 Python 模块是用 C 语言编写的，文件名通常以
.c并且模块名前加下划线。 - 示例:
_socketmodule.c,_arraymodule.c
“隐藏”文件或私有模块
- 惯例: 如果一个模块或文件是私有的，仅供内部使用，可以在文件名前加上一个下划线 (
_)。 - 示例:
_internal.py,private_utils.py - 理由: 这是一种约定，告诉其他开发者“不要直接导入我”，虽然技术上仍然可以导入，但它表明这是一个实现细节,可能会在未来版本中改变。
总结表格
| 文件类型 | 命名规则 | 示例 |
|---|---|---|
| 普通模块 | 全小写，单词用下划线分隔 (snake_case) | utils.py, auth.py |
| 可执行脚本 | 全小写，单词用下划线分隔，描述其功能 | run_server.py, generate_report.py |
| 测试文件 | test_ 开头或 _test.py
| |
| 私有模块 | 文件名前加一个下划线 _ |
_internal.py, private_helper.py |
| 包目录 | 全小写，单词用下划线分隔 | my_project/, ecommerce/ |
| C 扩展 | 通常以 .c 模块名前加下划线 |
_socketmodule.c |
黄金法则：
清晰胜于简洁。 一个稍长但能清晰表达文件功能的名称，远胜于一个简短但令人困惑的名称,保持命名风格在整个项目中的一致性。
