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

New in version 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 выше. Когда mtime установлено в 0, эта функция эквивалентна zlib.compress() с wbits, установленным в 31. Функция zlib быстрее.

New in version 3.2.

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

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

gzip.decompress(data)

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

New in version 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)