Install & Compatibility
Where this runs
tested against v2.1.1b1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
24MB installed
● package 24MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
RSCodec
✓ from reedsolo import RSCodec
Standard import for the pure-Python implementation.
ReedSolomonError
✓ from reedsolo import ReedSolomonError
Exception class for Reed-Solomon related errors.
RSCodec
✓ from creedsolo import RSCodec
✗ from reedsolo import creedsolo
Used when the optional Cython/C extension is successfully compiled and available. The module name changes from 'reedsolo' to 'creedsolo'.
This quickstart demonstrates how to encode a message using a specified number of ECC symbols and then decode it after introducing simulated errors. The `RSCodec` class handles the core encoding and decoding operations. The output type (bytearray or bytes) is matched to the input type.
from reedsolo import RSCodec, ReedSolomonError
# Initialize RSCodec with the number of error correction (ECC) symbols
# 10 ECC symbols allow correction of up to 5 byte-level errors (nsym/2)
rsc = RSCodec(10)
original_message = b'hello world'
print(f"Original: {original_message}")
# Encode the message
encoded_message = rsc.encode(original_message)
print(f"Encoded: {encoded_message}")
# Simulate some errors (e.g., change 'o' to 'X' in 'world')
tampered_message = bytearray(encoded_message)
tampered_message[4] = ord(b'X') # 'o' in 'hello'
tampered_message[8] = ord(b'X') # 'o' in 'world'
tampered_message[12] = ord(b'X') # ECC part
print(f"Tampered: {tampered_message}")
# Decode and correct errors
try:
# decode returns (decoded_message, corrected_ecc_symbols, errata_positions)
decoded_message, _, _ = rsc.decode(tampered_message)
print(f"Decoded: {decoded_message}")
if original_message == decoded_message:
print("Decoding successful, message recovered.")
else:
print("Decoding failed or original message not fully recovered.")
except ReedSolomonError as e:
print(f"Decoding failed: {e}")
Debug
Known issues
breakingThe 2.x beta branch (e.g., v2.1.1b1) introduces significant breaking changes. It requires Cython >= 3.0.0b2 for its speed-optimized C extension and enforces stricter type usage, primarily expecting `bytearray` or `cpython array` objects for data, whereas v1.x was more flexible with list objects.fixFor new projects, carefully review the 2.x migration guide on PyPI or GitHub. For existing v1.x projects, consider staying on the 1.x stable branch or refactor data handling to use `bytearray` consistently and update Cython if using the C extension. If using `cimport creedsolo` with Cython, the path changes to `cimport creedsolo.creedsolo`.
affects: 2.x.x (beta releases)
gotchaBy default, `reedsolo` (v1.x) installs only the pure-Python implementation. To utilize the faster Cython/C extension, you must explicitly request its compilation during installation, requiring Cython and a C++ compiler.fixInstall with `pip install --upgrade reedsolo --install-option="--cythonize" --verbose` (for older pip) or `pip install --config-setting="--build-option=--cythonize" reedsolo` (for pip 23.1+). This will attempt to build `creedsolo.pyx` if Cython and a C compiler are available.
affects: 1.7.0 and earlier 1.x, some 2.x pre-releases
gotchaThe default Galois field GF(2^8) used by reedsolo means that the maximum total message length (data + ECC symbols) is 255 bytes. For messages longer than this, you must implement chunking to break the data into smaller, manageable blocks for encoding and decoding.fixManually split your longer data into chunks that fit within the (255 - nsym) data bytes limit, encode each chunk separately, and then reassemble/decode them individually.
affects: All versions
gotchaIf the number of errors or erasures exceeds the Reed-Solomon code's correction capability (Singleton bound), the `check()` method or even the decoder might return a mathematically valid but still incorrect/tampered message, rather than raising an error. This is a characteristic of Reed-Solomon codes.fixFor critical applications requiring high integrity, consider using additional error detection mechanisms like hashing functions (e.g., SHA256) in parallel with Reed-Solomon. Use Reed-Solomon for repair, and the hash for a more robust integrity check.
affects: All versions
Upgrade
Version history
1.7.0latest on PyPI · released Jan 17, 2023
Audit
Dependencies
CythonoptionalRequired for compiling the optional C extension for significant speedups. Not installed by default in 1.x unless explicitly requested.