"gzip" --- Support for **gzip** files
*************************************

**Código fuente:** Lib/gzip.py

======================================================================

Este módulo proporciona una interfaz simple para comprimir y
descomprimir archivos como lo harían los programas GNU **gzip** y
**gunzip**.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see
Requirements for optional modules.

La compresión de datos la proporciona el módulo "zlib".

El módulo "gzip" proporciona la clase "GzipFile", así como las
funciones de conveniencia "open()", "compress()" y "decompress()". La
clase "GzipFile" lee y escribe archivos de formato **gzip**,
comprimiendo o descomprimiendo automáticamente los datos para que
parezcan un *file object* ordinario.

Tenga en cuenta que los formatos de archivo adicionales que pueden ser
descomprimidos por los programas **gzip** y **gunzip**, como los
producidos por **compress** y **pack**, no son compatibles con este
módulo.

El módulo define los siguientes elementos:

gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None)

   Abre un archivo comprimido gzip en modo binario o de texto,
   retornando un *file object*.

   El argumento *filename* puede ser un nombre de archivo real (un
   objeto "str" o "bytes"), o un objeto archivo existente para leer o
   escribir.

   El argumento *mode* puede ser cualquiera de "'r'", "'rb'", "'a'",
   "'ab'", "'w'", "'wb'", "'x'" or "'xb'" para el modo binario, o
   "'rt'", "'at'", "'wt'", or "'xt'" para el modo texto. El valor
   predeterminado es "'rb'".

   El argumento *compresslevel* es un número entero de 0 a 9, como
   para el constructor "GzipFile".

   Para el modo binario, esta función es equivalente al constructor
   "GzipFile": "GzipFile (filename, mode, compresslevel)". En este
   caso, no se deben proporcionar los argumentos *encoding*, *errors*
   y *newline*.

   Para el modo texto, se crea un objeto "GzipFile" y se envuelve en
   una instancia "io.TextIOWrapper" con la codificación especificada,
   comportamiento de manejo de errores y terminación(es) de línea.

   Distinto en la versión 3.3: Se agregó soporte para que *filename*
   sea un objeto de archivo, soporte para el modo de texto y los
   argumentos *encoding*, *errors* y *newline*.

   Distinto en la versión 3.4: Se agregó soporte para los modos "'x'",
   "'xb'" y "'xt'".

   Distinto en la versión 3.6: Acepta un *path-like object*.

   Distinto en la versión 3.15: The default compression level was
   reduced to 6 (down from 9). It is the default level used by most
   compression tools and a better tradeoff between speed and
   performance.

exception gzip.BadGzipFile

   An exception raised for invalid gzip files.  It inherits from
   "OSError". "EOFError" and "zlib.error" can also be raised for
   invalid gzip files.

   Added in version 3.8.

class gzip.GzipFile(filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)

   Constructor para la clase "GzipFile", que simula la mayoría de los
   métodos de *file object*, con la excepción del método "truncate()".
   Al menos uno de *fileobj* y *filename* debe recibir un valor no
   trivial.

   La nueva instancia de clase se basa en *fileobj*, que puede ser un
   archivo normal, un objeto "io.BytesIO", o cualquier otro objeto que
   simule un archivo. El valor predeterminado es "None", en cuyo caso
   se abre *filename* para proporcionar un objeto de archivo.

   Cuando *fileobj* no es "None", el argumento *filename* solo se usa
   para ser incluido en el encabezado del archivo **gzip**, que puede
   incluir el nombre de archivo original del archivo sin comprimir. De
   forma predeterminada, el nombre de archivo es de *fileobj*, si es
   discernible; de lo contrario, el valor predeterminado es la cadena
   vacía, y en este caso el nombre del archivo original no se incluye
   en el encabezado.

   El argumento *mode* puede ser cualquiera de "'r'", "'rb'", "'a'",
   "'ab'", "'w'", "'wb'", "'x'", or "'xb'", dependiendo de si el
   archivo se leerá o escribirá. El valor predeterminado es el modo de
   *fileobj* si es discernible; de lo contrario, el valor
   predeterminado es "'rb'". En futuras versiones de Python, no se
   utilizará el modo *fileobj*. Es mejor especificar siempre *mode*
   para escribir.

   Tenga en cuenta que el archivo siempre se abre en modo binario.
   Para abrir un archivo comprimido en modo de texto, utilice "open()"
   (o ajuste su "GzipFile" con un "io.TextIOWrapper").

   El argumento *compresslevel* es un entero de "0" a "9" que controla
   el nivel de compresión; "1" es más rápido y produce la menor
   compresión, y "9" es más lento y produce la mayor compresión. "0"
   no es una compresión. El valor predeterminado es "9".

   The optional *mtime* argument is the timestamp requested by gzip.
   The time is in Unix format, i.e., seconds since 00:00:00 UTC,
   January 1, 1970. If *mtime* is omitted or "None", the current time
   is used. Use *mtime* = 0 to generate a compressed stream that does
   not depend on creation time.

   See below for the "mtime" attribute that is set when decompressing.

   Calling a "GzipFile" object's "close()" method does not close
   *fileobj*, since you might wish to append more material after the
   compressed data.  This also allows you to pass an "io.BytesIO"
   object opened for writing as *fileobj*, and retrieve the resulting
   memory buffer using the "io.BytesIO" object's "getvalue()" method.

   "GzipFile" admite la interfaz "io.BufferedIOBase", incluida la
   iteración y la declaración "with". Solo el método "truncate()" no
   está implementado.

   "GzipFile" también proporciona el siguiente método y atributo:

   peek(n)

      Read *n* uncompressed bytes without advancing the file position.
      The number of bytes returned may be more or less than requested.

      Nota:

        Al llamar a "peek()" no cambia la posición del archivo
        "GzipFile", puede cambiar la posición del objeto de archivo
        subyacente (por ejemplo, si el "GzipFile" se construyó con el
        parámetro *fileobj*).

      Added in version 3.2.

   mode

      "'rb'" for reading and "'wb'" for writing.

      Distinto en la versión 3.13: In previous versions it was an
      integer "1" or "2".

   mtime

      When decompressing, this attribute is set to the last timestamp
      in the most recently read header.  It is an integer, holding the
      number of seconds since the Unix epoch (00:00:00 UTC, January 1,
      1970). The initial value before reading any headers is "None".

   name

      La ruta al archivo gzip en disco, como "str" o "bytes". Equivale
      a la salida de "os.fspath()" en la ruta de entrada original, sin
      ninguna otra normalización, resolución o expansión.

   Distinto en la versión 3.1: Se ha agregado soporte para la
   declaración "with", junto con el argumento del constructor *mtime*
   y el atributo "mtime".

   Distinto en la versión 3.2: Se agregó soporte para archivos con
   relleno de ceros y que no se pueden buscar.

   Distinto en la versión 3.3: El método "io.BufferedIOBase.read1()"
   ahora está implementado.

   Distinto en la versión 3.4: Se agregó soporte para los modos "'x'"
   y "'xb'".

   Distinto en la versión 3.5: Se ha añadido soporte para escribir
   objetos arbitrarios *bytes-like objects*. El método "read()" ahora
   acepta un argumento de "None".

   Distinto en la versión 3.6: Acepta un *path-like object*.

   Obsoleto desde la versión 3.9: Abriendo "GzipFile" para escribir
   sin especificar el argumento *mode* está obsoleto.

   Distinto en la versión 3.12: Elimine el atributo "filename",
   utilice en su lugar el atributo "name`".

   Distinto en la versión 3.15: The default compression level was
   reduced to 6 (down from 9). It is the default level used by most
   compression tools and a better tradeoff between speed and
   performance.

gzip.compress(data, compresslevel=6, *, mtime=0)

   Compress the *data*, returning a "bytes" object containing the
   compressed data.  *compresslevel* and *mtime* have the same meaning
   as in the "GzipFile" constructor above, but *mtime* defaults to 0
   for reproducible output.

   Added in version 3.2.

   Distinto en la versión 3.8: Se agregó el parámetro *mtime* para una
   salida reproducible.

   Distinto en la versión 3.11: Speed is improved by compressing all
   data at once instead of in a streamed fashion. Calls with *mtime*
   set to "0" are delegated to "zlib.compress()" for better speed. In
   this situation the output may contain a gzip header "OS" byte value
   other than 255 "unknown" as supplied by the underlying zlib
   implementation.

   Distinto en la versión 3.13: The gzip header OS byte is guaranteed
   to be set to 255 when this function is used as was the case in 3.10
   and earlier.

   Distinto en la versión 3.14: The *mtime* parameter now defaults to
   0 for reproducible output. For the previous behaviour of using the
   current time, pass "None" to *mtime*.

   Distinto en la versión 3.15: The default compression level was
   reduced to 6 (down from 9). It is the default level used by most
   compression tools and a better tradeoff between speed and
   performance.

gzip.decompress(data)

   Descomprime *data*, retornando un objeto "bytes" que contiene los
   datos sin comprimir. Esta función es capaz de descomprimir datos
   gzip de varios miembros (múltiples bloques gzip concatenados entre
   sí). Cuando se está seguro de que los datos contienen un solo
   miembro, la función "zlib.decompress()" es más rápida si se
   establece *wbits* a 31.

   Added in version 3.2.

   Distinto en la versión 3.11: La velocidad se mejora al descomprimir
   los miembros simultáneamente en memoria en lugar de hacerlo de
   manera continua.


Ejemplos de uso
===============

Ejemplos de como leer un archivo comprimido:

   import gzip
   with gzip.open('/home/joe/file.txt.gz', 'rb') as f:
       file_content = f.read()

Ejemplos de como crear un archivo comprimido GZIP:

   import gzip
   content = b"Lots of content here"
   with gzip.open('/home/joe/file.txt.gz', 'wb') as f:
       f.write(content)

Ejemplos de como GZIP comprime un archivo existente:

   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)

Ejemplo de como GZIP comprime una cadena binaria:

   import gzip
   s_in = b"Lots of content here"
   s_out = gzip.compress(s_in)

Ver también:

  Módulo "zlib"
     El módulo básico de compresión de datos necesario para admitir el
     formato de archivo **gzip**.

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.


Command-line interface
======================

El módulo "gzip" proporciona una interfaz de línea de comandos simple
para comprimir o descomprimir archivos.

Una vez ejecutado el módulo "gzip" conserva los archivos de entrada.

Distinto en la versión 3.8: Agrega una nueva interfaz de línea de
comandos con un uso. De forma predeterminada, cuando ejecutará la CLI,
el nivel de compresión predeterminado es 6.


Command-line options
--------------------

file

   Si no se especifica *file*, lee de "sys.stdin".

--fast

   Indica el método de compresión más rápido (menos compresión).

--best

   Indica el método de compresión más lento (mejor compresión).

-d, --decompress

   Descomprime el archivo dado.

-h, --help

   Muestra el mensaje de ayuda.
