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

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, отличное от 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)