From 930df3198746c0f718c7315c9ce331a306375867 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 16 Dec 2010 06:28:48 +0000 Subject: [PATCH] Add missing docs and directives related to PEP 3147 and byte-compilation --- Doc/c-api/import.rst | 3 +++ Doc/library/compileall.rst | 30 ++++++++++++++++++++++++++---- Doc/library/imp.rst | 4 ++-- Doc/library/py_compile.rst | 33 ++++++++++++++++++++------------- Doc/library/runpy.rst | 3 +++ 5 files changed, 54 insertions(+), 19 deletions(-) diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 15a11fd4bed..cf48363e105 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -142,6 +142,7 @@ Importing Modules attribute of the module object is set to *cpathname* if it is non-``NULL``. Of the three functions, this is the preferred one to use. + .. versionadded:: 3.2 .. c:function:: long PyImport_GetMagicNumber() @@ -155,6 +156,8 @@ Importing Modules Return the magic tag string for :pep:`3147` format Python bytecode file names. + .. versionadded:: 3.2 + .. c:function:: PyObject* PyImport_GetModuleDict() Return the dictionary used for the module administration (a.k.a. diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index 29041cdade3..53c3f0ab50c 100644 --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -54,8 +54,8 @@ compile Python sources. Write legacy ``.pyc`` file path names. Default is to write :pep:`3147`-style byte-compiled path names. -.. versionadded:: 3.2 - The ``-i`` and ``-b`` options. +.. versionchanged:: 3.2 + Added the ``-i``, ``-b`` and ``-h`` options. Public functions @@ -83,7 +83,29 @@ Public functions the built-in :func:`compile` function. .. versionchanged:: 3.2 - Added the *optimize* parameter. + Added the *legacy* and *optimize* parameter. + + +.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1) + + Compile the file with path *fullname*. If *ddir* is given, it is used as the + base path from which the filename used in error messages will be generated. + If *force* is true, modules are re-compiled even if the timestamp is up to + date. + + If *rx* is given, it specifies a regular expression which, if matched, will + prevent compilation; that expression is searched for in the full path. + + If *quiet* is true, nothing is printed to the standard output in normal + operation. + + If *legacy* is true, old-style ``.pyc`` file path names are written, + otherwise (the default), :pep:`3147`-style path names are written. + + *optimize* specifies the optimization level for the compiler. It is passed to + the built-in :func:`compile` function. + + .. versionadded:: 3.2 .. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1) @@ -94,7 +116,7 @@ Public functions function. .. versionchanged:: 3.2 - Added the *optimize* parameter. + Added the *legacy* and *optimize* parameter. To force a recompile of all the :file:`.py` files in the :file:`Lib/` diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst index 058e6b6a10e..398698f930e 100644 --- a/Doc/library/imp.rst +++ b/Doc/library/imp.rst @@ -190,8 +190,8 @@ This module provides an interface to the mechanisms used to implement the continue to use the old class definition. The same is true for derived classes. -The following functions and data provide conveniences for handling :pep:`3147` -byte-compiled file paths. +The following functions are conveniences for handling :pep:`3147` byte-compiled +file paths. .. versionadded:: 3.2 diff --git a/Doc/library/py_compile.rst b/Doc/library/py_compile.rst index b5b90107eca..d2e3208a656 100644 --- a/Doc/library/py_compile.rst +++ b/Doc/library/py_compile.rst @@ -24,25 +24,27 @@ byte-code cache files in the directory containing the source code. .. 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 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 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. *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 - Added the *optimize* parameter. + 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=None) @@ -51,6 +53,11 @@ byte-code cache files in the directory containing the source code. 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 diff --git a/Doc/library/runpy.rst b/Doc/library/runpy.rst index 896b65d44b5..10e5ebcec2d 100644 --- a/Doc/library/runpy.rst +++ b/Doc/library/runpy.rst @@ -70,6 +70,9 @@ The :mod:`runpy` module provides two functions: .. versionchanged:: 3.1 Added ability to execute packages by looking for a ``__main__`` submodule. + .. versionchanged:: 3.2 + Added ``__cached__`` global variable (see :PEP:`3147`). + .. function:: run_path(file_path, init_globals=None, run_name=None)