gzip – Поддержка файлов gzip¶gzip – Support for gzip files

Исходный код: 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: Принимает объект, подобный пути.

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

Обратите внимание, что файл всегда открывается в двоичном режиме. Чтобы открыть сжатый файл в текстовом режиме, используйте 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().

Изменено в версии 3.1: Добавлена поддержка оператора with, а также аргумента конструктора mtime и атрибута mtime.

Изменено в версии 3.2: Добавлена поддержка файлов с дополнением нулями и непозиционируемых файлов.

Изменено в версии 3.3: Теперь реализован метод io.BufferedIOBase.read1().

Изменено в версии 3.4: Добавлена поддержка режимов 'x' и 'xb'.

Изменено в версии 3.5: Добавлена поддержка записи произвольных байтоподобных объектов. Метод read() теперь принимает аргумент None.

Изменено в версии 3.6: Принимает объект, подобный пути.

gzip.compress(data, compresslevel=9)¶

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

Новое в версии 3.2.

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)