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

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

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

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

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

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

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

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

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

Аргумент 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: Принимает path-like object.

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, который имитирует большинство методов file object, за исключением метода truncate(). Хотя бы одному из fileobj и filename должно быть присвоено нетривиальное значение.

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

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

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

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

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

Аргумент mtime - это необязательная числовая метка времени, которая будет записана в поле времени последней модификации в потоке при сжатии. Его следует указывать только в режиме сжатия. Если опущен или None, используется текущее время. Более подробную информацию см. в атрибуте mtime.

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

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: Добавлена поддержка записи произвольных bytes-like objects. Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает path-like object.

Не рекомендуется, начиная с версии 3.9: Открытие GzipFile для записи без указания аргумента mode является устаревшим.

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

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

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

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

gzip.decompress(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)