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

Исходный код: Lib/gzip.py

Этот модуль предоставляет простой интерфейс для сжатия и распаковки файлов, подобно тому, как это делают программы GNU gzip и gunzip.

Это опциональный модуль. Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к требованиям к опциональным модулям.

Сжатие данных обеспечивается модулем zlib.

Модуль gzip предоставляет класс GzipFile, а также вспомогательные функции open(), compress() и decompress(). Класс GzipFile читает и записывает файлы в формате gzip, автоматически сжимая или распаковывая данные, так что он выглядит как обычный файловый объект.

Обратите внимание, что дополнительные форматы файлов, которые могут быть распакованы программами gzip и gunzip, например, созданные программами compress и pack, не поддерживаются этим модулем.

Модуль определяет следующие элементы:

gzip.open(filename, mode='rb', compresslevel=6, 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: Принимает объект, подобный пути.

Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.

exception gzip.BadGzipFile¶

Исключение, возбуждаемое для недопустимых файлов gzip. Оно наследуется от OSError. EOFError и zlib.error также могут возбуждаться для недопустимых файлов gzip.

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

class gzip.GzipFile(filename=None, mode=None, compresslevel=6, 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 в 0, чтобы создать сжатый поток, не зависящий от времени создания. Если mtime опущен или равен None, используется текущее время; однако, если текущее время выходит за пределы диапазона с 00:00:00 UTC, 1 января 1970 года по 06:28:15 UTC, 7 февраля 2106 года, или явно переданный аргумент mtime выходит за пределы диапазона от 0 до 2**32-1, то вместо него используется значение 0.

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

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: Добавлена поддержка записи произвольных байтоподобных объектов. Метод read() теперь принимает аргумент None.

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

Устарело с версии 3.9: Открытие GzipFile для записи без указания аргумента mode является устаревшим.

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

Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.

gzip.compress(data, compresslevel=6, *, mtime=0)¶

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

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

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

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

Изменено в версии 3.13: Гарантируется, что байт ОС заголовка gzip будет установлен в 255 при использовании этой функции, как и в версиях 3.10 и более ранних.

Изменено в версии 3.14: Параметр mtime теперь по умолчанию равен 0 для воспроизводимого вывода. Для предыдущего поведения с использованием текущего времени передайте None в mtime.

Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.

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)