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

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

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

Это необязательный модуль. Если его нет в вашей копии CPython, обратитесь к документации вашего дистрибутива (то есть того, кто предоставил вам Python). Если вы являетесь сопровождающим дистрибутива, см. раздел Требования для необязательных модулей.

Сжатие данных обеспечивается модулем 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. При работе с некорректными файлами gzip также могут возникнуть исключения EOFError и zlib.error.

Добавлено в версии 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'. В будущих выпусках Python режим fileobj использоваться не будет. При записи рекомендуется всегда указывать mode.

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

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

Необязательный аргумент mtime задаёт отметку времени, используемую gzip. Время указывается в формате Unix, то есть в секундах с 00:00:00 UTC 1 января 1970 года. Если mtime не указан или равен None, используется текущее время. Используйте mtime = 0, чтобы создать сжатый поток, не зависящий от времени создания.

Описание атрибута mtime, который задаётся при распаковке, см. ниже.

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

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

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

peek(n)

Читает n несжатых байтов, не перемещая позицию в файле. Число возвращённых байтов может быть больше или меньше запрошенного.

Примечание

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

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

mode

'rb' для чтения и 'wb' для записи.

Изменено в версии 3.13: В предыдущих версиях это было целое число 1 или 2.

mtime

При распаковке этот атрибут устанавливается в значение последней отметки времени из последнего прочитанного заголовка. Это целое число, содержащее количество секунд с начала эпохи Unix (00:00:00 UTC 1 января 1970 года). До чтения каких-либо заголовков начальное значение равно None.

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. Метод read() теперь принимает аргумент со значением None.

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

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

Изменено в версии 3.12: Атрибут filename удалён; вместо него используйте атрибут name.

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

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

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

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

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

Изменено в версии 3.13: Гарантируется, что байт OS заголовка gzip будет равен 255, как это было в версиях 3.10 и более ранних.

Изменено в версии 3.14: Теперь параметр mtime по умолчанию равен 0, чтобы результат был воспроизводимым. Чтобы получить прежнее поведение с использованием текущего времени, передайте None в параметр mtime.

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)