gzip — Поддержка файлов gzip

Исходный код: Lib/gzip.py

Этот модуль предоставляет простой интерфейс для сжатия и распаковки файлов, аналогично программам GNU gzip и gunzip.

Сжатие данных выполняется модулем zlib.

Модуль gzip предоставляет класс GzipFile, а также удобные функции open(), compress() и decompress(). Класс GzipFile считывает и записывает файлы в формате gzip, автоматически сжимая или распаковывая данные так, чтобы они выглядели как обычный объект файла.

Обратите внимание, что дополнительные форматы файлов, которые могут быть распакованы программами gzip и gunzip, такие как те, что созданы программами compress и pack, не поддерживаются этим модулем.

Модуль определяет следующие элементы:

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

Открывает сжатый gzip файл в двоичном или текстовом режиме, возвращая объект файла.

Аргумент filename может быть фактическим именем файла (объект str или bytes) или существующим объектом файла для чтения или записи.

Аргумент mode может быть любым из 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' или 'xb' для двоичного режима, или 'rt', 'at', 'wt', или 'xt' для текстового режима. По умолчанию используется 'rb'.

Аргумент compresslevel — целое число от 0 до 9, как и для конструктора GzipFile.

Для двоичного режима эта функция эквивалентна конструктору GzipFile: GzipFile(filename, mode, compresslevel). В этом случае аргументы encoding, errors и newline не должны быть предоставлены.

Для текстового режима создается объект GzipFile, и он оборачивается экземпляром io.TextIOWrapper со указанным кодированием, обработкой ошибок и разделителями строк.

Изменено в версии 3.3: Добавлена поддержка filename в виде объекта файла, поддержка текстового режима и аргументы encoding, errors и newline.

Изменено в версии 3.4: Добавлена поддержка режимов 'x', 'xb' и 'xt'.

Изменено в версии 3.6: Принимает объект пути.

exception gzip.BadGzipFile

Исключение, возбуждаемое для недопустимых файлов gzip. Оно наследуется от OSError. Также могут быть возбуждены EOFError и zlib.error для недопустимых файлов gzip.

Добавлена в версии 3.8.

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

Конструктор класса GzipFile, который имитирует большинство методов объекта файла объекта файла за исключением метода truncate(). По крайней мере одно из значений fileobj и filename должно быть ненулевым.

Новый экземпляр класса основан на fileobj, который может быть обычным файлом, объектом io.BytesIO или любым другим объектом, имитирующим файл. По умолчанию он равен None, в этом случае filename используется для открытия файла.

Когда fileobj не None, аргумент filename используется только для включения в заголовок файла gzip, который может содержать исходное имя файла нескомпрессированного файла. По умолчанию он равен имени файла fileobj, если это можно определить; в противном случае по умолчанию пустая строка, и в этом случае исходное имя файла не включается в заголовок.

Аргумент mode может принимать значения 'r', 'rb', 'a', 'ab', 'w', 'wb', 'x' или 'xb', в зависимости от того, будет ли файл читаться или записываться. По умолчанию используется режим fileobj, если это можно определить; в противном случае, по умолчанию 'rb'.

Обратите внимание, что файл всегда открывается в двоичном режиме. Для открытия сжатого файла в текстовом режиме используйте open() (или оберните ваш объект GzipFile с помощью io.TextIOWrapper).

Аргумент compresslevel — целое число от 0 до 9, контролирующее уровень сжатия; 1 — самый быстрый и с наименьшим сжатием, а 9 — самый медленный и с наибольшим сжатием. 0 — без сжатия. По умолчанию 9.

Аргумент mtime — необязательная числовая метка времени, которая записывается в поле последнего изменения времени в потоке при сжатии. Он должен быть задан только в режиме сжатия. Если он опущен или None, используется текущее время. Подробнее см. атрибут mtime.

Вызов метода close() объекта GzipFile не закрывает fileobj, так как вы можете добавить больше данных после сжатых данных. Это также позволяет передать объект io.BytesIO, открытый для записи, как fileobj и извлечь получившийся буфер памяти с помощью метода getvalue() объекта io.BytesIO.

Класс GzipFile поддерживает интерфейс io.BufferedIOBase, включая итерацию и оператор with. Только метод truncate() не реализован.

Класс GzipFile также предоставляет следующие методы и атрибут:

peek(n)

Считывает n нескомпрессированных байтов без изменения позиции файла. Для выполнения вызова выполняется не более одного единственного чтения в сжатом потоке. Количество возвращенных байтов может быть больше или меньше запрошенного.

Примечание

Хотя вызов peek() не изменяет позицию файла объекта GzipFile, он может изменить позицию базового объекта файла (например, если GzipFile был создан с параметром fileobj).

Добавлена в версии 3.2.

mtime

При распаковке значение поля последнего изменения времени в последнем прочитанном заголовке можно прочитать из этого атрибута в виде целого числа. Начальное значение до чтения каких-либо заголовков равно None.

Все сжатые потоки gzip обязаны содержать это поле метки времени. Некоторые программы, такие как gunzip, используют метку времени. Формат совпадает с возвращаемым значением time.time() и атрибутом st_mtime объекта, возвращаемого os.stat().

Изменено в версии 3.1: Добавлена поддержка оператора with, а также аргумента конструктора mtime и атрибута mtime.

Изменено в версии 3.2: Добавлена поддержка файлов с нулевым заполнением и неподдерживающих перемещение.

Изменено в версии 3.3: Метод io.BufferedIOBase.read1() теперь реализован.

Изменено в версии 3.4: Добавлена поддержка режимов 'x' и 'xb'.

Изменено в версии 3.5: Добавлена поддержка записи произвольных байтовых объектов. Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает объект пути.

gzip.compress(data, compresslevel=9, *, mtime=None)

Сжимает данные data, возвращая объект bytes, содержащий сжатые данные. compresslevel и mtime имеют то же значение, что и в конструкторе GzipFile выше.

Добавлена в версии 3.2.

Изменено в версии 3.8: Добавлен параметр mtime для воспроизводимого вывода.

gzip.decompress(data)

Распаковывает данные data, возвращая объект bytes, содержащий распакованные данные.

Добавлена в версии 3.2.

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

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

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)

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