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.12: Удален атрибут filename, используйте атрибут name вместо него.

Устарело начиная с версии 3.9: Открытие GzipFile для записи без указания аргумента mode устарело.

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

Сжимает данные data, возвращая объект bytes со сжатыми данными. compresslevel и mtime имеют то же значение, что и в конструкторе GzipFile выше. Когда mtime задано как 0, эта функция эквивалентна zlib.compress() со значением wbits, установленным как 31. Функция zlib быстрее.

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

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

Изменено в версии 3.11: Скорость улучшена путем сжатия всех данных сразу вместо по потокам. Вызовы с mtime, установленным как 0, делегируются в zlib.compress() для лучшей скорости. В этом случае вывод может содержать значение байта заголовка gzip “OS”, отличное от 255 “неизвестно”, как предоставлено реализацией zlib.

gzip.decompress(data)

Разархивировать данные data, возвращая объект bytes, содержащий неархивированные данные. Данная функция способна разархивировать данные gzip с несколькими членами (несколько блоков gzip, склеенных вместе). Если известно, что данные содержат только один член, то функция zlib.decompress() с параметром wbits, установленным в 31, будет работать быстрее.

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

Изменено в версии 3.11: Скорость улучшена за счёт разархивирования членов сразу в памяти вместо поточно.

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)