new repository

1 files changed, 78 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fcompileall.html b/devdocs/python~3.12/library%2Fcompileall.html
new file mode 100644
index 00000000..d37531a0
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fcompileall.html
@@ -0,0 +1,78 @@
+ <span id="compileall-byte-compile-python-libraries"></span><h1>compileall — Byte-compile Python libraries</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/compileall.py">Lib/compileall.py</a></p>  <p>This module provides some utility functions to support installing Python 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.</p> <div class="availability docutils container"> <p><a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p> <p>This module does not work or is not available on WebAssembly platforms <code>wasm32-emscripten</code> and <code>wasm32-wasi</code>. See <a class="reference internal" href="https://docs.python.org/3.12/library/intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p> </div> <section id="command-line-use"> <span id="compileall-cli"></span><h2>Command-line use</h2> <p>This module can work as a script (using <strong class="program">python -m compileall</strong>) to compile Python sources.</p> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-arg-directory">
+<code>directory ...</code> </dt> <dt class="sig sig-object std" id="cmdoption-compileall-arg-file">
+<code>file ...</code> </dt> <dd>
+<p>Positional arguments are files to compile or directories that contain source files, traversed recursively. If no argument is given, behave as if the command line was <code>-l <em>&lt;directories from sys.path&gt;</em></code>.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-l">
+<code>-l</code> </dt> <dd>
+<p>Do not recurse into subdirectories, only compile source code files directly contained in the named or implied directories.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-f">
+<code>-f</code> </dt> <dd>
+<p>Force rebuild even if timestamps are up-to-date.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-q">
+<code>-q</code> </dt> <dd>
+<p>Do not print the list of files compiled. If passed once, error messages will still be printed. If passed twice (<code>-qq</code>), all output is suppressed.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-d">
+<code>-d destdir</code> </dt> <dd>
+<p>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.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-s">
+<code>-s strip_prefix</code> </dt> <dd></dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-p">
+<code>-p prepend_prefix</code> </dt> <dd>
+<p>Remove (<code>-s</code>) or append (<code>-p</code>) the given prefix of paths recorded in the <code>.pyc</code> files. Cannot be combined with <code>-d</code>.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-x">
+<code>-x regex</code> </dt> <dd>
+<p>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.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-i">
+<code>-i list</code> </dt> <dd>
+<p>Read the file <code>list</code> and add each line that it contains to the list of files and directories to compile. If <code>list</code> is <code>-</code>, read lines from <code>stdin</code>.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-b">
+<code>-b</code> </dt> <dd>
+<p>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 <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a> locations and names, which allows byte-code files from multiple versions of Python to coexist.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-r">
+<code>-r</code> </dt> <dd>
+<p>Control the maximum recursion level for subdirectories. If this is given, then <code>-l</code> option will not be taken into account. <strong class="program">python -m compileall &lt;directory&gt; -r 0</strong> is equivalent to <strong class="program">python -m compileall &lt;directory&gt; -l</strong>.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-j">
+<code>-j N</code> </dt> <dd>
+<p>Use <em>N</em> workers to compile the files within the given directory. If <code>0</code> is used, then the result of <a class="reference internal" href="os#os.cpu_count" title="os.cpu_count"><code>os.cpu_count()</code></a> will be used.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-invalidation-mode">
+<code>--invalidation-mode [timestamp|checked-hash|unchecked-hash]</code> </dt> <dd>
+<p>Control how the generated byte-code files are invalidated at runtime. The <code>timestamp</code> value, means that <code>.pyc</code> files with the source timestamp and size embedded will be generated. The <code>checked-hash</code> and <code>unchecked-hash</code> values cause hash-based pycs to be generated. Hash-based pycs embed a hash of the source file contents rather than a timestamp. See <a class="reference internal" href="../reference/import#pyc-invalidation"><span class="std std-ref">Cached bytecode invalidation</span></a> for more information on how Python validates bytecode cache files at runtime. The default is <code>timestamp</code> if the <span class="target" id="index-1"></span><code>SOURCE_DATE_EPOCH</code> environment variable is not set, and <code>checked-hash</code> if the <code>SOURCE_DATE_EPOCH</code> environment variable is set.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-o">
+<code>-o level</code> </dt> <dd>
+<p>Compile with the given optimization level. May be used multiple times to compile for multiple levels at a time (for example, <code>compileall -o 1 -o 2</code>).</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-e">
+<code>-e dir</code> </dt> <dd>
+<p>Ignore symlinks pointing outside the given directory.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-compileall-hardlink-dupes">
+<code>--hardlink-dupes</code> </dt> <dd>
+<p>If two <code>.pyc</code> files with different optimization level have the same content, use hard links to consolidate duplicate files.</p> </dd>
+</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <code>-i</code>, <code>-b</code> and <code>-h</code> options.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <code>-j</code>, <code>-r</code>, and <code>-qq</code> options. <code>-q</code> option was changed to a multilevel value. <code>-b</code> will always produce a byte-code file ending in <code>.pyc</code>, never <code>.pyo</code>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>Added the <code>--invalidation-mode</code> option.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>Added the <code>-s</code>, <code>-p</code>, <code>-e</code> and <code>--hardlink-dupes</code> options. Raised the default recursion limit from 10 to <a class="reference internal" href="sys#sys.getrecursionlimit" title="sys.getrecursionlimit"><code>sys.getrecursionlimit()</code></a>. Added the possibility to specify the <code>-o</code> option multiple times.</p> </div> <p>There is no command-line option to control the optimization level used by the <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> function, because the Python interpreter itself already provides the option: <strong class="program">python -O -m compileall</strong>.</p> <p>Similarly, the <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> function respects the <a class="reference internal" href="sys#sys.pycache_prefix" title="sys.pycache_prefix"><code>sys.pycache_prefix</code></a> setting. The generated bytecode cache will only be useful if <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> is run with the same <a class="reference internal" href="sys#sys.pycache_prefix" title="sys.pycache_prefix"><code>sys.pycache_prefix</code></a> (if any) that will be used at runtime.</p> </section> <section id="public-functions"> <h2>Public functions</h2> <dl class="py function"> <dt class="sig sig-object py" id="compileall.compile_dir">
+<code>compileall.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, hardlink_dupes=False)</code> </dt> <dd>
+<p>Recursively descend the directory tree named by <em>dir</em>, compiling all <code>.py</code> files along the way. Return a true value if all the files compiled successfully, and a false value otherwise.</p> <p>The <em>maxlevels</em> parameter is used to limit the depth of the recursion; it defaults to <code>sys.getrecursionlimit()</code>.</p> <p>If <em>ddir</em> 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.</p> <p>If <em>force</em> is true, modules are re-compiled even if the timestamps are up to date.</p> <p>If <em>rx</em> is given, its <code>search</code> method is called on the complete path to each file considered for compilation, and if it returns a true value, the file is skipped. This can be used to exclude files matching a regular expression, given as a <a class="reference internal" href="re#re-objects"><span class="std std-ref">re.Pattern</span></a> object.</p> <p>If <em>quiet</em> is <code>False</code> or <code>0</code> (the default), the filenames and other information are printed to standard out. Set to <code>1</code>, only errors are printed. Set to <code>2</code>, all output is suppressed.</p> <p>If <em>legacy</em> 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 <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a> locations and names, which allows byte-code files from multiple versions of Python to coexist.</p> <p><em>optimize</em> specifies the optimization level for the compiler. It is passed to the built-in <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> function. Accepts also a sequence of optimization levels which lead to multiple compilations of one <code>.py</code> file in one call.</p> <p>The argument <em>workers</em> specifies how many workers are used to compile files in parallel. The default is to not use multiple workers. If the platform can’t use multiple workers and <em>workers</em> argument is given, then sequential compilation will be used as a fallback. If <em>workers</em> is 0, the number of cores in the system is used. If <em>workers</em> is lower than <code>0</code>, a <a class="reference internal" href="exceptions#ValueError" title="ValueError"><code>ValueError</code></a> will be raised.</p> <p><em>invalidation_mode</em> should be a member of the <a class="reference internal" href="py_compile#py_compile.PycInvalidationMode" title="py_compile.PycInvalidationMode"><code>py_compile.PycInvalidationMode</code></a> enum and controls how the generated pycs are invalidated at runtime.</p> <p>The <em>stripdir</em>, <em>prependdir</em> and <em>limit_sl_dest</em> arguments correspond to the <code>-s</code>, <code>-p</code> and <code>-e</code> options described above. They may be specified as <code>str</code> or <a class="reference internal" href="os#os.PathLike" title="os.PathLike"><code>os.PathLike</code></a>.</p> <p>If <em>hardlink_dupes</em> is true and two <code>.pyc</code> files with different optimization level have the same content, use hard links to consolidate duplicate files.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>legacy</em> and <em>optimize</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added the <em>workers</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span><em>quiet</em> parameter was changed to a multilevel value.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>legacy</em> parameter only writes out <code>.pyc</code> files, not <code>.pyo</code> files no matter what the value of <em>optimize</em> is.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.6: </span>Accepts a <a class="reference internal" href="../glossary#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>invalidation_mode</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7.2: </span>The <em>invalidation_mode</em> parameter’s default value is updated to None.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Setting <em>workers</em> to 0 now chooses the optimal number of cores.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>Added <em>stripdir</em>, <em>prependdir</em>, <em>limit_sl_dest</em> and <em>hardlink_dupes</em> arguments. Default value of <em>maxlevels</em> was changed from <code>10</code> to <code>sys.getrecursionlimit()</code></p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="compileall.compile_file">
+<code>compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=- 1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)</code> </dt> <dd>
+<p>Compile the file with path <em>fullname</em>. Return a true value if the file compiled successfully, and a false value otherwise.</p> <p>If <em>ddir</em> 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.</p> <p>If <em>rx</em> is given, its <code>search</code> 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 <code>True</code> is returned. This can be used to exclude files matching a regular expression, given as a <a class="reference internal" href="re#re-objects"><span class="std std-ref">re.Pattern</span></a> object.</p> <p>If <em>quiet</em> is <code>False</code> or <code>0</code> (the default), the filenames and other information are printed to standard out. Set to <code>1</code>, only errors are printed. Set to <code>2</code>, all output is suppressed.</p> <p>If <em>legacy</em> 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 <span class="target" id="index-3"></span><a class="pep reference external" href="https://peps.python.org/pep-3147/"><strong>PEP 3147</strong></a> locations and names, which allows byte-code files from multiple versions of Python to coexist.</p> <p><em>optimize</em> specifies the optimization level for the compiler. It is passed to the built-in <a class="reference internal" href="functions#compile" title="compile"><code>compile()</code></a> function. Accepts also a sequence of optimization levels which lead to multiple compilations of one <code>.py</code> file in one call.</p> <p><em>invalidation_mode</em> should be a member of the <a class="reference internal" href="py_compile#py_compile.PycInvalidationMode" title="py_compile.PycInvalidationMode"><code>py_compile.PycInvalidationMode</code></a> enum and controls how the generated pycs are invalidated at runtime.</p> <p>The <em>stripdir</em>, <em>prependdir</em> and <em>limit_sl_dest</em> arguments correspond to the <code>-s</code>, <code>-p</code> and <code>-e</code> options described above. They may be specified as <code>str</code> or <a class="reference internal" href="os#os.PathLike" title="os.PathLike"><code>os.PathLike</code></a>.</p> <p>If <em>hardlink_dupes</em> is true and two <code>.pyc</code> files with different optimization level have the same content, use hard links to consolidate duplicate files.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span><em>quiet</em> parameter was changed to a multilevel value.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>legacy</em> parameter only writes out <code>.pyc</code> files, not <code>.pyo</code> files no matter what the value of <em>optimize</em> is.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>invalidation_mode</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7.2: </span>The <em>invalidation_mode</em> parameter’s default value is updated to None.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>Added <em>stripdir</em>, <em>prependdir</em>, <em>limit_sl_dest</em> and <em>hardlink_dupes</em> arguments.</p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="compileall.compile_path">
+<code>compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=- 1, invalidation_mode=None)</code> </dt> <dd>
+<p>Byte-compile all the <code>.py</code> files found along <code>sys.path</code>. Return a true value if all the files compiled successfully, and a false value otherwise.</p> <p>If <em>skip_curdir</em> is true (the default), the current directory is not included in the search. All other parameters are passed to the <a class="reference internal" href="#compileall.compile_dir" title="compileall.compile_dir"><code>compile_dir()</code></a> function. Note that unlike the other compile functions, <code>maxlevels</code> defaults to <code>0</code>.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Added the <em>legacy</em> and <em>optimize</em> parameter.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span><em>quiet</em> parameter was changed to a multilevel value.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>legacy</em> parameter only writes out <code>.pyc</code> files, not <code>.pyo</code> files no matter what the value of <em>optimize</em> is.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>invalidation_mode</em> parameter was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.7.2: </span>The <em>invalidation_mode</em> parameter’s default value is updated to None.</p> </div> </dd>
+</dl> <p>To force a recompile of all the <code>.py</code> files in the <code>Lib/</code> subdirectory and all its subdirectories:</p> <pre data-language="python">import compileall
+
+compileall.compile_dir('Lib/', force=True)
+
+# Perform same compilation, excluding files in .svn directories.
+import re
+compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)
+
+# pathlib.Path objects can also be used.
+import pathlib
+compileall.compile_dir(pathlib.Path('Lib/'), force=True)
+</pre> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
+<code>Module</code> <a class="reference internal" href="py_compile#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code>py_compile</code></a>
+</dt>
+<dd>
+<p>Byte-compile a single source file.</p> </dd> </dl> </div> </section> <div class="_attribution">
+  <p class="_attribution-p">
+    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
+    <a href="https://docs.python.org/3.12/library/compileall.html" class="_attribution-link">https://docs.python.org/3.12/library/compileall.html</a>
+  </p>
+</div>