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: Принимает объект пути.

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.

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

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

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)