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).

1 files changed, 38 insertions, 1 deletions

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 @@ compile Python sources.
    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 @@ compile Python sources.
    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 @@ compile Python sources.
 .. 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 @@ runtime.
 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 @@ Public functions
    :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 @@ Public functions
    .. 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 @@ Public functions
    :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 @@ Public functions
    .. 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