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

Данный модуль предоставляет простой интерфейс для сжатия и распаковки файлов, аналогично программам 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()

Пример создания сжатого GZIP файла:

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

Пример того, как GZIP сжимает существующий файл:

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)

Пример того, как GZIP сжимает двоичную строку:

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

См.также

Модуль zlib
Базовый модуль сжатия данных, необходимый для поддержки файла gzip формата.

Интерфейс командной строки

Модуль gzip предоставляет простой интерфейс командной строки для сжатия или распаковки файлов.

После выполнения модуль gzip сохраняет входные файлы.

Изменено в версии 3.8: Добавлен новый интерфейс командной строки с использованием. По умолчанию при выполнении CLI уровень сжатия по умолчанию равен 6.

Параметры командной строки

file

Если file не указан, читать с sys.stdin.

--fast

Указывает самый быстрый метод сжатия (меньшее сжатие).

--best

Указывает самый медленный метод сжатия (наилучшее сжатие).

-d, --decompress

Распаковать данный файл.

-h, --help

Показать справочное сообщение.