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'. В будущих версиях 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, так как вы можете добавить больше данных после сжатых данных. Это также позволяет вам передать объект io.BytesIO, открытый для записи, как fileobj и извлечь полученный буфер памяти, используя метод объекта io.BytesIO getvalue().

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

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

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

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

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

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

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

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

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

Изменено в версии 3.13: Гарантируется, что значение заголовка gzip «OS» будет установлено в 255, когда используется эта функция, как это было в 3.10 и ранее.

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