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' для двоичного режима или '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: Принимает объект, подобный пути.

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'.

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

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

Аргумент mtime — необязательная числовая временная метка, которая будет записана в поле последнего изменения времени в потоке при сжатии. Его следует указывать только в режиме сжатия. Если он опущен или None, используется текущее время. Дополнительные сведения см. в атрибуте mtime.

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

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

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

gzip.compress(data, compresslevel=9)

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

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

gzip.decompress(data)

Распаковывает data, возвращая объект bytes с нескомпрессированными данными.

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

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

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

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)