bz2
— Support for bzip2 compression¶
Вихідний код: Lib/bz2.py
Цей модуль забезпечує комплексний інтерфейс для стиснення та розпакування даних за допомогою алгоритму стиснення bzip2.
Модуль bz2
містить:
Функція
open()
і класBZ2File
для читання та запису стиснених файлів.Класи
BZ2Compressor
іBZ2Decompressor
для поступового (де)стиснення.Функції
compress()
іdecompress()
для одноразового (де)стиснення.
(Де)компресія файлів¶
- bz2.open(filename, mode='rb', compresslevel=9, encoding=None, errors=None, newline=None)¶
Відкрийте файл, стиснутий за допомогою bzip2, у двійковому або текстовому режимі, повертаючи file object.
Як і у випадку з конструктором для
BZ2File
, аргумент filename може бути фактичним ім’ям файлу (об’єктstr
абоbytes
) або наявним файловим об’єктом для читання чи запису до.Аргумент mode може бути будь-яким із
'r'
,'rb'
,'w'
,'wb'
,'x'
,'xb'
,'a'
або'ab'
для бінарного режиму або'rt'
,'wt'
,'xt'
або'at'
для текстового режиму. Типовим є'rb'
.Аргумент compresslevel є цілим числом від 1 до 9, як і для конструктора
BZ2File
.Для двійкового режиму ця функція еквівалентна конструктору
BZ2File
:BZ2File(filename, mode, compresslevel=compresslevel)
. У цьому випадку аргументи encoding, errors і newline не повинні надаватися.Для текстового режиму створюється об’єкт
BZ2File
, який загортається в екземплярio.TextIOWrapper
із вказаним кодуванням, поведінкою обробки помилок і закінченнями рядків.Added in version 3.3.
Змінено в версії 3.4: Додано режим
'x
(ексклюзивне створення).Змінено в версії 3.6: Приймає path-like object.
- class bz2.BZ2File(filename, mode='r', *, compresslevel=9)¶
Відкрийте файл, стиснутий за допомогою bzip2, у двійковому режимі.
Якщо filename є об’єктом
str
абоbytes
, відкрийте названий файл безпосередньо. В іншому випадку filename має бути file object, який використовуватиметься для читання або запису стиснутих даних.Аргументом mode може бути
'r'
для читання (за замовчуванням),'w'
для перезапису,'x'
для ексклюзивного створення або'a'
для додавання. Їх можна еквівалентно вказати як'rb'
,'wb'
,'xb'
і'ab'
відповідно.Якщо filename є об’єктом файлу (а не справжнім ім’ям файлу), режим
'w'
не скорочує файл, а замість цього еквівалентний'a'
.Якщо mode має значення
'w'
або'a'
, compresslevel може бути цілим числом від1
до9
, що визначає рівень стиснення:1
створює найменше стиснення, а9
(за замовчуванням) створює найбільше стиснення.Якщо mode має значення
'r'
, вхідний файл може бути конкатенацією кількох стиснутих потоків.BZ2File
provides all of the members specified by theio.BufferedIOBase
, except fordetach()
andtruncate()
. Iteration and thewith
statement are supported.BZ2File
also provides the following methods and attributes:- peek([n])¶
Повернути буферизовані дані без просування позиції файлу. Буде повернено принаймні один байт даних (якщо не EOF). Точна кількість повернутих байтів не вказана.
Примітка
Хоча виклик
peek()
не змінює позицію файлуBZ2File
, він може змінити позицію основного файлового об’єкта (наприклад, якщоBZ2File
було створено шляхом передачі файлового об’єкта для ім’я файлу).Added in version 3.3.
- fileno()¶
Return the file descriptor for the underlying file.
Added in version 3.3.
- readable()¶
Return whether the file was opened for reading.
Added in version 3.3.
- seekable()¶
Return whether the file supports seeking.
Added in version 3.3.
- writable()¶
Return whether the file was opened for writing.
Added in version 3.3.
- read1(size=-1)¶
Read up to size uncompressed bytes, while trying to avoid making multiple reads from the underlying stream. Reads up to a buffer’s worth of data if size is negative.
Returns
b''
if the file is at EOF.Added in version 3.3.
- readinto(b)¶
Read bytes into b.
Returns the number of bytes read (0 for EOF).
Added in version 3.3.
- mode¶
'rb'
for reading and'wb'
for writing.Added in version 3.13.
- name¶
The bzip2 file name. Equivalent to the
name
attribute of the underlying file object.Added in version 3.13.
Змінено в версії 3.1: Додано підтримку оператора
with
.Змінено в версії 3.3: Було додано підтримку для filename як file object замість фактичної назви файлу.
Було додано режим
'a'
(додавання) разом із підтримкою читання багатопотокових файлів.Змінено в версії 3.4: Додано режим
'x
(ексклюзивне створення).Змінено в версії 3.5: Метод
read()
тепер приймає аргументNone
.Змінено в версії 3.6: Приймає path-like object.
Змінено в версії 3.9: Параметр buffering видалено. Він був проігнорований і застарілим, починаючи з Python 3.0. Передайте відкритий файловий об’єкт, щоб контролювати, як відкривається файл.
Параметр compresslevel став лише ключовим словом.
Поступове (роз)стиснення¶
- class bz2.BZ2Compressor(compresslevel=9)¶
Створіть новий об’єкт компресора. Цей об’єкт можна використовувати для поступового стиснення даних. Для одноразового стиснення замість цього використовуйте функцію
compress()
.compresslevel, якщо задано, має бути цілим числом від
1
до9
. Типовим значенням є9
.- compress(data)¶
Надайте дані об’єкту компресора. Повертає фрагмент стиснутих даних, якщо це можливо, або порожній рядок байтів в іншому випадку.
Коли ви закінчите надсилати дані компресору, викличте метод
flush()
, щоб завершити процес стиснення.
- flush()¶
Завершіть процес стиснення. Повертає стислі дані, що залишилися у внутрішніх буферах.
Об’єкт компресора не можна використовувати після виклику цього методу.
- class bz2.BZ2Decompressor¶
Створіть новий об’єкт декомпресора. Цей об’єкт можна використовувати для поступового розпакування даних. Для одноразового стиснення замість цього використовуйте функцію
decompress()
.Примітка
Цей клас не обробляє прозоро вхідні дані, що містять кілька стиснутих потоків, на відміну від
decompress()
іBZ2File
. Якщо вам потрібно розпакувати багатопотоковий вхід за допомогоюBZ2Decompressor
, ви повинні використовувати новий розпаковувач для кожного потоку.- decompress(data, max_length=-1)¶
Розпакуйте дані (bytes-like object), повертаючи нестиснуті дані у вигляді байтів. Деякі з даних можуть бути збережені у внутрішньому буфері для використання в подальших викликах
decompress()
. Повернуті дані мають бути об’єднані з результатами будь-яких попередніх викликівdecompress()
.Якщо max_length є невід’ємним, повертає щонайбільше max_length байтів розпакованих даних. Якщо цей ліміт буде досягнуто, і буде створено подальший вихід, атрибут
needs_input
буде встановлено наFalse
. У цьому випадку наступний викликdecompress()
може надати data якb''
, щоб отримати більше вихідних даних.Якщо всі вхідні дані було розпаковано та повернуто (або через те, що вони були меншими за max_length байтів, або через те, що max_length було від’ємним), для атрибута
needs_input
буде встановлено значенняTrue
.Attempting to decompress data after the end of stream is reached raises an
EOFError
. Any data found after the end of the stream is ignored and saved in theunused_data
attribute.Змінено в версії 3.5: Додано параметр max_length.
- eof¶
True
, якщо досягнуто маркера кінця потоку.Added in version 3.3.
- unused_data¶
Дані знайдено після закінчення стисненого потоку.
Якщо цей атрибут доступний до досягнення кінця потоку, його значення буде
b''
.
- needs_input¶
False
, якщо методdecompress()
може надати більше розпакованих даних перед запитом нового нестисненого введення.Added in version 3.5.
Одноразова (де)компресія¶
- bz2.compress(data, compresslevel=9)¶
Стиснути data, байт-подібний об’єкт.
compresslevel, якщо задано, має бути цілим числом від
1
до9
. Типовим значенням є9
.Для інкрементного стиснення замість цього використовуйте
BZ2Compressor
.
- bz2.decompress(data)¶
Розархівуйте data, байт-подібний об’єкт.
Якщо data є конкатенацією кількох стиснутих потоків, розпакуйте всі потоки.
Для інкрементної декомпресії замість цього використовуйте
BZ2Decompressor
.Змінено в версії 3.3: Додано підтримку багатопотокових входів.
Приклади вживання¶
Нижче наведено декілька прикладів типового використання модуля bz2
.
Використання compress()
і decompress()
для демонстрації двостороннього стиснення:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> c = bz2.compress(data)
>>> len(data) / len(c) # Data compression ratio
1.513595166163142
>>> d = bz2.decompress(c)
>>> data == d # Check equality to original object after round-trip
True
Використання BZ2Compressor
для поступового стиснення:
>>> import bz2
>>> def gen_data(chunks=10, chunksize=1000):
... """Yield incremental blocks of chunksize bytes."""
... for _ in range(chunks):
... yield b"z" * chunksize
...
>>> comp = bz2.BZ2Compressor()
>>> out = b""
>>> for chunk in gen_data():
... # Provide data to the compressor object
... out = out + comp.compress(chunk)
...
>>> # Finish the compression process. Call this once you have
>>> # finished providing data to the compressor.
>>> out = out + comp.flush()
The example above uses a very «nonrandom» stream of data
(a stream of b"z"
chunks). Random data tends to compress poorly,
while ordered, repetitive data usually yields a high compression ratio.
Запис і читання файлу, стисненого bzip2, у двійковому режимі:
>>> import bz2
>>> data = b"""\
... Donec rhoncus quis sapien sit amet molestie. Fusce scelerisque vel augue
... nec ullamcorper. Nam rutrum pretium placerat. Aliquam vel tristique lorem,
... sit amet cursus ante. In interdum laoreet mi, sit amet ultrices purus
... pulvinar a. Nam gravida euismod magna, non varius justo tincidunt feugiat.
... Aliquam pharetra lacus non risus vehicula rutrum. Maecenas aliquam leo
... felis. Pellentesque semper nunc sit amet nibh ullamcorper, ac elementum
... dolor luctus. Curabitur lacinia mi ornare consectetur vestibulum."""
>>> with bz2.open("myfile.bz2", "wb") as f:
... # Write compressed data to file
... unused = f.write(data)
...
>>> with bz2.open("myfile.bz2", "rb") as f:
... # Decompress data from file
... content = f.read()
...
>>> content == data # Check equality to original object after round-trip
True