{"id":1642,"library":"pybcj","title":"pybcj","description":"pybcj is a Python library that provides the BCJ (Branch/Call/Jump) filter, often used as a pre-processing step for data compression algorithms like LZMA (e.g., in xz). It aims to improve compression ratios for executable code by converting relative branch/call/jump targets to absolute addresses. The current version is 1.0.7, and releases are generally infrequent, driven by bug fixes or minor enhancements.","status":"active","version":"1.0.7","language":"en","source_language":"en","source_url":"https://github.com/miurahr/pybcj","tags":["compression","filter","bcj","lzma","executable","binary"],"install":[{"cmd":"pip install pybcj","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"BCJEncoder","correct":"from pybcj import BCJEncoder"},{"symbol":"BCJDecoder","correct":"from pybcj import BCJDecoder"},{"note":"compress_buffer is a top-level function, not a method of BCJEncoder.","wrong":"BCJEncoder().compress_buffer(data)","symbol":"compress_buffer","correct":"from pybcj import compress_buffer"}],"quickstart":{"code":"from pybcj import BCJEncoder, BCJDecoder, compress_buffer, decompress_buffer\nimport io\n\n# Example data (simulating executable code, BCJ works best on actual binaries)\noriginal_data = b\"\\xe8\\x00\\x00\\x00\\x00\\x48\\x83\\xec\\x28\\xe9\\x05\\x00\\x00\\x00\\x90\\x01\\x02\\x03\\x04\\x05\\x06\\x07\\x08\\x09\\x0a\\x0b\\x0c\\x0d\\x0e\\x0f\"\nprint(f\"Original data length: {len(original_data)}\")\n\n# --- Method 1: Using BCJEncoder/Decoder objects with streams ---\n# Encode\nencoder = BCJEncoder()\nencoded_stream = io.BytesIO()\nencoder.compress(original_data, encoded_stream)\nencoded_data_stream = encoded_stream.getvalue()\nprint(f\"Encoded (stream) data length: {len(encoded_data_stream)}\")\n\n# Decode\ndecoder = BCJDecoder()\ndecoded_stream = io.BytesIO()\ndecoder.decompress(encoded_data_stream, decoded_stream)\ndecoded_data_stream = decoded_stream.getvalue()\nprint(f\"Decoded (stream) data length: {len(decoded_data_stream)}\")\n\nassert original_data == decoded_data_stream\nprint(\"Stream method: Original and decoded data match!\")\n\n# --- Method 2: Using top-level compress_buffer/decompress_buffer functions ---\nencoded_data_buffer = compress_buffer(original_data)\nprint(f\"Encoded (buffer) data length: {len(encoded_data_buffer)}\")\n\ndecoded_data_buffer = decompress_buffer(encoded_data_buffer)\nprint(f\"Decoded (buffer) data length: {len(decoded_data_buffer)}\")\n\nassert original_data == decoded_data_buffer\nprint(\"Buffer method: Original and decoded data match!\")","lang":"python","description":"This quickstart demonstrates two ways to use pybcj: with `BCJEncoder`/`BCJDecoder` objects utilizing `io.BytesIO` streams, and with the simpler top-level `compress_buffer`/`decompress_buffer` functions for direct byte array processing."},"warnings":[{"fix":"Ensure your Python environment is 3.10 or newer. Use `python --version` to check.","message":"pybcj requires Python 3.10 or newer. Installing on older Python versions will result in a `Requires-Python` error.","severity":"gotcha","affected_versions":"<1.0.0 (all versions)"},{"fix":"If working with byte strings directly, use `from pybcj import compress_buffer, decompress_buffer`. If using `BCJEncoder`/`BCJDecoder` objects, wrap your byte data in `io.BytesIO(your_bytes_data)`.","message":"The `BCJEncoder.compress()` and `BCJDecoder.decompress()` methods expect stream-like objects (e.g., `io.BytesIO`) as input/output targets. For direct byte array to byte array operations, use the top-level `compress_buffer()` and `decompress_buffer()` functions.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always upgrade to the latest stable version (`pip install --upgrade pybcj`) to ensure access to the most robust and complete API, including the convenient buffer functions.","message":"Versions prior to `1.0.0` (specifically `0.x` releases) might have had different API structures or missing helper functions like `compress_buffer`/`decompress_buffer`. These older versions are no longer actively maintained.","severity":"deprecated","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}