全面解析 Python 常见代码文件后缀及其用途

from distutils.core import setup, Extension

module = Extension('myext', sources=['src/myext.c'])
setup(name='MyModule', ext_modules=[module])

运行 python setup.py build_ext --inplace 即可生成 .pyd 文件。

4. .pyi：类型提示存根文件

定义与作用

.pyi 文件是 Python 类型提示（Type Hints）的存根文件。它们不包含实现逻辑，仅定义函数签名、类结构和变量类型。主要用于静态类型检查工具（如 MyPy）和 IDE 智能提示。

示例代码

# hello.pyi
def hello(name: str) -> None:
    ...

当存在对应的 hello.py 时，IDE 会自动关联 .pyi 中的类型信息，即使 .py 文件中未显式标注类型。

适用场景

• 第三方库开发：发布不含源码的库时，提供 .pyi 供用户获取类型信息。
• 大型项目重构：逐步引入类型注解，降低迁移成本。

5. .ipynb：Jupyter Notebook 文件

定义与架构

.ipynb 是 Jupyter Notebook 的标准文件格式，本质上是 JSON 文档。它支持代码单元、Markdown 文本、数学公式及交互式图表的混合编排。广泛用于数据分析、机器学习原型验证及教学演示。

内核机制

Notebook 通过 Kernel 与后端 Python 解释器通信。用户输入的代码会被发送到 Kernel 执行，结果返回前端渲染。支持多语言内核，但 .ipynb 本身不绑定特定语言。

转换与导出

Notebook 可转换为 HTML、PDF、Markdown 或标准 .py 脚本：

jupyter nbconvert --to script notebook.ipynb

这有助于将实验性代码转化为生产环境脚本。

6. .pyw：无控制台窗口脚本

定义与场景

.pyw 是 Windows 特有的扩展名，用于运行 GUI 应用程序时不弹出命令行窗口。普通 .py 脚本双击运行时会在 CMD 中显示输出并等待关闭，而 .pyw 则隐藏该窗口。

技术原理

Python 解释器在加载 .pyw 文件时，会将标准输出重定向到空设备，避免控制台闪烁。适用于 Tkinter、PyQt 等图形界面应用。

示例代码

# app.pyw
import tkinter as tk

def on_click():
    label.config(text="Button Clicked!")

window = tk.Tk()
button = tk.Button(window, text="Click Me", command=on_click)
label = tk.Label(window, text="Hello")
button.pack()
label.pack()
window.mainloop()

注意：调试 .pyw 程序较为困难，建议配合日志记录而非打印输出。

7. .pyx：Cython 源代码文件

定义与优势

.pyx 是 Cython 语言的源代码扩展名。Cython 是一种静态类型超集语言，允许在 Python 语法中嵌入 C 代码。编译后可生成 C 扩展，显著提升执行速度。

编译流程

1. 编写 .pyx 文件，使用 cdef 声明局部变量类型。
2. 创建 setup.py 配置编译选项。
3. 运行 cythonize 生成 C 代码。
4. 编译 C 代码为 Python 扩展模块。

性能对比

在计算密集型任务中，Cython 相比纯 Python 有显著优势。以下是对比示例：

Cython 版本 (fb.pyx)

cdef int a, b, i
def fibonacci(n):
    if n <= 0:
        raise ValueError("n 必须是正整数")
    if n == 1:
        return 0
    elif n == 2:
        return 1
    else:
        a = 0
        b = 1
        for i in range(3, n + 1):
            a, b = b, a + b
        return b

纯 Python 版本 (run.py)

import timeit

def fibonacci(n):
    if n <= 0:
        raise ValueError("n 必须是正整数")
    if n == 1:
        return 0
    elif n == 2:
        return 1
    else:
        a, b = 0, 1
        for _ in range(3, n + 1):
            a, b = b, a + b
        return b

python_time = timeit.timeit("fibonacci(300)", setup="from __main__ import fibonacci", number=1000000)
print(f"纯 Python 版本执行时间：{python_time}")

测试结果

• 纯 Python 版本：约 12.39 秒
• Cython 版本：约 6.57 秒

在此场景下，Cython 效率提升近一倍。对于更复杂的数值计算，使用 @cython.boundscheck(False) 等装饰器可进一步优化。

8. 常见问题与解决方案

问题 1：导入 .pyd 失败

现象：ImportError: DLL load failed 原因：缺少依赖的动态链接库（DLL）或 Python 版本不匹配。 解决：确保所有依赖项已安装，且使用对应版本的 Python 构建扩展。

问题 2：.pyc 文件过大

现象：项目体积异常膨胀。 原因：__pycache__ 目录未被清理。 解决：定期删除 __pycache__ 文件夹，或在 .gitignore 中添加该路径。

问题 3：Cython 编译报错

现象：AttributeError: 'NoneType' object has no attribute '...' 原因：Cython 版本与 Python 版本不兼容。 解决：升级 Cython 至最新版本，并确保 setup.py 正确配置。

9. 总结与建议

选择合适的文件后缀取决于具体需求：

• 日常开发：使用 .py。
• 性能优化：考虑 .pyx 或 .pyd。
• 数据探索：使用 .ipynb。
• GUI 应用：使用 .pyw。
• 类型安全：配合 .pyi 使用。

在分发代码时，务必注意安全性。不要仅依赖字节码混淆保护核心逻辑，应结合许可证协议和法律手段。同时，保持代码的可维护性，优先选择开源透明的方案，便于团队协作与长期演进。

通过深入理解这些文件类型的底层机制，开发者可以更灵活地构建高效、安全且易于维护的 Python 生态系统。