32.10. "py_compile" --- 编译 Python 源文件
******************************************

**源代码:** Lib/py_compile.py

======================================================================

"py_compile" 模块提供了用来从源文件生成字节码的函数和另一个用于当模块
源文件作为脚本被调用时的函数。

虽然不太常用，但这个函数在安装共享模块时还是很有用的，特别是当一些用户
可能没有权限在包含源代码的目录中写字节码缓存文件时。

exception py_compile.PyCompileError

   当编译文件过程中发生错误时，抛出的异常。

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1)

   将源文件编译成字节码，并写出字节码缓存文件。源代码从名为 *file* 的
   文件中加载。 字节码写入 *cfile* ，默认为 **PEP 3147**/**PEP 488**
   路径，以 ".pyc" 结尾。例如，如果 *file* 是 "/foo/bar/baz.py" ，那么
   对于 Python 3.2，*cfile* 默认为
   "/foo/bar/__pycache__/baz.cpython-32.pyc" 。 如果指定了 *dfile* ，
   那么在错误信息中，它将代替 *file* 作为源文件的名称。 如果 *doraise*
   为true，当编译 *file* 遇到错误时，会抛出一个 "PyCompileError" 。如
   果 *doraise* 为 false (默认值)，错误字符串将写入 "sys.stderr" ，但
   不会抛出异常。 该函数返回编译后字节文件的路径，即 *cfile* 的值。

   如果 *cfile* 所表示（显式指定或计算得出）的路径为符号链接或非常规文
   件，则将引发 "FileExistsError"。 此行为是用来警告如果允许写入编译后
   字节码文件到这些路径则导入操作将会把它们转为常规文件。 这是使用文件
   重命名来将最终编译后字节码文件放置到位以防止并发文件写入问题的导入
   操作的附带效果。

   *optimize* 控制优化级别并会被传给内置的 "compile()" 函数。 默认值
   "-1" 表示选择当前解释器的优化级别。

   3.2 版更變: 将 *cfile* 的默认值改成与 **PEP 3147** 兼容。 之前的默
   认值是 *file* + "'c'" (如果启用优化则为 "'o'")。 同时也添加了
   *optimize* 形参。

   3.4 版更變: 将代码更改为使用 "importlib" 执行字节码缓存文件写入。
   这意味着文件创建/写入的语义现在与 "importlib" 所做的相匹配，例如权
   限、写入和移动语义等等。 同时也添加了当 *cfile* 为符号链接或非常规
   文件时引发 "FileExistsError" 的预警设置。

py_compile.main(args=None)

   编译多个源文件。 在 *args* 中（或者当 *args* 为 "None" 时则是在命令
   行中）指定的文件会被编译并将结果字节码以正常方式来缓存。 此函数不会
   搜索目录结构来定位源文件；它只编译显式指定的文件。 如果 "'-'" 是
   args 中唯一的值，则会从标准输入获取文件列表。

   3.2 版更變: 添加了对 "'-'" 的支持。

当此模块作为脚本运行时，会使用 "main()" 来编译命令行中指定的所有文件。
如果某个文件无法被编译则退出状态将为非零值。

也參考:

  模块 "compileall"
     编译一个目录树中所有 Python 源文件的工具。
