diff options
Diffstat (limited to 'Doc/library/py_compile.rst')
| -rw-r--r-- | Doc/library/py_compile.rst | 44 |
1 files changed, 33 insertions, 11 deletions
diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index 0891862..07ddc25 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -8,6 +8,10 @@ .. index:: pair: file; byte-code +**Source code:** :source:`Lib/py_compile.py` + +-------------- + The :mod:`py_compile` module provides a function to generate a byte-code file from a source file, and another function used when the module source file is invoked as a script. @@ -22,24 +26,42 @@ byte-code cache files in the directory containing the source code. Exception raised when an error occurs while attempting to compile the file. -.. function:: compile(file[, cfile[, dfile[, doraise]]]) +.. function:: compile(file, cfile=None, dfile=None, doraise=False, optimize=-1) + + Compile a source file to byte-code and write out the byte-code cache file. + The source code is loaded from the file name *file*. The byte-code is + written to *cfile*, which defaults to the :PEP:`3147` path, ending in + ``.pyc`` (``.pyo`` if optimization is enabled in the current interpreter). + For example, if *file* is ``/foo/bar/baz.py`` *cfile* will default to + ``/foo/bar/__pycache__/baz.cpython-32.pyc`` for Python 3.2. If *dfile* is + specified, it is used as the name of the source file in error messages when + instead of *file*. If *doraise* is true, a :exc:`PyCompileError` is raised + when an error is encountered while compiling *file*. If *doraise* is false + (the default), an error string is written to ``sys.stderr``, but no exception + is raised. This function returns the path to byte-compiled file, i.e. + whatever *cfile* value was used. - Compile a source file to byte-code and write out the byte-code cache file. The - source code is loaded from the file name *file*. The byte-code is written to - *cfile*, which defaults to *file* ``+`` ``'c'`` (``'o'`` if optimization is - enabled in the current interpreter). If *dfile* is specified, it is used as the - name of the source file in error messages instead of *file*. If *doraise* is - true, a :exc:`PyCompileError` is raised when an error is encountered while - compiling *file*. If *doraise* is false (the default), an error string is - written to ``sys.stderr``, but no exception is raised. + *optimize* controls the optimization level and is passed to the built-in + :func:`compile` function. The default of ``-1`` selects the optimization + level of the current interpreter. + .. versionchanged:: 3.2 + Changed default value of *cfile* to be :PEP:`3147`-compliant. Previous + default was *file* + ``'c'`` (``'o'`` if optimization was enabled). + Also added the *optimize* parameter. -.. function:: main([args]) + +.. function:: main(args=None) Compile several source files. The files named in *args* (or on the command - line, if *args* is not specified) are compiled and the resulting bytecode is + line, if *args* is ``None``) are compiled and the resulting bytecode is cached in the normal manner. This function does not search a directory structure to locate source files; it only compiles files named explicitly. + If ``'-'`` is the only parameter in args, the list of files is taken from + standard input. + + .. versionchanged:: 3.2 + Added support for ``'-'``. When this module is run as a script, the :func:`main` is used to compile all the files named on the command line. The exit status is nonzero if one of the files |