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

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.

gzip.compress(data, compresslevel=9)

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

Введено в версии 3.2.

gzip.decompress(data)

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

Введено в версии 3.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)