Python模块函数命名规范全解析

Python模块与函数命名远不止是风格选择，而是关乎代码可读性、工具兼容性、导入正确性乃至项目稳定性的关键实践：函数必须严格遵循snake_case（如calculate_total_price），模块名须全小写、无特殊字符且避免与内置名（如json、str）或标准库冲突，同时严禁使用双下划线命名非__init__.py文件——这些看似细微的规范一旦被忽视，轻则导致IDE补全失效、静态检查遗漏，重则引发静默覆盖、ImportError或运行时AttributeError，让问题深藏于“能跑但不对”的陷阱中。

Python 函数名必须用小写字母加下划线

Python 官方 PEP 8 明确要求函数名使用 snake_case，即全小写、单词间用单个下划线连接。这不是风格偏好，而是影响可读性和工具兼容性的硬性约定。

常见错误包括：getUserName（驼峰）、GET_USER_NAME（大写常量风格）、get_user__name（双下划线）、get-user-name（短横线，语法错误）。

• def calculate_total_price() ✅ 合理
• def CalculateTotalPrice() ❌ 类名风格，易与 class 混淆
• def _internal_helper() ✅ 单下划线前缀表示“受保护”，非公开
• def __private_method() ⚠️ 双下划线触发 name mangling，仅限真正私有逻辑

模块名要简短、全小写、无特殊字符

模块文件名即导入名，直接影响 import 语句和 IDE 补全。它必须是合法的 Python 标识符，且不能含点号、中划线或空格——否则会直接报错 ImportError: invalid syntax 或 ModuleNotFoundError。

典型问题场景：把 my-api-client.py 当模块导入，结果写 import my-api-client 导致语法错误；或用 2024_utils.py 开头数字导致无法导入。

• ✅ 正确命名：requests_cache.py → import requests_cache
• ✅ 正确命名：db_helpers.py → from db_helpers import connect
• ❌ 错误命名：data-v2.py（含短横线，文件可存但无法 import）
• ❌ 错误命名：1main.py（开头数字，标识符非法）

避免与内置函数或标准库模块重名

覆盖内置名（如 list、str、open）会导致后续调用异常，且 IDE 往往不报错，排查困难。同理，自定义模块命名为 json.py 或 os.py 会屏蔽标准库，引发不可预知行为。

例如：在项目根目录建了 json.py，再执行 import json，实际导入的是你本地那个空文件，而非标准库 json 模块，接着调用 json.loads(...) 就会抛 AttributeError。

• ⚠️ 高危重名：str.py、dict.py、time.py、math.py
• ✅ 安全替代：str_utils.py、dict_tools.py、time_helpers.py
• 检查是否冲突：运行 python -c "import json; print(json.__file__)" 看路径是否指向标准库

包内模块名不要用 __init__.py 以外的双下划线文件

Python 包机制依赖 __init__.py 触发识别，但其他以双下划线开头的模块（如 __main__.py、__version__.py）虽语法合法，却容易被误认为特殊文件而被某些打包工具（如 setuptools）忽略，或在 pip install -e . 时未正确包含。

更隐蔽的问题是：IDE 和静态分析工具（如 mypy）可能跳过这些文件的类型检查，导致 bug 潜伏。

• ✅ 推荐方式：version.py 存版本字符串，__init__.py 中 from .version import __version__
• ✅ 推荐方式：cli.py 放命令行入口，通过 if __name__ == "__main__": 控制执行
• ❌ 不推荐：__cli__.py、__utils__.py —— 无实际收益，徒增混淆

def get_version() -> str:
    return "1.2.3"
<h1>version.py —— 清晰、可导入、可测试、无歧义</h1>

模块和函数命名看着简单，真正卡住人的往往是那些“能跑但不对”的边界情况：比如名字合法却遮蔽了内置函数，或者文件名合法却让 import 走错了路径。留心这些细节比记住规则更重要。

到这里，我们也就讲完了《Python模块函数命名规范全解析》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！