gzip.md

1> **Источник:** https://python-all.ru/3.16/library/gzip.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `gzip` – Поддержка файлов **gzip**89**Исходный код:** [Lib/gzip.py](https://python-all.ru/src/main/Lib/gzip.py)1011---1213Этот модуль предоставляет простой интерфейс для сжатия и распаковки файлов, подобно тому, как это делают программы GNU **gzip** и **gunzip**.1415Это [опциональный модуль](https://python-all.ru/3.16/glossary.html#term-optional-module). Если его нет в вашей копии CPython, обратитесь к документации от вашего дистрибьютора (то есть того, кто предоставил вам Python). Если вы дистрибьютор, обратитесь к [требованиям к опциональным модулям](https://python-all.ru/3.16/using/configure.html#optional-module-requirements).1617Сжатие данных обеспечивается модулем [`zlib`](https://python-all.ru/3.16/library/zlib.html#module-zlib).1819Модуль `gzip` предоставляет класс [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile), а также вспомогательные функции [`open()`](https://python-all.ru/3.16/library/gzip.html#gzip.open), [`compress()`](https://python-all.ru/3.16/library/gzip.html#gzip.compress) и [`decompress()`](https://python-all.ru/3.16/library/gzip.html#gzip.decompress). Класс `GzipFile` читает и записывает файлы в формате **gzip**, автоматически сжимая или распаковывая данные, так что он выглядит как обычный [файловый объект](https://python-all.ru/3.16/glossary.html#term-file-object).2021Обратите внимание, что дополнительные форматы файлов, которые могут быть распакованы программами **gzip** и **gunzip**, например, созданные программами **compress** и **pack**, не поддерживаются этим модулем.2223Модуль определяет следующие элементы:2425#### `gzip.open(filename, mode='rb', compresslevel=6, encoding=None, errors=None, newline=None, *, mtime=None)`2627Открывает файл, сжатый gzip, в двоичном или текстовом режиме и возвращает [файловый объект](https://python-all.ru/3.16/glossary.html#term-file-object).2829Аргумент *filename* может быть фактическим именем файла (объектом [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes)) или существующим файловым объектом для чтения или записи.3031Аргумент *mode* может быть любым из `'r'`, `'rb'`, `'a'`, `'ab'`, `'w'`, `'wb'`, `'x'` или `'xb'` для бинарного режима, или `'rt'`, `'at'`, `'wt'` или `'xt'` для текстового режима. По умолчанию `'rb'`.3233Аргумент *compresslevel* – целое число от 0 до 9, как для конструктора [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile).3435Аргумент *mtime*, передаваемый только по ключу, представляет собой метку времени Unix.3637В двоичном режиме эта функция эквивалентна конструктору [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile): `GzipFile(filename, mode, compresslevel, mtime=mtime)`. В этом случае аргументы *encoding*, *errors* и *newline* не должны передаваться.3839Для текстового режима создаётся объект [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile), обёрнутый в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3.16/library/io.html#io.TextIOWrapper) с указанными кодировкой, поведением при ошибках и символами конца строки.4041Изменено в версии 3.3: Добавлена поддержка *filename* в качестве файлового объекта, поддержка текстового режима, и аргументов *encoding*, *errors* и *newline*.4243Изменено в версии 3.4: Добавлена поддержка режимов `'x'`, `'xb'` и `'xt'`.4445Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object).4647Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.4849Изменено в версии 3.16.0a0 (не выпущена): Добавлен аргумент *mtime*, передаваемый только по ключу, который передается конструктору класса [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile).5051#### `exception gzip.BadGzipFile`5253Исключение, возбуждаемое для недопустимых файлов gzip. Оно наследуется от [`OSError`](https://python-all.ru/3.16/library/exceptions.html#OSError). [`EOFError`](https://python-all.ru/3.16/library/exceptions.html#EOFError) и [`zlib.error`](https://python-all.ru/3.16/library/zlib.html#zlib.error) также могут возбуждаться для недопустимых файлов gzip.5455Добавлено в версии 3.8.5657#### `class gzip.GzipFile(filename=None, mode=None, compresslevel=6, fileobj=None, mtime=None)`5859Конструктор класса `GzipFile`, который имитирует большинство методов [файлового объекта](https://python-all.ru/3.16/glossary.html#term-file-object), за исключением метода [`truncate()`](https://python-all.ru/3.16/library/io.html#io.IOBase.truncate). По крайней мере один из *fileobj* и *filename* должен иметь нетривиальное значение.6061Новый экземпляр класса основан на *fileobj*, который может быть обычным файлом, объектом [`io.BytesIO`](https://python-all.ru/3.16/library/io.html#io.BytesIO) или любым другим объектом, имитирующим файл. По умолчанию он равен `None`, и в этом случае *filename* открывается для предоставления файлового объекта.6263Если *fileobj* не равен `None`, аргумент *filename* используется только для включения в заголовок файла **gzip**, который может содержать исходное имя файла несжатого файла. По умолчанию он равен имени файла *fileobj*, если его можно определить; в противном случае по умолчанию используется пустая строка, и в этом случае исходное имя файла не включается в заголовок.6465Аргумент *mode* может быть любым из `'r'`, `'rb'`, `'a'`, `'ab'`, `'w'`, `'wb'`, `'x'` или `'xb'`, в зависимости от того, будет ли файл читаться или записываться. По умолчанию используется режим *fileobj*, если его можно определить; в противном случае по умолчанию используется `'rb'`. В будущих версиях Python режим *fileobj* не будет использоваться. Лучше всегда указывать *mode* для записи.6667Обратите внимание, что файл всегда открывается в двоичном режиме. Чтобы открыть сжатый файл в текстовом режиме, используйте [`open()`](https://python-all.ru/3.16/library/gzip.html#gzip.open) (или оберните свой `GzipFile` с помощью [`io.TextIOWrapper`](https://python-all.ru/3.16/library/io.html#io.TextIOWrapper)).6869Аргумент *compresslevel* – целое число от `0` до `9`, управляющее уровнем сжатия; `1` – самый быстрый и даёт наименьшее сжатие, а `9` – самый медленный и даёт наибольшее сжатие. `0` – это отсутствие сжатия. По умолчанию `9`.7071Необязательный аргумент *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`.7273Смотрите ниже атрибут [`mtime`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile.mtime), который устанавливается при распаковке.7475Вызов метода `close()` объекта `GzipFile` не закрывает *fileobj*, поскольку может потребоваться добавить ещё данные после сжатых данных. Это также позволяет передать объект [`io.BytesIO`](https://python-all.ru/3.16/library/io.html#io.BytesIO), открытый для записи, в качестве *fileobj*, и получить результирующий буфер в памяти с помощью метода [`getvalue()`](https://python-all.ru/3.16/library/io.html#io.BytesIO.getvalue) объекта `io.BytesIO`.7677`GzipFile` поддерживает интерфейс [`io.BufferedIOBase`](https://python-all.ru/3.16/library/io.html#io.BufferedIOBase), включая итерацию и оператор [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with). Не реализован только метод [`truncate()`](https://python-all.ru/3.16/library/io.html#io.IOBase.truncate).7879`GzipFile` также предоставляет следующий метод и атрибут:8081#### `peek(n)`8283Читает *n* несжатых байт без изменения позиции файла. Количество возвращаемых байт может быть больше или меньше запрошенного.8485> **Примечание**86>87> Хотя вызов `peek()` не изменяет позицию файла объекта `GzipFile`, он может изменить позицию нижележащего файлового объекта (например, если `GzipFile` был создан с параметром *fileobj*).8889Добавлено в версии 3.2.9091#### `mode`9293`'rb'` для чтения и `'wb'` для записи.9495Изменено в версии 3.13: В предыдущих версиях это было целое число `1` или `2`.9697#### `mtime`9899При распаковке этот атрибут устанавливается в последнюю временную метку из самого последнего прочитанного заголовка. Это целое число, содержащее количество секунд с начала эпохи Unix (00:00:00 UTC, 1 января 1970 г.). Начальное значение до чтения любого заголовка – `None`.100101#### `name`102103Путь к файлу gzip на диске, как [`str`](https://python-all.ru/3.16/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes). Эквивалентен выводу [`os.fspath()`](https://python-all.ru/3.16/library/os.html#os.fspath) для исходного пути ввода, без какой-либо дополнительной нормализации, разрешения или раскрытия.104105Изменено в версии 3.1: Добавлена поддержка оператора [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with), а также аргумента конструктора *mtime* и атрибута [`mtime`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile.mtime).106107Изменено в версии 3.2: Добавлена поддержка файлов с дополнением нулями и непозиционируемых файлов.108109Изменено в версии 3.3: Теперь реализован метод [`io.BufferedIOBase.read1()`](https://python-all.ru/3.16/library/io.html#io.BufferedIOBase.read1).110111Изменено в версии 3.4: Добавлена поддержка режимов `'x'` и `'xb'`.112113Изменено в версии 3.5: Добавлена поддержка записи произвольных [байтоподобных объектов](https://python-all.ru/3.16/glossary.html#term-bytes-like-object). Метод [`read()`](https://python-all.ru/3.16/library/io.html#io.BufferedIOBase.read) теперь принимает аргумент `None`.114115Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.16/glossary.html#term-path-like-object).116117Устарело с версии 3.9: Открытие `GzipFile` для записи без указания аргумента *mode* является устаревшим.118119Изменено в версии 3.12: Удалён атрибут `filename`, вместо него используйте атрибут [`name`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile.name).120121Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.122123#### `gzip.compress(data, compresslevel=6, *, mtime=0)`124125Сжимает *data*, возвращая объект [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), содержащий сжатые данные. *compresslevel* и *mtime* имеют тот же смысл, что и в [`GzipFile`](https://python-all.ru/3.16/library/gzip.html#gzip.GzipFile) конструкторе выше, но *mtime* по умолчанию равен 0 для воспроизводимого вывода.126127Добавлено в версии 3.2.128129Изменено в версии 3.8: Добавлен параметр *mtime* для воспроизводимого вывода.130131Изменено в версии 3.11: Скорость улучшена за счёт сжатия всех данных сразу, а не потоковым способом. Вызовы с *mtime*, установленным в `0`, перенаправляются в [`zlib.compress()`](https://python-all.ru/3.16/library/zlib.html#zlib.compress) для лучшей скорости. В этой ситуации вывод может содержать значение байта «ОС» заголовка gzip, отличное от 255 «неизвестно», которое предоставляется базовой реализацией zlib.132133Изменено в версии 3.13: Гарантируется, что байт ОС заголовка gzip будет установлен в 255 при использовании этой функции, как и в версиях 3.10 и более ранних.134135Изменено в версии 3.14: Параметр *mtime* теперь по умолчанию равен 0 для воспроизводимого вывода. Для предыдущего поведения с использованием текущего времени передайте `None` в *mtime*.136137Изменено в версии 3.15: Уровень сжатия по умолчанию был снижен до 6 (с 9). Это уровень, используемый большинством инструментов сжатия, и он обеспечивает более удачный компромисс между скоростью и производительностью.138139#### `gzip.decompress(data)`140141Распаковывает *data*, возвращая объект [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), содержащий распакованные данные. Эта функция может распаковывать многокомпонентные данные gzip (несколько блоков gzip, объединённых вместе). Если данные точно содержат только один компонент, функция [`zlib.decompress()`](https://python-all.ru/3.16/library/zlib.html#zlib.decompress) с *wbits*, установленным в 31, работает быстрее.142143Добавлено в версии 3.2.144145Изменено в версии 3.11: Скорость улучшена за счёт распаковки компонентов сразу в памяти, а не потоковым способом.146147## Примеры использования148149Пример чтения сжатого файла:150151```python152import gzip153with gzip.open('/home/joe/file.txt.gz', 'rb') as f:154    file_content = f.read()155```156157Пример создания сжатого файла GZIP:158159```python160import gzip161content = b"Lots of content here"162with gzip.open('/home/joe/file.txt.gz', 'wb') as f:163    f.write(content)164```165166Пример сжатия существующего файла в формате GZIP:167168```python169import gzip170import shutil171with open('/home/joe/file.txt', 'rb') as f_in:172    with gzip.open('/home/joe/file.txt.gz', 'wb') as f_out:173        shutil.copyfileobj(f_in, f_out)174```175176Пример сжатия бинарной строки в формате GZIP:177178```python179import gzip180s_in = b"Lots of content here"181s_out = gzip.compress(s_in)182```183184> **См. также**185>186> **Модуль [`zlib`](https://python-all.ru/3.16/library/zlib.html#module-zlib)**187>188> Базовый модуль сжатия данных, необходимый для поддержки формата файлов **gzip**.189>190> Если сжатие/распаковка gzip является узким местом, пакет [python-isal](https://python-all.ru/3.16/library/gzip.html) ускоряет сжатие/распаковку с помощью почти совместимого API.191192## Интерфейс командной строки193194Модуль `gzip` предоставляет простой интерфейс командной строки для сжатия или распаковки файлов.195196После выполнения модуль `gzip` сохраняет входной файл(ы).197198Изменено в версии 3.8: Добавлен новый интерфейс командной строки с описанием использования. По умолчанию при выполнении CLI уровень сжатия равен 6.199200### Параметры командной строки201202#### `file`203204Если *file* не указан, чтение из [`sys.stdin`](https://python-all.ru/3.16/library/sys.html#sys.stdin).205206#### `--fast`207208Указывает самый быстрый метод сжатия (меньше степень сжатия).209210#### `--best`211212Указывает самый медленный метод сжатия (наилучшее сжатие).213214#### `-d, --decompress`215216Распаковывает указанный файл.217218#### `-h, --help`219220Показывает справочное сообщение.221