Nota
¡Ayúdanos a traducir la documentación oficial de Python al Español! Puedes encontrar más información en Como contribuir. Ayuda a acercar Python a más personas de habla hispana.
gzip
— Soporte para archivos gzip¶
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.
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=9, 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
obytes
), 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 instanciaio.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.
- exception gzip.BadGzipFile¶
Se lanzó una excepción para archivos gzip no válidos. Hereda
OSError
.OFError
yzlib.error
también se pueden lanzar para archivos gzip no válidos.Nuevo en la versión 3.8.
- class gzip.GzipFile(filename=None, mode=None, compresslevel=9, 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étodotruncate()
. 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 esNone
, 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 suGzipFile
con unio.TextIOWrapper
).El argumento compresslevel es un entero de
0
a9
que controla el nivel de compresión;1
es más rápido y produce la menor compresión, y9
es más lento y produce la mayor compresión.0
no es una compresión. El valor predeterminado es9
.El argumento mtime es una marca de tiempo numérica opcional que se escribirá en el campo de tiempo de última modificación de la secuencia al comprimir. Sólo debe proporcionarse en modo de compresión. Si se omite o
None
, se utiliza la hora actual. Consulte el atributomtime
para obtener más detalles.Al llamar en un objeto
GzipFile
el métodoclose()
no cierra fileobj, ya que es posible que desee anexar más material después de los datos comprimidos. Esto también le permite pasar un objetoio.BytesIO
que se abrió para escribir como fileobj, y recupera el búfer de memoria resultante usando elio.BytesIO
método del objetogetvalue()
.GzipFile
admite la interfazio.BufferedIOBase
, incluida la iteración y la declaraciónwith
. Solo el métodotruncate()
no está implementado.GzipFile
también proporciona el siguiente método y atributo:- peek(n)¶
Lee n bytes no comprimidos sin avanzar en la posición del archivo. A lo sumo se realiza una sola lectura en la secuencia comprimida para satisfacer la llamada. El número de bytes retornados puede ser mayor o menor de lo solicitado.
Nota
Al llamar a
peek()
no cambia la posición del archivoGzipFile
, puede cambiar la posición del objeto de archivo subyacente (por ejemplo, si elGzipFile
se construyó con el parámetro fileobj).Nuevo en la versión 3.2.
- mtime¶
Al descomprimir, el valor de la última modificación del campo de tiempo en el encabezado de lectura más reciente se puede leer de este atributo, como un entero. El valor inicial antes de leer cualquier encabezado es
None
.Todas las secuencias comprimidas gzip deben contener este campo de marca de tiempo. Algunos programas, como gunzip, hacen uso de la marca de tiempo. El formato es el mismo que el valor retornado de
time.time()
y el atributost_mtime
del objeto retornado poros.stat()
.
- name¶
La ruta al archivo gzip en disco, como
str
obytes
. Equivale a la salida deos.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 atributomtime
.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 deNone
.Distinto en la versión 3.6: Acepta un path-like object.
Distinto en la versión 3.12: Elimine el atributo
filename
, utilice en su lugar el atributoname`
.Obsoleto desde la versión 3.9: Abriendo
GzipFile
para escribir sin especificar el argumento mode está obsoleto.
- gzip.compress(data, compresslevel=9, *, mtime=None)¶
Comprime data, retornando un objeto
bytes
con los datos comprimidos. compresslevel y mtime tienen el mismo significado que en el constructorGzipFile
anterior. Cuando mtime se configura a0
en esta función, es equivalente azlib.compress()
con wbits configurado a31
. La función zlib es más rápida.Nuevo en la versión 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: La velocidad se mejora al comprimir todos los datos a la vez en lugar de transmitirlos. Las llamadas con mtime establecido a
0
se delegan azlib.compress()
para una mejor velocidad.
- 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ónzlib.decompress()
es más rápida si se establece wbits a 31.Nuevo en la versión 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.
Interfaz de Línea de Comandos¶
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.
Opciones de línea de comandos¶
- --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.