bpo-38112: Compileall improvements (GH-16012)
* Raise the limit of maximum path depth to actual recursion limit
* Add posibilities to adjust a path compiled in .pyc file.
Now, you can:
- Strip a part of path from a beggining of path into compiled file
example "-s /test /test/build/real/test.py" → "build/real/test.py"
- Append some new path to a beggining of path into compiled file
example "-p /boo real/test.py" → "/boo/real/test.py"
You can also use both options in the same time. In that case,
striping is done before appending.
* Add a possibility to specify multiple optimization levels
Each optimization level then leads to separated compiled file.
Use `action='append'` instead of `nargs='+'` for the -o option.
Instead of `-o 0 1 2`, specify `-o 0 -o 1 -o 2`. It's more to type,
but much more explicit.
* Add a symlinks limitation feature
This feature allows us to limit byte-compilation of symbolic
links if they are pointing outside specified dir (build root
for example).
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst
index 9ce5ca8..394d606 100644
--- a/Doc/library/compileall.rst
+++ b/Doc/library/compileall.rst
@@ -52,6 +52,13 @@
cases where the source file does not exist at the time the byte-code file is
executed.
+.. cmdoption:: -s strip_prefix
+.. cmdoption:: -p prepend_prefix
+
+ Remove (``-s``) or append (``-p``) the given prefix of paths
+ recorded in the ``.pyc`` files.
+ Cannot be combined with ``-d``.
+
.. cmdoption:: -x regex
regex is used to search the full path to each file considered for
@@ -96,6 +103,16 @@
variable is not set, and ``checked-hash`` if the ``SOURCE_DATE_EPOCH``
environment variable is set.
+.. cmdoption:: -o level
+
+ Compile with the given optimization level. May be used multiple times
+ to compile for multiple levels at a time (for example,
+ ``compileall -o 1 -o 2``).
+
+.. cmdoption:: -e dir
+
+ Ignore symlinks pointing outside the given directory.
+
.. versionchanged:: 3.2
Added the ``-i``, ``-b`` and ``-h`` options.
@@ -107,6 +124,12 @@
.. versionchanged:: 3.7
Added the ``--invalidation-mode`` option.
+.. versionchanged:: 3.9
+ Added the ``-s``, ``-p``, ``-e`` options.
+ Raised the default recursion limit from 10 to
+ :py:func:`sys.getrecursionlimit()`.
+ Added the possibility to specify the ``-o`` option multiple times.
+
There is no command-line option to control the optimization level used by the
:func:`compile` function, because the Python interpreter itself already
@@ -120,7 +143,7 @@
Public functions
----------------
-.. function:: compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)
+.. function:: compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None, stripdir=None, prependdir=None, limit_sl_dest=None)
Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
files along the way. Return a true value if all the files compiled successfully,
@@ -166,6 +189,10 @@
:class:`py_compile.PycInvalidationMode` enum and controls how the generated
pycs are invalidated at runtime.
+ The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to
+ the ``-s``, ``-p`` and ``-e`` options described above.
+ They may be specified as ``str``, ``bytes`` or :py:class:`os.PathLike`.
+
.. versionchanged:: 3.2
Added the *legacy* and *optimize* parameter.
@@ -191,6 +218,9 @@
.. versionchanged:: 3.8
Setting *workers* to 0 now chooses the optimal number of cores.
+ .. versionchanged:: 3.9
+ Added *stripdir*, *prependdir* and *limit_sl_dest* arguments.
+
.. function:: compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
Compile the file with path *fullname*. Return a true value if the file
@@ -223,6 +253,10 @@
:class:`py_compile.PycInvalidationMode` enum and controls how the generated
pycs are invalidated at runtime.
+ The *stripdir*, *prependdir* and *limit_sl_dest* arguments correspond to
+ the ``-s``, ``-p`` and ``-e`` options described above.
+ They may be specified as ``str``, ``bytes`` or :py:class:`os.PathLike`.
+
.. versionadded:: 3.2
.. versionchanged:: 3.5
@@ -238,6 +272,9 @@
.. versionchanged:: 3.7.2
The *invalidation_mode* parameter's default value is updated to None.
+ .. versionchanged:: 3.9
+ Added *stripdir*, *prependdir* and *limit_sl_dest* arguments.
+
.. function:: compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)
Byte-compile all the :file:`.py` files found along ``sys.path``. Return a