new repository

1 files changed, 64 insertions, 0 deletions

diff --git a/devdocs/python~3.12/library%2Fgzip.html b/devdocs/python~3.12/library%2Fgzip.html
new file mode 100644
index 00000000..efb81e26
--- /dev/null
+++ b/devdocs/python~3.12/library%2Fgzip.html
@@ -0,0 +1,64 @@
+ <span id="gzip-support-for-gzip-files"></span><h1>gzip — Support for gzip files</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/gzip.py">Lib/gzip.py</a></p>  <p>This module provides a simple interface to compress and decompress files just like the GNU programs <strong class="program">gzip</strong> and <strong class="program">gunzip</strong> would.</p> <p>The data compression is provided by the <a class="reference internal" href="zlib#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code>zlib</code></a> module.</p> <p>The <a class="reference internal" href="#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code>gzip</code></a> module provides the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> class, as well as the <a class="reference internal" href="#gzip.open" title="gzip.open"><code>open()</code></a>, <a class="reference internal" href="#gzip.compress" title="gzip.compress"><code>compress()</code></a> and <a class="reference internal" href="#gzip.decompress" title="gzip.decompress"><code>decompress()</code></a> convenience functions. The <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> class reads and writes <strong class="program">gzip</strong>-format files, automatically compressing or decompressing the data so that it looks like an ordinary <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a>.</p> <p>Note that additional file formats which can be decompressed by the <strong class="program">gzip</strong> and <strong class="program">gunzip</strong> programs, such as those produced by <strong class="program">compress</strong> and <strong class="program">pack</strong>, are not supported by this module.</p> <p>The module defines the following items:</p> <dl class="py function"> <dt class="sig sig-object py" id="gzip.open">
+<code>gzip.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)</code> </dt> <dd>
+<p>Open a gzip-compressed file in binary or text mode, returning a <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a>.</p> <p>The <em>filename</em> argument can be an actual filename (a <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> or <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object), or an existing file object to read from or write to.</p> <p>The <em>mode</em> argument can be any of <code>'r'</code>, <code>'rb'</code>, <code>'a'</code>, <code>'ab'</code>, <code>'w'</code>, <code>'wb'</code>, <code>'x'</code> or <code>'xb'</code> for binary mode, or <code>'rt'</code>, <code>'at'</code>, <code>'wt'</code>, or <code>'xt'</code> for text mode. The default is <code>'rb'</code>.</p> <p>The <em>compresslevel</em> argument is an integer from 0 to 9, as for the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> constructor.</p> <p>For binary mode, this function is equivalent to the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> constructor: <code>GzipFile(filename, mode, compresslevel)</code>. In this case, the <em>encoding</em>, <em>errors</em> and <em>newline</em> arguments must not be provided.</p> <p>For text mode, a <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> object is created, and wrapped in an <a class="reference internal" href="io#io.TextIOWrapper" title="io.TextIOWrapper"><code>io.TextIOWrapper</code></a> instance with the specified encoding, error handling behavior, and line ending(s).</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>Added support for <em>filename</em> being a file object, support for text mode, and the <em>encoding</em>, <em>errors</em> and <em>newline</em> arguments.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Added support for the <code>'x'</code>, <code>'xb'</code> and <code>'xt'</code> modes.</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> </dd>
+</dl> <dl class="py exception"> <dt class="sig sig-object py" id="gzip.BadGzipFile">
+<code>exception gzip.BadGzipFile</code> </dt> <dd>
+<p>An exception raised for invalid gzip files. It inherits <a class="reference internal" href="exceptions#OSError" title="OSError"><code>OSError</code></a>. <a class="reference internal" href="exceptions#EOFError" title="EOFError"><code>EOFError</code></a> and <a class="reference internal" href="zlib#zlib.error" title="zlib.error"><code>zlib.error</code></a> can also be raised for invalid gzip files.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> </dd>
+</dl> <dl class="py class"> <dt class="sig sig-object py" id="gzip.GzipFile">
+<code>class gzip.GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)</code> </dt> <dd>
+<p>Constructor for the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> class, which simulates most of the methods of a <a class="reference internal" href="../glossary#term-file-object"><span class="xref std std-term">file object</span></a>, with the exception of the <a class="reference internal" href="io#io.IOBase.truncate" title="io.IOBase.truncate"><code>truncate()</code></a> method. At least one of <em>fileobj</em> and <em>filename</em> must be given a non-trivial value.</p> <p>The new class instance is based on <em>fileobj</em>, which can be a regular file, an <a class="reference internal" href="io#io.BytesIO" title="io.BytesIO"><code>io.BytesIO</code></a> object, or any other object which simulates a file. It defaults to <code>None</code>, in which case <em>filename</em> is opened to provide a file object.</p> <p>When <em>fileobj</em> is not <code>None</code>, the <em>filename</em> argument is only used to be included in the <strong class="program">gzip</strong> file header, which may include the original filename of the uncompressed file. It defaults to the filename of <em>fileobj</em>, if discernible; otherwise, it defaults to the empty string, and in this case the original filename is not included in the header.</p> <p>The <em>mode</em> argument can be any of <code>'r'</code>, <code>'rb'</code>, <code>'a'</code>, <code>'ab'</code>, <code>'w'</code>, <code>'wb'</code>, <code>'x'</code>, or <code>'xb'</code>, depending on whether the file will be read or written. The default is the mode of <em>fileobj</em> if discernible; otherwise, the default is <code>'rb'</code>. In future Python releases the mode of <em>fileobj</em> will not be used. It is better to always specify <em>mode</em> for writing.</p> <p>Note that the file is always opened in binary mode. To open a compressed file in text mode, use <a class="reference internal" href="#gzip.open" title="gzip.open"><code>open()</code></a> (or wrap your <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> with an <a class="reference internal" href="io#io.TextIOWrapper" title="io.TextIOWrapper"><code>io.TextIOWrapper</code></a>).</p> <p>The <em>compresslevel</em> argument is an integer from <code>0</code> to <code>9</code> controlling the level of compression; <code>1</code> is fastest and produces the least compression, and <code>9</code> is slowest and produces the most compression. <code>0</code> is no compression. The default is <code>9</code>.</p> <p>The <em>mtime</em> argument is an optional numeric timestamp to be written to the last modification time field in the stream when compressing. It should only be provided in compression mode. If omitted or <code>None</code>, the current time is used. See the <a class="reference internal" href="#gzip.GzipFile.mtime" title="gzip.GzipFile.mtime"><code>mtime</code></a> attribute for more details.</p> <p>Calling a <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> object’s <code>close()</code> method does not close <em>fileobj</em>, since you might wish to append more material after the compressed data. This also allows you to pass an <a class="reference internal" href="io#io.BytesIO" title="io.BytesIO"><code>io.BytesIO</code></a> object opened for writing as <em>fileobj</em>, and retrieve the resulting memory buffer using the <a class="reference internal" href="io#io.BytesIO" title="io.BytesIO"><code>io.BytesIO</code></a> object’s <a class="reference internal" href="io#io.BytesIO.getvalue" title="io.BytesIO.getvalue"><code>getvalue()</code></a> method.</p> <p><a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> supports the <a class="reference internal" href="io#io.BufferedIOBase" title="io.BufferedIOBase"><code>io.BufferedIOBase</code></a> interface, including iteration and the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement. Only the <a class="reference internal" href="io#io.IOBase.truncate" title="io.IOBase.truncate"><code>truncate()</code></a> method isn’t implemented.</p> <p><a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> also provides the following method and attribute:</p> <dl class="py method"> <dt class="sig sig-object py" id="gzip.GzipFile.peek">
+<code>peek(n)</code> </dt> <dd>
+<p>Read <em>n</em> uncompressed bytes without advancing the file position. At most one single read on the compressed stream is done to satisfy the call. The number of bytes returned may be more or less than requested.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>While calling <a class="reference internal" href="#gzip.GzipFile.peek" title="gzip.GzipFile.peek"><code>peek()</code></a> does not change the file position of the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a>, it may change the position of the underlying file object (e.g. if the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> was constructed with the <em>fileobj</em> parameter).</p> </div> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="gzip.GzipFile.mtime">
+<code>mtime</code> </dt> <dd>
+<p>When decompressing, the value of the last modification time field in the most recently read header may be read from this attribute, as an integer. The initial value before reading any headers is <code>None</code>.</p> <p>All <strong class="program">gzip</strong> compressed streams are required to contain this timestamp field. Some programs, such as <strong class="program">gunzip</strong>, make use of the timestamp. The format is the same as the return value of <a class="reference internal" href="time#time.time" title="time.time"><code>time.time()</code></a> and the <a class="reference internal" href="os#os.stat_result.st_mtime" title="os.stat_result.st_mtime"><code>st_mtime</code></a> attribute of the object returned by <a class="reference internal" href="os#os.stat" title="os.stat"><code>os.stat()</code></a>.</p> </dd>
+</dl> <dl class="py attribute"> <dt class="sig sig-object py" id="gzip.GzipFile.name">
+<code>name</code> </dt> <dd>
+<p>The path to the gzip file on disk, as a <a class="reference internal" href="stdtypes#str" title="str"><code>str</code></a> or <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a>. Equivalent to the output of <a class="reference internal" href="os#os.fspath" title="os.fspath"><code>os.fspath()</code></a> on the original input path, with no other normalization, resolution or expansion.</p> </dd>
+</dl> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.1: </span>Support for the <a class="reference internal" href="../reference/compound_stmts#with"><code>with</code></a> statement was added, along with the <em>mtime</em> constructor argument and <a class="reference internal" href="#gzip.GzipFile.mtime" title="gzip.GzipFile.mtime"><code>mtime</code></a> attribute.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.2: </span>Support for zero-padded and unseekable files was added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.3: </span>The <a class="reference internal" href="io#io.BufferedIOBase.read1" title="io.BufferedIOBase.read1"><code>io.BufferedIOBase.read1()</code></a> method is now implemented.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>Added support for the <code>'x'</code> and <code>'xb'</code> modes.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.5: </span>Added support for writing arbitrary <a class="reference internal" href="../glossary#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a>. The <a class="reference internal" href="io#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code>read()</code></a> method now accepts an argument of <code>None</code>.</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.12: </span>Remove the <code>filename</code> attribute, use the <a class="reference internal" href="#gzip.GzipFile.name" title="gzip.GzipFile.name"><code>name</code></a> attribute instead.</p> </div> <div class="deprecated"> <p><span class="versionmodified deprecated">Deprecated since version 3.9: </span>Opening <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> for writing without specifying the <em>mode</em> argument is deprecated.</p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="gzip.compress">
+<code>gzip.compress(data, compresslevel=9, *, mtime=None)</code> </dt> <dd>
+<p>Compress the <em>data</em>, returning a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object containing the compressed data. <em>compresslevel</em> and <em>mtime</em> have the same meaning as in the <a class="reference internal" href="#gzip.GzipFile" title="gzip.GzipFile"><code>GzipFile</code></a> constructor above. When <em>mtime</em> is set to <code>0</code>, this function is equivalent to <a class="reference internal" href="zlib#zlib.compress" title="zlib.compress"><code>zlib.compress()</code></a> with <em>wbits</em> set to <code>31</code>. The zlib function is faster.</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.8: </span>Added the <em>mtime</em> parameter for reproducible output.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.11: </span>Speed is improved by compressing all data at once instead of in a streamed fashion. Calls with <em>mtime</em> set to <code>0</code> are delegated to <a class="reference internal" href="zlib#zlib.compress" title="zlib.compress"><code>zlib.compress()</code></a> for better speed.</p> </div> </dd>
+</dl> <dl class="py function"> <dt class="sig sig-object py" id="gzip.decompress">
+<code>gzip.decompress(data)</code> </dt> <dd>
+<p>Decompress the <em>data</em>, returning a <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a> object containing the uncompressed data. This function is capable of decompressing multi-member gzip data (multiple gzip blocks concatenated together). When the data is certain to contain only one member the <a class="reference internal" href="zlib#zlib.decompress" title="zlib.decompress"><code>zlib.decompress()</code></a> function with <em>wbits</em> set to 31 is faster.</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.11: </span>Speed is improved by decompressing members at once in memory instead of in a streamed fashion.</p> </div> </dd>
+</dl> <section id="examples-of-usage"> <span id="gzip-usage-examples"></span><h2>Examples of usage</h2> <p>Example of how to read a compressed file:</p> <pre data-language="python">import gzip
+with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
+    file_content = f.read()
+</pre> <p>Example of how to create a compressed GZIP file:</p> <pre data-language="python">import gzip
+content = b"Lots of content here"
+with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
+    f.write(content)
+</pre> <p>Example of how to GZIP compress an existing file:</p> <pre data-language="python">import gzip
+import shutil
+with open('/home/joe/file.txt', 'rb') as f_in:
+    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:
+        shutil.copyfileobj(f_in, f_out)
+</pre> <p>Example of how to GZIP compress a binary string:</p> <pre data-language="python">import gzip
+s_in = b"Lots of content here"
+s_out = gzip.compress(s_in)
+</pre> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt>
+<code>Module</code> <a class="reference internal" href="zlib#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code>zlib</code></a>
+</dt>
+<dd>
+<p>The basic data compression module needed to support the <strong class="program">gzip</strong> file format.</p> </dd> </dl> </div> </section> <section id="command-line-interface"> <span id="gzip-cli"></span><h2>Command Line Interface</h2> <p>The <a class="reference internal" href="#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code>gzip</code></a> module provides a simple command line interface to compress or decompress files.</p> <p>Once executed the <a class="reference internal" href="#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code>gzip</code></a> module keeps the input file(s).</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Add a new command line interface with a usage. By default, when you will execute the CLI, the default compression level is 6.</p> </div> <section id="command-line-options"> <h3>Command line options</h3> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-gzip-arg-file">
+<code>file</code> </dt> <dd>
+<p>If <em>file</em> is not specified, read from <a class="reference internal" href="sys#sys.stdin" title="sys.stdin"><code>sys.stdin</code></a>.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-gzip-fast">
+<code>--fast</code> </dt> <dd>
+<p>Indicates the fastest compression method (less compression).</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-gzip-best">
+<code>--best</code> </dt> <dd>
+<p>Indicates the slowest compression method (best compression).</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-gzip-d">
+<code>-d, --decompress</code> </dt> <dd>
+<p>Decompress the given file.</p> </dd>
+</dl> <dl class="std option"> <dt class="sig sig-object std" id="cmdoption-gzip-h">
+<code>-h, --help</code> </dt> <dd>
+<p>Show the help message.</p> </dd>
+</dl> </section> </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/gzip.html" class="_attribution-link">https://docs.python.org/3.12/library/gzip.html</a>
+  </p>
+</div>