`bz2.md`

274 строк · 20.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/library/bz2.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# [`bz2`](https://python-all.ru/3.11/library/bz2.html#module-bz2) – Поддержка сжатия **bzip2**89**Исходный код:** [Lib/bz2.py](https://python-all.ru/src/3.11/Lib/bz2.py)1011---1213Этот модуль предоставляет полный интерфейс для сжатия и распаковки данных с использованием алгоритма сжатия bzip2.1415Модуль [`bz2`](https://python-all.ru/3.11/library/bz2.html#module-bz2) содержит:1617- Функция [`open()`](https://python-all.ru/3.11/library/bz2.html#bz2.open) и класс [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File) для чтения и записи сжатых файлов.18- Классы [`BZ2Compressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Compressor) и [`BZ2Decompressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor) для инкрементального сжатия и распаковки.19- Функции [`compress()`](https://python-all.ru/3.11/library/bz2.html#bz2.compress) и [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress) для одноразового сжатия и распаковки.2021## Сжатие и распаковка файлов2223#### `bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)`2425Открывает сжатый bzip2 файл в бинарном или текстовом режиме, возвращая [файловый объект](https://python-all.ru/3.11/glossary.html#term-file-object).2627Как и в случае с конструктором [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File), аргумент *filename* может быть фактическим именем файла (объектом [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes)) или существующим файловым объектом для чтения или записи.2829Аргумент *mode* может быть любым из `'r'`, `'rb'`, `'w'`, `'wb'`, `'x'`, `'xb'`, `'a'` или `'ab'` для бинарного режима, или `'rt'`, `'wt'`, `'xt'` или `'at'` для текстового режима. По умолчанию `'rb'`.3031Аргумент *compresslevel* – целое число от 1 до 9, как и у конструктора [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File).3233В бинарном режиме эта функция эквивалентна конструктору [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File): `BZ2File(filename, mode, compresslevel=compresslevel)`. В этом случае аргументы *encoding*, *errors* и *newline* не должны передаваться.3435Для текстового режима создаётся объект [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File), обёрнутый в экземпляр [`io.TextIOWrapper`](https://python-all.ru/3.11/library/io.html#io.TextIOWrapper) с указанными кодировкой, поведением при ошибках и символами конца строки.3637Новое в версии 3.3.3839Изменено в версии 3.4: Добавлен режим `'x'` (эксклюзивное создание).4041Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.11/glossary.html#term-path-like-object).4243#### `class bz2.BZ2File(filename, mode='r', *, compresslevel=9)`4445Открывает сжатый bzip2 файл в бинарном режиме.4647Если *filename* – объект [`str`](https://python-all.ru/3.11/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.11/library/stdtypes.html#bytes), открыть указанный файл напрямую. В противном случае *filename* должен быть [файловым объектом](https://python-all.ru/3.11/glossary.html#term-file-object), который будет использоваться для чтения или записи сжатых данных.4849Аргумент *mode* может быть `'r'` для чтения (по умолчанию), `'w'` для перезаписи, `'x'` для исключительного создания или `'a'` для добавления. Им эквивалентно соответствуют `'rb'`, `'wb'`, `'xb'` и `'ab'` соответственно.5051Если *filename* – файловый объект (а не фактическое имя файла), режим `'w'` не усекает файл, а вместо этого эквивалентен `'a'`.5253Если *mode* – `'w'` или `'a'`, *compresslevel* может быть целым числом от `1` до `9`, задающим уровень сжатия: `1` даёт наименьшее сжатие, а `9` (по умолчанию) – наибольшее.5455Если *mode* – `'r'`, входной файл может быть объединением нескольких сжатых потоков.5657[`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File) предоставляет все члены, указанные в [`io.BufferedIOBase`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase), за исключением [`detach()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.detach) и [`truncate()`](https://python-all.ru/3.11/library/io.html#io.IOBase.truncate). Поддерживаются итерация и оператор [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).5859[`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File) также предоставляет следующие методы:6061#### `peek([n])`6263Возвращает буферизованные данные без продвижения файловой позиции. Будет возвращён как минимум один байт данных (если не достигнут конец файла). Точное количество возвращаемых байт не указано.6465> **Примечание**66>67> Хотя вызов [`peek()`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File.peek) не меняет файловую позицию [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File), он может изменить позицию нижележащего файлового объекта (например, если [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File) был создан путём передачи файлового объекта в качестве *filename*).6869Новое в версии 3.3.7071#### `fileno()`7273Возвращает файловый дескриптор базового файла.7475Новое в версии 3.3.7677#### `readable()`7879Возвращает, был ли файл открыт для чтения.8081Новое в версии 3.3.8283#### `seekable()`8485Возвращает, поддерживает ли файл позиционирование.8687Новое в версии 3.3.8889#### `writable()`9091Возвращает, был ли файл открыт для записи.9293Новое в версии 3.3.9495#### `read1(size=-1)`9697Читает не более *size* несжатых байт, стараясь не выполнять несколько операций чтения из нижележащего потока. Если size отрицателен, читает данные объёмом до одного буфера.9899Возвращает `b''`, если достигнут конец файла (EOF).100101Новое в версии 3.3.102103#### `readinto(b)`104105Читает байты в *b*.106107Возвращает количество прочитанных байт (0 – конец файла).108109Новое в версии 3.3.110111Изменено в версии 3.1: Добавлена поддержка оператора [`with`](https://python-all.ru/3.11/reference/compound_stmts.html#with).112113Изменено в версии 3.3: Добавлена поддержка передачи *filename* в качестве [файлового объекта](https://python-all.ru/3.11/glossary.html#term-file-object) вместо реального имени файла.114115Добавлен режим `'a'` (добавление) и поддержка чтения файлов с несколькими потоками.116117Изменено в версии 3.4: Добавлен режим `'x'` (эксклюзивное создание).118119Изменено в версии 3.5: Метод [`read()`](https://python-all.ru/3.11/library/io.html#io.BufferedIOBase.read) теперь принимает аргумент типа `None`.120121Изменено в версии 3.6: Принимает [объект, подобный пути](https://python-all.ru/3.11/glossary.html#term-path-like-object).122123Изменено в версии 3.9: Параметр *buffering* был удалён. Он игнорировался и считался устаревшим начиная с Python 3.0. Для управления открытием файла передавайте открытый файловый объект.124125Параметр *compresslevel* стал строго именованным аргументом.126127Изменено в версии 3.10: Этот класс не является потокобезопасным при одновременном чтении или записи из нескольких потоков – как и его аналоги в модулях [`gzip`](https://python-all.ru/3.11/library/gzip.html#module-gzip) и [`lzma`](https://python-all.ru/3.11/library/lzma.html#module-lzma).128129## Инкрементальное (де)сжатие130131#### `class bz2.BZ2Compressor(compresslevel=9)`132133Создаёт новый объект компрессора. Этот объект можно использовать для инкрементального сжатия данных. Для однократного сжатия используйте функцию [`compress()`](https://python-all.ru/3.11/library/bz2.html#bz2.compress).134135*compresslevel*, если указан, должен быть целым числом между `1` и `9`. По умолчанию `9`.136137#### `compress(data)`138139Передаёт данные объекту компрессора. Возвращает сжатый фрагмент данных, если возможно, или пустую байтовую строку в противном случае.140141После завершения передачи данных компрессору следует вызвать метод [`flush()`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Compressor.flush) для завершения процесса сжатия.142143#### `flush()`144145Завершает процесс сжатия. Возвращает сжатые данные, оставшиеся во внутренних буферах.146147Объект компрессора нельзя использовать после вызова этого метода.148149#### `class bz2.BZ2Decompressor`150151Создаёт новый объект декомпрессора. Этот объект можно использовать для инкрементальной декомпрессии данных. Для одноразового сжатия используйте функцию [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress) вместо этого.152153> **Примечание**154>155> Этот класс не обрабатывает прозрачно входные данные, содержащие несколько сжатых потоков, в отличие от [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress) и [`BZ2File`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2File). Если необходимо декомпрессировать многопоточный вход с помощью [`BZ2Decompressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor), нужно использовать новый декомпрессор для каждого потока.156157#### `decompress(data, max_length=-1)`158159Декомпрессирует *data* ([байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object)), возвращая несжатые данные в виде байтов. Часть *data* может буферизироваться внутренне для использования в последующих вызовах [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress). Возвращаемые данные следует объединять с результатом любых предыдущих вызовов [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress).160161Если *max\_length* неотрицательно, возвращает не более *max\_length* байтов декомпрессированных данных. Если этот лимит достигнут и может быть сгенерирован дальнейший вывод, атрибут [`needs_input`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor.needs_input) будет установлен в `False`. В этом случае следующий вызов [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor.decompress) может передать *data* как `b''` для получения ещё вывода.162163Если все входные данные были декомпрессированы и возвращены (либо потому что это было меньше *max\_length* байтов, либо потому что *max\_length* было отрицательным), атрибут [`needs_input`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor.needs_input) будет установлен в `True`.164165Попытка декомпрессировать данные после достижения конца потока вызывает [`EOFError`](https://python-all.ru/3.11/library/exceptions.html#EOFError). Любые данные, обнаруженные после конца потока, игнорируются и сохраняются в атрибуте [`unused_data`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor.unused_data).166167Изменено в версии 3.5: Добавлен параметр *max\_length*.168169#### `eof`170171`True`, если достигнут маркер конца потока.172173Новое в версии 3.3.174175#### `unused_data`176177Данные, обнаруженные после конца сжатого потока.178179Если к этому атрибуту обратиться до достижения конца потока, его значение будет `b''`.180181#### `needs_input`182183`False`, если метод [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor.decompress) может предоставить больше декомпрессированных данных до запроса нового несжатого входа.184185Новое в версии 3.5.186187## Одноразовое (де)сжатие188189#### `bz2.compress(data, compresslevel=9)`190191Сжимает *data*, [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object).192193*compresslevel*, если указан, должен быть целым числом между `1` и `9`. По умолчанию `9`.194195Для инкрементального сжатия используйте [`BZ2Compressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Compressor).196197#### `bz2.decompress(data)`198199Декомпрессирует *data*, [байтоподобный объект](https://python-all.ru/3.11/glossary.html#term-bytes-like-object).200201Если *data* является объединением нескольких сжатых потоков, декомпрессирует все потоки.202203Для инкрементальной декомпрессии используйте [`BZ2Decompressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Decompressor).204205Изменено в версии 3.3: Добавлена поддержка многопоточных входных данных.206207## Примеры использования208209Ниже приведены несколько примеров типичного использования модуля [`bz2`](https://python-all.ru/3.11/library/bz2.html#module-bz2).210211Использование [`compress()`](https://python-all.ru/3.11/library/bz2.html#bz2.compress) и [`decompress()`](https://python-all.ru/3.11/library/bz2.html#bz2.decompress) для демонстрации двустороннего сжатия:212213```python214>>> import bz2215>>> data = b"""\216... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue217... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,218... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus219... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.220... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo221... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum222... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""223>>> c = bz2.compress(data)224>>> len(data) / len(c)  # Коэффициент сжатия данных2251.513595166163142226>>> d = bz2.decompress(c)227>>> data == d  # Проверка равенства исходному объекту после полного цикла сжатия-распаковки228True229```230231Использование [`BZ2Compressor`](https://python-all.ru/3.11/library/bz2.html#bz2.BZ2Compressor) для инкрементального сжатия:232233```python234>>> import bz2235>>> def gen_data(chunks=10, chunksize=1000):236...     """Выдаёт инкрементальные блоки по chunksize байт."""237...     for _ in range(chunks):238...         yield b"z" * chunksize239...240>>> comp = bz2.BZ2Compressor()241>>> out = b""242>>> for chunk in gen_data():243...     # Передаёт данные объекту сжатия244...     out = out + comp.compress(chunk)245...246>>> # Завершает процесс сжатия. Вызывайте этот метод после того, как247>>> # завершена передача данных компрессору.248>>> out = out + comp.flush()249```250251В приведённом примере используется очень «неслучайный» поток данных (поток фрагментов `b"z"`). Случайные данные обычно сжимаются плохо, тогда как упорядоченные повторяющиеся данные обычно дают высокую степень сжатия.252253Запись и чтение сжатого bzip2 файла в двоичном режиме:254255```python256>>> import bz2257>>> data = b"""\258... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue259... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,260... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus261... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.262... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo263... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum264... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""265>>> with bz2.open("myfile.bz2", "wb") as f:266...     # Записать сжатые данные в файл267...     unused = f.write(data)268>>> with bz2.open("myfile.bz2", "rb") as f:269...     # Распаковать данные из файла270...     content = f.read()271>>> content == data  # Проверка равенства исходному объекту после полного цикла сжатия-распаковки272True273```274