correction 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (40) hide show
  1. correction-0.2.0/LICENSE +26 -0
  2. correction-0.2.0/MANIFEST.in +2 -0
  3. correction-0.2.0/PKG-INFO +229 -0
  4. correction-0.2.0/README.rst +191 -0
  5. correction-0.2.0/correct.c +621 -0
  6. correction-0.2.0/correction.egg-info/PKG-INFO +229 -0
  7. correction-0.2.0/correction.egg-info/SOURCES.txt +38 -0
  8. correction-0.2.0/correction.egg-info/dependency_links.txt +1 -0
  9. correction-0.2.0/correction.egg-info/requires.txt +1 -0
  10. correction-0.2.0/correction.egg-info/top_level.txt +2 -0
  11. correction-0.2.0/libcorrect/LICENSE +12 -0
  12. correction-0.2.0/libcorrect/include/correct/convolutional/bit.h +44 -0
  13. correction-0.2.0/libcorrect/include/correct/convolutional/convolutional.h +40 -0
  14. correction-0.2.0/libcorrect/include/correct/convolutional/error_buffer.h +15 -0
  15. correction-0.2.0/libcorrect/include/correct/convolutional/history_buffer.h +59 -0
  16. correction-0.2.0/libcorrect/include/correct/convolutional/lookup.h +27 -0
  17. correction-0.2.0/libcorrect/include/correct/convolutional/metric.h +20 -0
  18. correction-0.2.0/libcorrect/include/correct/convolutional.h +28 -0
  19. correction-0.2.0/libcorrect/include/correct/portable.h +20 -0
  20. correction-0.2.0/libcorrect/include/correct/reed-solomon/encode.h +3 -0
  21. correction-0.2.0/libcorrect/include/correct/reed-solomon/field.h +167 -0
  22. correction-0.2.0/libcorrect/include/correct/reed-solomon/polynomial.h +14 -0
  23. correction-0.2.0/libcorrect/include/correct/reed-solomon/reed-solomon.h +3 -0
  24. correction-0.2.0/libcorrect/include/correct/reed-solomon.h +76 -0
  25. correction-0.2.0/libcorrect/include/correct.h +277 -0
  26. correction-0.2.0/libcorrect/src/convolutional/bit.c +232 -0
  27. correction-0.2.0/libcorrect/src/convolutional/convolutional.c +59 -0
  28. correction-0.2.0/libcorrect/src/convolutional/decode.c +321 -0
  29. correction-0.2.0/libcorrect/src/convolutional/encode.c +61 -0
  30. correction-0.2.0/libcorrect/src/convolutional/error_buffer.c +43 -0
  31. correction-0.2.0/libcorrect/src/convolutional/history_buffer.c +158 -0
  32. correction-0.2.0/libcorrect/src/convolutional/lookup.c +74 -0
  33. correction-0.2.0/libcorrect/src/convolutional/metric.c +17 -0
  34. correction-0.2.0/libcorrect/src/reed-solomon/decode.c +508 -0
  35. correction-0.2.0/libcorrect/src/reed-solomon/encode.c +34 -0
  36. correction-0.2.0/libcorrect/src/reed-solomon/polynomial.c +255 -0
  37. correction-0.2.0/libcorrect/src/reed-solomon/reed-solomon.c +187 -0
  38. correction-0.2.0/setup.cfg +4 -0
  39. correction-0.2.0/setup.py +55 -0
  40. correction-0.2.0/test_correct.py +165 -0
@@ -0,0 +1,26 @@
1
+ Copyright (c) 2026, Ilan Schnell
2
+ All rights reserved.
3
+
4
+ Redistribution and use in source and binary forms, with or without
5
+ modification, are permitted provided that the following conditions are met:
6
+
7
+ 1. Redistributions of source code must retain the above copyright notice, this
8
+ list of conditions and the following disclaimer.
9
+ 2. Redistributions in binary form must reproduce the above copyright notice,
10
+ this list of conditions and the following disclaimer in the documentation
11
+ and/or other materials provided with the distribution.
12
+
13
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
14
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
15
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
16
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
17
+ ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
18
+ (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
19
+ LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
20
+ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
21
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
22
+ SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23
+
24
+ The views and conclusions contained in the software and documentation are those
25
+ of the authors and should not be interpreted as representing official policies,
26
+ either expressed or implied, of the (Python) correct project.
@@ -0,0 +1,2 @@
1
+ include LICENSE
2
+ include libcorrect/LICENSE
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.4
2
+ Name: correction
3
+ Version: 0.2.0
4
+ Summary: Forward Error Correction - bindings for libcorrect
5
+ Home-page: https://github.com/ilanschnell/correct
6
+ Author: Ilan Schnell
7
+ Author-email: ilanschnell@gmail.com
8
+ License: BSD
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: C
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Programming Language :: Python :: 3.9
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Programming Language :: Python :: 3.15
21
+ Classifier: Topic :: Utilities
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/x-rst
24
+ License-File: LICENSE
25
+ License-File: libcorrect/LICENSE
26
+ Requires-Dist: bitarray>=3.4
27
+ Dynamic: author
28
+ Dynamic: author-email
29
+ Dynamic: classifier
30
+ Dynamic: description
31
+ Dynamic: description-content-type
32
+ Dynamic: home-page
33
+ Dynamic: license
34
+ Dynamic: license-file
35
+ Dynamic: requires-dist
36
+ Dynamic: requires-python
37
+ Dynamic: summary
38
+
39
+ correct
40
+ =======
41
+
42
+ ``correct`` provides Python bindings for the convolutional and Reed-Solomon
43
+ forward error correction algorithms from `libcorrect`_. Convolutional codes
44
+ use bitarrays for encoded data, while Reed-Solomon codes operate on bytes.
45
+
46
+ The package requires Python 3.9 or later and bitarray 3.4 or later.
47
+
48
+ Installation
49
+ ------------
50
+
51
+ Install the package from PyPI::
52
+
53
+ python -m pip install libcorrect
54
+
55
+ Run the self-tests::
56
+
57
+ python -m test_correct
58
+
59
+
60
+ Convolutional codes
61
+ -------------------
62
+
63
+ A convolutional encoder turns each input bit into several output bits. The
64
+ ``inv_rate`` argument is the number of output bits per input bit: ``2`` gives
65
+ a rate 1/2 code, and ``3`` gives a rate 1/3 code. A lower rate adds more
66
+ redundancy.
67
+
68
+ The ``order`` is the width, in bits, of the encoder's shift register. It
69
+ controls how much preceding input affects each output. Larger orders can
70
+ provide stronger codes, but decoding cost and memory use increase rapidly.
71
+
72
+ The generator ``polynomials`` are bit masks which select the shift-register
73
+ bits XORed to produce each output bit. There must be exactly ``inv_rate``
74
+ polynomials. They are conventionally written in octal. For example::
75
+
76
+ conv = correct.Convolutional(2, 7, (0o161, 0o127))
77
+
78
+ This creates a rate 1/2, order 7 code: each input bit produces two output bits,
79
+ using the generator polynomials ``161`` and ``127`` (octal).
80
+
81
+ The following configurations are defined by libcorrect and exercised by the
82
+ test suite:
83
+
84
+ ====== ===== ==========================
85
+ Rate Order Polynomials (octal)
86
+ ====== ===== ==========================
87
+ 1/2 6 ``(0o73, 0o61)``
88
+ 1/2 7 ``(0o161, 0o127)``
89
+ 1/2 8 ``(0o225, 0o373)``
90
+ 1/2 9 ``(0o767, 0o545)``
91
+ 1/3 6 ``(0o53, 0o75, 0o47)``
92
+ 1/3 7 ``(0o137, 0o153, 0o121)``
93
+ 1/3 8 ``(0o333, 0o257, 0o351)``
94
+ 1/3 9 ``(0o417, 0o627, 0o675)``
95
+ ====== ===== ==========================
96
+
97
+ ``Convolutional.encode(data)``
98
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99
+
100
+ Encode a bytes-like object and return a big-endian ``bitarray.bitarray``. The
101
+ encoder appends ``order + 1`` zero steps to terminate the code. The exact
102
+ encoded length is therefore::
103
+
104
+ inv_rate * (8 * len(data) + order + 1)
105
+
106
+ The result may contain a number of bits which is not divisible by eight;
107
+ bitarray preserves that length without exposing byte-padding details.
108
+
109
+ The following example encodes a message, damages three bits, and recovers the
110
+ original data::
111
+
112
+ >>> import correct
113
+ >>> conv = correct.Convolutional(2, 7, (0o161, 0o127))
114
+ >>> encoded = conv.encode(b"Hello world!")
115
+ >>> encoded.endian
116
+ 'big'
117
+ >>> len(encoded)
118
+ 208
119
+ >>> for i in 97, 123, 198:
120
+ ... encoded.invert(i)
121
+ >>> conv.decode(encoded)
122
+ b'Hello world!'
123
+
124
+ ``encoded`` is a big-endian ``bitarray.bitarray`` and can be stored,
125
+ transmitted, or modified using the normal bitarray operations.
126
+
127
+ ``Convolutional.decode(codeword)``
128
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
+
130
+ Decode a big-endian bitarray produced by a compatible convolutional code and
131
+ return ``bytes``. A little-endian bitarray is rejected because its bit order
132
+ would give the codeword a different meaning.
133
+
134
+ Convolutional decoding cannot reliably detect when corruption exceeds the
135
+ code's ability to recover the original message. Protect the decoded data with
136
+ a checksum or CRC when silent corruption matters.
137
+
138
+ ``Convolutional.decode_soft(values)``
139
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140
+
141
+ Soft decoding accepts one unsigned byte for every encoded bit. Each value
142
+ expresses confidence in the received bit:
143
+
144
+ * ``0`` means a definite zero;
145
+ * ``255`` means a definite one;
146
+ * ``128`` means an unknown or erased bit;
147
+ * intermediate values express intermediate confidence.
148
+
149
+ The argument may be any contiguous bytes-like object with one-byte elements.
150
+ For example, convert a hard codeword to soft symbols and erase one symbol::
151
+
152
+ >>> encoded = conv.encode(b"soft decisions")
153
+ >>> soft = bytearray(255 if bit else 0 for bit in encoded)
154
+ >>> soft[len(soft) // 2] = 128
155
+ >>> conv.decode_soft(soft)
156
+ b'soft decisions'
157
+
158
+
159
+ Reed-Solomon codes
160
+ ------------------
161
+
162
+ ``correct.ReedSolomon(num_roots, primitive_polynomial=0x11d,
163
+ first_root=1, root_gap=1)`` creates a Reed-Solomon code over 8-bit symbols. A
164
+ full encoded block contains at most 255 bytes.
165
+
166
+ ``num_roots`` is the number of parity bytes added to every message and must be
167
+ between 1 and 254. A block can therefore contain at most
168
+ ``255 - num_roots`` message bytes. With no erasure information, up to
169
+ ``num_roots // 2`` corrupted bytes can be corrected.
170
+
171
+ The other constructor arguments define the finite field and generator roots.
172
+ The defaults use the primitive polynomial
173
+ ``x^8 + x^4 + x^3 + x^2 + 1``. Change these advanced parameters only when
174
+ interoperating with a protocol or implementation that specifies different
175
+ values; not every combination produces a useful code.
176
+
177
+ ``ReedSolomon.encode(data)``
178
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
179
+
180
+ Encode a bytes-like object and return ``bytes`` containing the original data
181
+ followed by ``num_roots`` parity bytes. Short messages use virtual leading
182
+ padding, which is not included in the result::
183
+
184
+ >>> rs = correct.ReedSolomon(32)
185
+ >>> encoded = rs.encode(b"Reed-Solomon")
186
+ >>> len(encoded)
187
+ 44
188
+ >>> encoded[:12]
189
+ b'Reed-Solomon'
190
+ >>> rs.decode(encoded)
191
+ b'Reed-Solomon'
192
+
193
+ ``ReedSolomon.decode(encoded, erasures=None)``
194
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195
+
196
+ Decode an encoded bytes-like object and return the original message as
197
+ ``bytes``. The optional ``erasures`` argument is a sequence of byte positions
198
+ known to be unreliable. A known erasure consumes one parity byte of the
199
+ correction capacity, while an error at an unknown position consumes two. In
200
+ general, recovery is possible when::
201
+
202
+ 2 * unknown_errors + erasures <= num_roots
203
+
204
+ For example, mark several corrupted bytes as erasures::
205
+
206
+ >>> encoded = bytearray(rs.encode(b"known erasures"))
207
+ >>> erasures = [0, 4, 8]
208
+ >>> for i in erasures:
209
+ ... encoded[i] ^= 0xff
210
+ >>> rs.decode(encoded, erasures=erasures)
211
+ b'known erasures'
212
+
213
+ As with convolutional decoding, sufficiently severe corruption is not always
214
+ detectable. Use a checksum or CRC when the decoded message must be verified.
215
+
216
+
217
+ Version
218
+ -------
219
+
220
+ The installed version is available as::
221
+
222
+ >>> correct.__version__
223
+ '0.2.0'
224
+
225
+
226
+ The Python binding and the vendored libcorrect sources are distributed under
227
+ BSD licenses. See ``LICENSE`` and ``libcorrect/LICENSE`` for details.
228
+
229
+ .. _libcorrect: https://github.com/quiet/libcorrect
@@ -0,0 +1,191 @@
1
+ correct
2
+ =======
3
+
4
+ ``correct`` provides Python bindings for the convolutional and Reed-Solomon
5
+ forward error correction algorithms from `libcorrect`_. Convolutional codes
6
+ use bitarrays for encoded data, while Reed-Solomon codes operate on bytes.
7
+
8
+ The package requires Python 3.9 or later and bitarray 3.4 or later.
9
+
10
+ Installation
11
+ ------------
12
+
13
+ Install the package from PyPI::
14
+
15
+ python -m pip install libcorrect
16
+
17
+ Run the self-tests::
18
+
19
+ python -m test_correct
20
+
21
+
22
+ Convolutional codes
23
+ -------------------
24
+
25
+ A convolutional encoder turns each input bit into several output bits. The
26
+ ``inv_rate`` argument is the number of output bits per input bit: ``2`` gives
27
+ a rate 1/2 code, and ``3`` gives a rate 1/3 code. A lower rate adds more
28
+ redundancy.
29
+
30
+ The ``order`` is the width, in bits, of the encoder's shift register. It
31
+ controls how much preceding input affects each output. Larger orders can
32
+ provide stronger codes, but decoding cost and memory use increase rapidly.
33
+
34
+ The generator ``polynomials`` are bit masks which select the shift-register
35
+ bits XORed to produce each output bit. There must be exactly ``inv_rate``
36
+ polynomials. They are conventionally written in octal. For example::
37
+
38
+ conv = correct.Convolutional(2, 7, (0o161, 0o127))
39
+
40
+ This creates a rate 1/2, order 7 code: each input bit produces two output bits,
41
+ using the generator polynomials ``161`` and ``127`` (octal).
42
+
43
+ The following configurations are defined by libcorrect and exercised by the
44
+ test suite:
45
+
46
+ ====== ===== ==========================
47
+ Rate Order Polynomials (octal)
48
+ ====== ===== ==========================
49
+ 1/2 6 ``(0o73, 0o61)``
50
+ 1/2 7 ``(0o161, 0o127)``
51
+ 1/2 8 ``(0o225, 0o373)``
52
+ 1/2 9 ``(0o767, 0o545)``
53
+ 1/3 6 ``(0o53, 0o75, 0o47)``
54
+ 1/3 7 ``(0o137, 0o153, 0o121)``
55
+ 1/3 8 ``(0o333, 0o257, 0o351)``
56
+ 1/3 9 ``(0o417, 0o627, 0o675)``
57
+ ====== ===== ==========================
58
+
59
+ ``Convolutional.encode(data)``
60
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
61
+
62
+ Encode a bytes-like object and return a big-endian ``bitarray.bitarray``. The
63
+ encoder appends ``order + 1`` zero steps to terminate the code. The exact
64
+ encoded length is therefore::
65
+
66
+ inv_rate * (8 * len(data) + order + 1)
67
+
68
+ The result may contain a number of bits which is not divisible by eight;
69
+ bitarray preserves that length without exposing byte-padding details.
70
+
71
+ The following example encodes a message, damages three bits, and recovers the
72
+ original data::
73
+
74
+ >>> import correct
75
+ >>> conv = correct.Convolutional(2, 7, (0o161, 0o127))
76
+ >>> encoded = conv.encode(b"Hello world!")
77
+ >>> encoded.endian
78
+ 'big'
79
+ >>> len(encoded)
80
+ 208
81
+ >>> for i in 97, 123, 198:
82
+ ... encoded.invert(i)
83
+ >>> conv.decode(encoded)
84
+ b'Hello world!'
85
+
86
+ ``encoded`` is a big-endian ``bitarray.bitarray`` and can be stored,
87
+ transmitted, or modified using the normal bitarray operations.
88
+
89
+ ``Convolutional.decode(codeword)``
90
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91
+
92
+ Decode a big-endian bitarray produced by a compatible convolutional code and
93
+ return ``bytes``. A little-endian bitarray is rejected because its bit order
94
+ would give the codeword a different meaning.
95
+
96
+ Convolutional decoding cannot reliably detect when corruption exceeds the
97
+ code's ability to recover the original message. Protect the decoded data with
98
+ a checksum or CRC when silent corruption matters.
99
+
100
+ ``Convolutional.decode_soft(values)``
101
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
102
+
103
+ Soft decoding accepts one unsigned byte for every encoded bit. Each value
104
+ expresses confidence in the received bit:
105
+
106
+ * ``0`` means a definite zero;
107
+ * ``255`` means a definite one;
108
+ * ``128`` means an unknown or erased bit;
109
+ * intermediate values express intermediate confidence.
110
+
111
+ The argument may be any contiguous bytes-like object with one-byte elements.
112
+ For example, convert a hard codeword to soft symbols and erase one symbol::
113
+
114
+ >>> encoded = conv.encode(b"soft decisions")
115
+ >>> soft = bytearray(255 if bit else 0 for bit in encoded)
116
+ >>> soft[len(soft) // 2] = 128
117
+ >>> conv.decode_soft(soft)
118
+ b'soft decisions'
119
+
120
+
121
+ Reed-Solomon codes
122
+ ------------------
123
+
124
+ ``correct.ReedSolomon(num_roots, primitive_polynomial=0x11d,
125
+ first_root=1, root_gap=1)`` creates a Reed-Solomon code over 8-bit symbols. A
126
+ full encoded block contains at most 255 bytes.
127
+
128
+ ``num_roots`` is the number of parity bytes added to every message and must be
129
+ between 1 and 254. A block can therefore contain at most
130
+ ``255 - num_roots`` message bytes. With no erasure information, up to
131
+ ``num_roots // 2`` corrupted bytes can be corrected.
132
+
133
+ The other constructor arguments define the finite field and generator roots.
134
+ The defaults use the primitive polynomial
135
+ ``x^8 + x^4 + x^3 + x^2 + 1``. Change these advanced parameters only when
136
+ interoperating with a protocol or implementation that specifies different
137
+ values; not every combination produces a useful code.
138
+
139
+ ``ReedSolomon.encode(data)``
140
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
141
+
142
+ Encode a bytes-like object and return ``bytes`` containing the original data
143
+ followed by ``num_roots`` parity bytes. Short messages use virtual leading
144
+ padding, which is not included in the result::
145
+
146
+ >>> rs = correct.ReedSolomon(32)
147
+ >>> encoded = rs.encode(b"Reed-Solomon")
148
+ >>> len(encoded)
149
+ 44
150
+ >>> encoded[:12]
151
+ b'Reed-Solomon'
152
+ >>> rs.decode(encoded)
153
+ b'Reed-Solomon'
154
+
155
+ ``ReedSolomon.decode(encoded, erasures=None)``
156
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
157
+
158
+ Decode an encoded bytes-like object and return the original message as
159
+ ``bytes``. The optional ``erasures`` argument is a sequence of byte positions
160
+ known to be unreliable. A known erasure consumes one parity byte of the
161
+ correction capacity, while an error at an unknown position consumes two. In
162
+ general, recovery is possible when::
163
+
164
+ 2 * unknown_errors + erasures <= num_roots
165
+
166
+ For example, mark several corrupted bytes as erasures::
167
+
168
+ >>> encoded = bytearray(rs.encode(b"known erasures"))
169
+ >>> erasures = [0, 4, 8]
170
+ >>> for i in erasures:
171
+ ... encoded[i] ^= 0xff
172
+ >>> rs.decode(encoded, erasures=erasures)
173
+ b'known erasures'
174
+
175
+ As with convolutional decoding, sufficiently severe corruption is not always
176
+ detectable. Use a checksum or CRC when the decoded message must be verified.
177
+
178
+
179
+ Version
180
+ -------
181
+
182
+ The installed version is available as::
183
+
184
+ >>> correct.__version__
185
+ '0.2.0'
186
+
187
+
188
+ The Python binding and the vendored libcorrect sources are distributed under
189
+ BSD licenses. See ``LICENSE`` and ``libcorrect/LICENSE`` for details.
190
+
191
+ .. _libcorrect: https://github.com/quiet/libcorrect