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 — это временная метка, запрошенная gzip. Время задаётся в формате Unix, то есть в секундах с 00:00:00 UTC 1 января 1970 года. Если mtime не указан или равен None, используется текущее время. Установите mtime = 0, чтобы сгенерировать сжатый поток, не зависящий от времени создания.

См. ниже описание атрибута 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.

mode

'rb' для чтения и 'wb' для записи.

Изменено в версии 3.13: В предыдущих версиях это было целое число 1 или 2.

mtime

При распаковке этому атрибуту присваивается последняя временная метка из последнего прочитанного заголовка. Это целое число, содержащее количество секунд с начала эпохи Unix (00:00:00 UTC 1 января 1970 года). До чтения каких-либо заголовков начальным значением является None.

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.9: Открытие GzipFile для записи без указания аргумента mode считается устаревшим.

Изменено в версии 3.12: Удалён атрибут filename; вместо него используйте атрибут name.

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

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

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

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

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

Изменено в версии 3.13: Гарантируется, что байт OS заголовка gzip будет равен 255, как и в версиях 3.10 и более ранних.

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)