mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-04 00:48:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

#10454: clarify the compileall docs and help messages.

Browse source
This commit is contained in:
R. David Murray 2010-12-17 16:29:07 +00:00
parent a396463db3
commit 94f58c3a65
2 changed files with 85 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

95
Doc/library/compileall.rst
View file

@ -6,9 +6,10 @@
This module provides some utility functions to support installing Python
libraries. These functions compile Python source files in a directory tree,
allowing users without permission to write to the libraries to take advantage of
cached byte-code files.
libraries. These functions compile Python source files in a directory tree.
This module can be used to create the cached byte-code files at library
installation time, which makes them available for use even by users who don't
have write permission to the library directories.
Command-line use
@ -27,7 +28,8 @@ compile Python sources.
.. cmdoption:: -l
Do not recurse.
Do not recurse into subdirectories, only compile source code files directly
contained in the named or implied directories.
.. cmdoption:: -f
@ -35,24 +37,33 @@ compile Python sources.
.. cmdoption:: -q
Do not print the list of files compiled.
Do not print the list of files compiled, print only error messages.
.. cmdoption:: -d destdir
Purported directory name for error messages.
Directory prepended to the path to each file being compiled. This will
appear in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
.. cmdoption:: -x regex
Skip files with a full path that matches given regular expression.
regex is used to search the full path to each file considered for
compilation, and if the regex produces a match, the file is skipped.
.. cmdoption:: -i list
Expand list with its content (file and directory names).
Read the file ``list`` and add each line that it contains to the list of
files and directories to compile. If ``list`` is ``-``, read lines from
``stdin``.
.. cmdoption:: -b
Write legacy ``.pyc`` file path names. Default is to write :pep:`3147`-style
byte-compiled path names.
Write the byte-code files to their legacy locations and names, which may
overwrite byte-code files created by another version of Python. The default
is to write files to their :pep:`3147` locations and names, which allows
byte-code files from multiple versions of Python to coexist.
.. versionchanged:: 3.2
Added the ``-i``, ``-b`` and ``-h`` options.
@ -64,20 +75,32 @@ Public functions
.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=False, legacy=False, optimize=-1)
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. The *maxlevels* parameter is used to limit the depth of
the recursion; it defaults to ``10``. If *ddir* is given, it is used as the
base path from which the filenames used in error messages will be generated.
files along the way.
The *maxlevels* parameter is used to limit the depth of the recursion; it
defaults to ``10``.
If *ddir* is given, it is prepended to the path to each file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *force* is true, modules are re-compiled even if the timestamps are up to
date.
If *rx* is given, it specifies a regular expression of file names to exclude
from the search; that expression is searched for in the full path.
If *rx* is given, its search method is called on the complete path to each
file considered for compilation, and if it returns a true value, the file
is skipped.
If *quiet* is true, nothing is printed to the standard output in normal
operation.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
If *legacy* is true, old-style ``.pyc`` file path names are written,
otherwise (the default), :pep:`3147`-style path names are written.
If *legacy* is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python. The default is to write files to their :pep:`3147` locations and
names, which allows byte-code files from multiple versions of Python to
coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
@ -88,19 +111,26 @@ Public functions
.. 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.
Compile the file with path *fullname*.
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 *ddir* is given, it is prepended to the path to the file being compiled
for use in compilation time tracebacks, and is also compiled in to the
byte-code file, where it will be used in tracebacks and other messages in
cases where the source file does not exist at the time the byte-code file is
executed.
If *quiet* is true, nothing is printed to the standard output in normal
operation.
If *ra* is given, its search method is passed the full path name to the
file being compiled, and if it returns a true value, the file is not
compiled and ``True`` is returned.
If *legacy* is true, old-style ``.pyc`` file path names are written,
otherwise (the default), :pep:`3147`-style path names are written.
If *quiet* is true, nothing is printed to the standard output unless errors
occur.
If *legacy* is true, byte-code files are written to their legacy locations
and names, which may overwrite byte-code files created by another version of
Python. The default is to write files to their :pep:`3147` locations and
names, which allows byte-code files from multiple versions of Python to
coexist.
*optimize* specifies the optimization level for the compiler. It is passed to
the built-in :func:`compile` function.
@ -111,9 +141,10 @@ Public functions
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, legacy=False, optimize=-1)
Byte-compile all the :file:`.py` files found along ``sys.path``. If
*skip_curdir* is true (the default), the current directory is not included in
the search. All other parameters are passed to the :func:`compile_dir`
function.
*skip_curdir* is true (the default), the current directory is not included
in the search. All other parameters are passed to the :func:`compile_dir`
function. Note that unlike the other compile functions, ``maxlevels``
defaults to ``0``.
.. versionchanged:: 3.2
Added the *legacy* and *optimize* parameter.