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. При обработке некорректных файлов gzip также могут возникнуть исключения EOFError и zlib.error.

Добавлено в версии 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, поскольку после сжатых данных может потребоваться добавить другие данные. Это также позволяет передать в качестве fileobj открытый для записи объект io.BytesIO и получить результирующий буфер памяти с помощью метода 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: Добавлена поддержка записи произвольных объектов, подобных bytes. Метод 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() для повышения скорости. В этом случае выходные данные могут содержать в байте «OS» заголовка gzip значение, отличное от 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)