diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/library/compileall.rst | 5 | ||||
| -rw-r--r-- | Doc/library/sys.rst | 20 | ||||
| -rw-r--r-- | Doc/using/cmdline.rst | 16 |
3 files changed, 41 insertions, 0 deletions
diff --git a/Doc/library/compileall.rst b/Doc/library/compileall.rst index 7b3963d..22d1c6b 100644 --- a/Doc/library/compileall.rst +++ b/Doc/library/compileall.rst @@ -109,6 +109,11 @@ There is no command-line option to control the optimization level used by the :func:`compile` function, because the Python interpreter itself already provides the option: :program:`python -O -m compileall`. +Similarly, the :func:`compile` function respects the :attr:`sys.pycache_prefix` +setting. The generated bytecode cache will only be useful if :func:`compile` is +run with the same :attr:`sys.pycache_prefix` (if any) that will be used at +runtime. + Public functions ---------------- diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 67925e4..4ad060f 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -209,6 +209,26 @@ always available. yourself to control bytecode file generation. +.. data:: pycache_prefix + + If this is set (not ``None``), Python will write bytecode-cache ``.pyc`` + files to (and read them from) a parallel directory tree rooted at this + directory, rather than from ``__pycache__`` directories in the source code + tree. Any ``__pycache__`` directories in the source code tree will be ignored + and new `.pyc` files written within the pycache prefix. Thus if you use + :mod:`compileall` as a pre-build step, you must ensure you run it with the + same pycache prefix (if any) that you will use at runtime. + + A relative path is interpreted relative to the current working directory. + + This value is initially set based on the value of the :option:`-X` + ``pycache_prefix=PATH`` command-line option or the + :envvar:`PYTHONPYCACHEPREFIX` environment variable (command-line takes + precedence). If neither are set, it is ``None``. + + .. versionadded:: 3.8 + + .. function:: excepthook(type, value, traceback) This function prints out a given traceback and exception to ``sys.stderr``. diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index c6bb0be..9ddc515 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -442,6 +442,9 @@ Miscellaneous options the default locale-aware mode. ``-X utf8=0`` explicitly disables UTF-8 mode (even when it would otherwise activate automatically). See :envvar:`PYTHONUTF8` for more details. + * ``-X pycache_prefix=PATH`` enables writing ``.pyc`` files to a parallel + tree rooted at the given directory instead of to the code tree. See also + :envvar:`PYTHONPYCACHEPREFIX`. It also allows passing arbitrary values and retrieving them through the :data:`sys._xoptions` dictionary. @@ -461,6 +464,9 @@ Miscellaneous options .. versionadded:: 3.7 The ``-X importtime``, ``-X dev`` and ``-X utf8`` options. + .. versionadded:: 3.8 + The ``-X pycache_prefix`` option. + Options you shouldn't use ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -587,6 +593,16 @@ conflict. specifying the :option:`-B` option. +.. envvar:: PYTHONPYCACHEPREFIX + + If this is set, Python will write ``.pyc`` files in a mirror directory tree + at this path, instead of in ``__pycache__`` directories within the source + tree. This is equivalent to specifying the :option:`-X` + ``pycache_prefix=PATH`` option. + + .. versionadded:: 3.8 + + .. envvar:: PYTHONHASHSEED If this variable is not set or set to ``random``, a random value is used |