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-файлов.

Added in version 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 - это временная метка, запрашиваемая gzip. Время указывается в формате Unix, т. е. в секундах с 00:00:00 UTC, 1 января 1970 года. Если mtime опущен или None, используется текущее время. Используйте mtime = 0, чтобы сгенерировать сжатый поток, не зависящий от времени создания.

Атрибут mtime, который устанавливается при распаковке, см. ниже.

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

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

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

peek(n)

Чтение n несжатых байтов без продвижения позиции файла. Для удовлетворения вызова выполняется не более одного чтения сжатого потока. Количество возвращаемых байтов может быть больше или меньше запрошенного.

Примечание

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

Added in version 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-like objects. Метод read() теперь принимает аргумент None.

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

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

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

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

Сжимает данные, возвращая объект bytes, содержащий сжатые данные. Значения compresslevel и mtime такие же, как и в конструкторе GzipFile выше. Когда mtime установлено в 0, эта функция эквивалентна zlib.compress() с wbits, установленным в 31. Функция zlib работает быстрее.

Added in version 3.2.

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

Изменено в версии 3.11: Скорость повышается за счет сжатия всех данных сразу, а не в потоковом режиме. Вызовы с mtime, установленным в 0, передаются в zlib.compress() для повышения скорости.

gzip.decompress(data)

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

Added in version 3.2.

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

Примеры использования

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

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

Показать сообщение о помощи.