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 и получить полученный буфер памяти с помощью метода объекта io.BytesIO getvalue().

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

Устарело начиная с версии 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)