Reed-Solomon Encoder/Decoder

Warnings

• breaking The 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.
  Fix: For 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`.
• gotcha By 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.
  Fix: Install 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.
• gotcha The 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.
  Fix: Manually 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.
• gotcha If 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.
  Fix: For 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.

Install

• pip install reedsolo Stable (1.x branch, pure Python by default)
• pip install reedsolo --install-option="--cythonize" --verbose Stable (1.x branch, with optional Cython extension - older pip)
• pip install --config-setting="--build-option=--cythonize" reedsolo Stable (1.x branch, with optional Cython extension - pip 23.1+)
• pip install reedsolo --pre Beta (2.x branch, may include Cython extension)

Imports

• 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

  Used when the optional Cython/C extension is successfully compiled and available. The module name changes from 'reedsolo' to 'creedsolo'.

Quickstart

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}")