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

name¶

Путь к файлу gzip на диске, в виде str или bytes. Эквивалентно результату os.fspath() в исходном входном пути, без какой-либо другой нормализации, разрешения или расширения.

Изменено в версии 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, приведенном выше. Когда значение mtime равно 0, эта функция эквивалентна zlib.compress(), а значение wbits равно 31. Функция zlib работает быстрее.

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

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

Изменено в версии 3.11: Скорость повышается за счет сжатия всех данных сразу, а не в потоковом режиме. Вызовы, для которых значение mtime равно 0, делегируются на zlib.compress() для повышения скорости. В этой ситуации выходные данные могут содержать байтовое значение заголовка gzip «OS», отличное от 255 «неизвестно», как указано в базовой реализации zlib.

gzip.decompress(data)¶

Распакуйте data, возвращая объект bytes, содержащий несжатые данные. Эта функция способна распаковывать данные gzip, состоящие из нескольких элементов (несколько блоков gzip, соединенных вместе). Когда данные наверняка содержат только один элемент, функция zlib.decompress() с значением wbits равным 31 работает быстрее.

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

Изменено в версии 3.11: Скорость повышается за счет одновременной распаковки элементов в памяти, а не в потоковом режиме.

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)