{"id":7059,"library":"bz2file","title":"BZ2File","description":"The `bz2file` library provides a file-like object for reading and writing bzip2-compressed files, backporting the `io.BZ2File` interface introduced in Python 3.3. While Python 3.3+ includes `bz2.open()` in its standard library, this standalone package serves as a drop-in replacement or for use with older Python versions (>=2.6, excluding 3.0-3.2). The current version is 0.98. It has an infrequent release cadence, being a stable backport.","status":"maintenance","version":"0.98","language":"en","source_language":"en","source_url":"https://github.com/nvawda/bz2file","tags":["compression","bz2","file","io","backport"],"install":[{"cmd":"pip install bz2file","lang":"bash","label":"Install bz2file"}],"dependencies":[],"imports":[{"note":"The standard library's 'bz2' module exposes file operations via `bz2.open()`, not directly as `bz2.BZ2File`.","wrong":"import bz2.BZ2File","symbol":"BZ2File","correct":"from bz2file import BZ2File"}],"quickstart":{"code":"import os\nfrom bz2file import BZ2File\n\n# Define a temporary file name\nfile_name = 'example.bz2'\ndata_to_write = b'This is some data that will be compressed using bzip2.'\n\n# 1. Write compressed data to a .bz2 file\nprint(f\"Writing to {file_name}...\")\nwith BZ2File(file_name, 'wb') as f:\n    f.write(data_to_write)\nprint(\"Write complete.\")\n\n# 2. Read compressed data from the .bz2 file\nprint(f\"Reading from {file_name}...\")\nwith BZ2File(file_name, 'rb') as f:\n    read_data = f.read()\nprint(f\"Read data: {read_data}\")\n\nassert read_data == data_to_write\nprint(\"Data integrity check passed.\")\n\n# Clean up the temporary file\nos.remove(file_name)\nprint(f\"Cleaned up {file_name}.\")\n","lang":"python","description":"This quickstart demonstrates how to create and read a bzip2-compressed file using `BZ2File` in binary mode. It writes byte data, then reads it back to verify integrity."},"warnings":[{"fix":"Use `import bz2; with bz2.open('file.bz2', 'wb') as f:` for standard library usage.","message":"For new code on Python 3.3 and newer, consider using `bz2.open()` from the standard library's `bz2` module instead of this `bz2file` package. `bz2.open()` provides similar functionality and is built-in, making this external package largely redundant for modern Python versions.","severity":"gotcha","affected_versions":"All versions of bz2file package, for Python 3.3+"},{"fix":"Encode string data to bytes explicitly before writing, e.g., `f.write('my string'.encode('utf-8'))`.","message":"When writing to a `BZ2File` opened in binary mode ('wb', 'ab'), input data must be `bytes` objects. Attempting to write `str` objects will result in a `TypeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For text, use `BZ2File('file.bz2', 'wt', encoding='utf-8')` for writing or `BZ2File('file.bz2', 'rt', encoding='utf-8')` for reading.","message":"The `BZ2File` class, by default, operates in binary mode. If you need to read or write text, you must explicitly specify a text mode (e.g., `'wt'`, `'rt'`) and ideally an `encoding`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Convert the string to bytes before writing: `f.write(\"my data\".encode('utf-8'))`.","cause":"Attempting to write a Python `str` object to a `BZ2File` opened in binary mode ('wb').","error":"TypeError: a bytes-like object is required, not 'str'"},{"fix":"Install the package using pip: `pip install bz2file`.","cause":"The `bz2file` package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'bz2file'"},{"fix":"Ensure the file being opened is a correctly compressed bzip2 file. This error can also occur if the file is corrupted or truncated. Use standard file opening functions for uncompressed files.","cause":"Attempting to open a file that is not a valid bzip2 compressed archive using `BZ2File`.","error":"OSError: Invalid data stream"}]}