#10454: clarify the compileall docs and help messages.
This commit is contained in:
R. David Murray
parent
a396463db3
commit
94f58c3a65
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -27,8 +27,8 @@ def compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None,
|
|||
|
||||
dir: the directory to byte-compile
|
||||
maxlevels: maximum recursion level (default 10)
|
||||
ddir: if given, purported directory name (this is the
|
||||
directory name that will show up in error messages)
|
||||
ddir: the directory that will be prepended to the path to the
|
||||
file as it is compiled into each byte-code file.
|
||||
force: if True, force compilation, even if timestamps are up-to-date
|
||||
quiet: if True, be quiet during compilation
|
||||
legacy: if True, produce legacy pyc paths instead of PEP 3147 paths
|
||||
|
|
@ -66,8 +66,8 @@ def compile_file(fullname, ddir=None, force=0, rx=None, quiet=False,
|
|||
legacy=False, optimize=-1):
|
||||
"""Byte-compile file.
|
||||
fullname: the file to byte-compile
|
||||
ddir: if given, purported directory name (this is the
|
||||
directory name that will show up in error messages)
|
||||
ddir: if given, the directory name compiled in to the
|
||||
byte-code file.
|
||||
force: if True, force compilation, even if timestamps are up-to-date
|
||||
quiet: if True, be quiet during compilation
|
||||
legacy: if True, produce legacy pyc paths instead of PEP 3147 paths
|
||||
|
|
@ -163,25 +163,32 @@ def main():
|
|||
|
||||
parser = argparse.ArgumentParser(
|
||||
description='Utilities to support installing Python libraries.')
|
||||
parser.add_argument('-l', action='store_const', default=10, const=0,
|
||||
dest='maxlevels', help="don't recurse down")
|
||||
parser.add_argument('-l', action='store_const', const=0,
|
||||
default=10, dest='maxlevels',
|
||||
help="don't recurse into subdirectories")
|
||||
parser.add_argument('-f', action='store_true', dest='force',
|
||||
help='force rebuild even if timestamps are up to date')
|
||||
parser.add_argument('-q', action='store_true', dest='quiet',
|
||||
help='reduce output')
|
||||
help='output only error messages')
|
||||
parser.add_argument('-b', action='store_true', dest='legacy',
|
||||
help='produce legacy byte-compiled file paths')
|
||||
help='use legacy (pre-PEP3147) compiled file locations')
|
||||
parser.add_argument('-d', metavar='DESTDIR', dest='ddir', default=None,
|
||||
help=('purported directory name for error messages; '
|
||||
'if no directory arguments, -l sys.path '
|
||||
'is assumed.'))
|
||||
help=('directory to prepend to file paths for use in '
|
||||
'compile time tracebacks and in runtime '
|
||||
'tracebacks in cases where the source file is '
|
||||
'unavailable'))
|
||||
parser.add_argument('-x', metavar='REGEXP', dest='rx', default=None,
|
||||
help=('skip files matching the regular expression.\n\t'
|
||||
help=('skip files matching the regular expression. '
|
||||
'The regexp is searched for in the full path '
|
||||
'of the file'))
|
||||
'to each file considered for compilation.'))
|
||||
parser.add_argument('-i', metavar='FILE', dest='flist',
|
||||
help='expand the list with the content of FILE.')
|
||||
parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*')
|
||||
help=('add all the files and directories listed in '
|
||||
'FILE to the list considered for compilation. '
|
||||
'If "-", names are read from stdin.'))
|
||||
parser.add_argument('compile_dest', metavar='FILE|DIR', nargs='*',
|
||||
help=('zero or more file and directory names '
|
||||
'to compile; if no arguments given, defaults '
|
||||
'to the equivalent of -l sys.path'))
|
||||
args = parser.parse_args()
|
||||
|
||||
compile_dests = args.compile_dest
|
||||
|
|
|
|||
Loading…
Reference in New Issue