`bz2`

The Python bz2 module provides support for compressing and decompressing data using the bzip2 algorithm. It offers three complementary APIs: one-shot functions for in-memory data, a file-oriented class for reading and writing .bz2 files, and incremental classes for streaming large datasets.

Here’s a quick example:

>>> import bz2

>>> data = b"Real Python rocks! " * 10
>>> compressed = bz2.compress(data)
>>> bz2.decompress(compressed) == data
True

Key Features

Compresses and decompresses data using the bzip2 algorithm
Reads and writes .bz2 files in binary or text mode
Supports incremental (de)compression for streaming large datasets
Provides one-shot compress() and decompress() functions for in-memory data
Accepts compression levels from 1 (fastest) to 9 (most compression, default)
Handles multi-stream .bz2 files transparently with bz2.open() and BZ2File
Integrates with the with statement as a context manager

Frequently Used Classes and Functions

Object	Type	Description
`bz2.open()`	Function	Opens a bzip2-compressed file in binary or text mode
`bz2.compress()`	Function	Compresses data in a single call and returns the result
`bz2.decompress()`	Function	Decompresses data in a single call and returns the result
`bz2.BZ2File`	Class	Provides a file-like interface to bzip2-compressed files
`bz2.BZ2Compressor`	Class	Compresses data incrementally in chunks
`bz2.BZ2Decompressor`	Class	Decompresses data incrementally in chunks

Examples

Compresses data and writes it to a .bz2 file:

>>> import bz2

>>> data = b"Hello from Real Python!"
>>> with bz2.open("example.bz2", "wb") as f:
...     f.write(data)
...
23

Reads and decompresses a .bz2 file:

>>> with bz2.open("example.bz2", "rb") as f:
...     f.read()
...
b'Hello from Real Python!'

Compresses a stream incrementally using BZ2Compressor:

>>> compressor = bz2.BZ2Compressor()
>>> chunk1 = compressor.compress(b"first chunk ")
>>> chunk2 = compressor.compress(b"second chunk")
>>> compressed = chunk1 + chunk2 + compressor.flush()

Common Use Cases

The most common tasks for bz2 include:

Compressing log files, datasets, or backups in .bz2 format
Reading bzip2-compressed files downloaded from external sources
Streaming and incrementally compressing large data without loading it all into memory
Reducing storage size when archiving text or scientific data

Real-World Example

Reading a compressed log file line by line to find error entries:

>>> import bz2
>>> with bz2.open("server.log.bz2", "rt", encoding="utf-8") as log:
...     errors = [line for line in log if "ERROR" in line]
...

Opening the file in text mode ("rt") allows iterating over lines directly, without loading the entire decompressed content into memory first.

Tutorial

Python's zipfile: Manipulate Your ZIP Files Efficiently

In this guided tutorial, you'll learn how to manipulate ZIP files using Python's zipfile module from the standard library. Through hands-on examples, you'll learn how to read, write, compress, and extract files from your ZIP files quickly.

intermediate python stdlib

For additional information on related topics, take a look at the following resources: