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