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 — необязательная числовая временная метка, которая записывается в поле последнего изменения времени в потоке при сжатии. Он должен быть указан только в режиме сжатия. Если он опущен или 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().

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 устарело.

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

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

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

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

gzip.decompress(data)

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

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

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)