simple-compression 0.1.0__tar.gz

simple_compression-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Malek Yehya (th3f0rk)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

simple_compression-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: simple-compression
+Version: 0.1.0
+Summary: A byte-level compression library implementing RLE and LZ77 with explicit encoding formats, manual pipelines, and automatic algorithm selection.
+Author: Malek Yehya
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# simple-compression
+
+`simple-compression` is a small Python library that implements classic byte-oriented compression algorithms with an explicit and composable API.
+
+The library is designed to operate directly on `bytearray` data and provides both manual and automatic compression pipelines. All encoded outputs are self-describing and can be decoded without external metadata.
+
+Current version: **v0.1.0**
+
+---
+
+## Scope and goals
+
+This project focuses on:
+
+- Correct, deterministic implementations of classic compression algorithms
+- Explicit encoding formats that are easy to inspect and reason about
+- A simple API for chaining multiple compression stages
+- Safe and strict decoding
+
+This library does **not** attempt to compete with production compressors in performance. It is intended for correctness, clarity, and control.
+
+---
+
+## Implemented algorithms
+
+- Run-Length Encoding (RLE)
+- LZ77
+
+Each algorithm has a fully defined binary format and a strict decoder.
+
+---
+
+## Installation
+
+```bash
+pip install simple-compression
+```
+
+---
+
+## Basic Usage
+
+**Both of these features are expected to improve in effectiveness with more testing and tuning as well as the future implementation of a Huffman Algorithm**
+The first usage uses the `auto=True` argument does a quick pass on the data to gather metrics to automatically select the algorithms and their sequence.
+The second usage passes the algorithm name as arguments to manually select algorithms and determine their sequence.
+
+```python
+from simple_compression.compression import SimpleCompression
+
+compress = SimpleCompression()
+
+data = bytearray(b"AAAAAABBBBBCCDSADDDDDSSSCVZCSSSSWEEEFWEWAFZCVAGQWTQL")
+
+encoded = compress.encode(data, auto=True)
+decoded = compress.decode(encoded)
+
+encoded = compress.encode(data, sequence=["RLE", "LZ77"])
+decoded = compress.decode(encoded)
+```
+The decoder reads header tokens embedded at the start of the bitstream to determine which algorithms were applied and in which order.
+This allows for a really robust decoder which when combined with the spec documentation for each algorithm can be helpful in implementing decoders in other languages.
+
+---
+
+## Algorithm Formatting
+
+Detailed binary formats for each algorithm are documented below.
+[RLE Format](documentation/rle_format.md)
+[LZ77 Format](documentation/lz77_format.md)
+
+---
+
+## Road Map
+
+First is implementing a Huffman algorithm to really take advantage of the sequencing ability of this library.
+As features are added the automatic sequencing feature will be continuously tuned to ensure that rle is only enabled when it doesn't infalte the input. 
+As algorithms are added sequencing logic and metrics will develop alongside.
+
+---
+
+## License 
+
+**MIT**

simple_compression-0.1.0/README.md

@@ -0,0 +1,83 @@
+# simple-compression
+
+`simple-compression` is a small Python library that implements classic byte-oriented compression algorithms with an explicit and composable API.
+
+The library is designed to operate directly on `bytearray` data and provides both manual and automatic compression pipelines. All encoded outputs are self-describing and can be decoded without external metadata.
+
+Current version: **v0.1.0**
+
+---
+
+## Scope and goals
+
+This project focuses on:
+
+- Correct, deterministic implementations of classic compression algorithms
+- Explicit encoding formats that are easy to inspect and reason about
+- A simple API for chaining multiple compression stages
+- Safe and strict decoding
+
+This library does **not** attempt to compete with production compressors in performance. It is intended for correctness, clarity, and control.
+
+---
+
+## Implemented algorithms
+
+- Run-Length Encoding (RLE)
+- LZ77
+
+Each algorithm has a fully defined binary format and a strict decoder.
+
+---
+
+## Installation
+
+```bash
+pip install simple-compression
+```
+
+---
+
+## Basic Usage
+
+**Both of these features are expected to improve in effectiveness with more testing and tuning as well as the future implementation of a Huffman Algorithm**
+The first usage uses the `auto=True` argument does a quick pass on the data to gather metrics to automatically select the algorithms and their sequence.
+The second usage passes the algorithm name as arguments to manually select algorithms and determine their sequence.
+
+```python
+from simple_compression.compression import SimpleCompression
+
+compress = SimpleCompression()
+
+data = bytearray(b"AAAAAABBBBBCCDSADDDDDSSSCVZCSSSSWEEEFWEWAFZCVAGQWTQL")
+
+encoded = compress.encode(data, auto=True)
+decoded = compress.decode(encoded)
+
+encoded = compress.encode(data, sequence=["RLE", "LZ77"])
+decoded = compress.decode(encoded)
+```
+The decoder reads header tokens embedded at the start of the bitstream to determine which algorithms were applied and in which order.
+This allows for a really robust decoder which when combined with the spec documentation for each algorithm can be helpful in implementing decoders in other languages.
+
+---
+
+## Algorithm Formatting
+
+Detailed binary formats for each algorithm are documented below.
+[RLE Format](documentation/rle_format.md)
+[LZ77 Format](documentation/lz77_format.md)
+
+---
+
+## Road Map
+
+First is implementing a Huffman algorithm to really take advantage of the sequencing ability of this library.
+As features are added the automatic sequencing feature will be continuously tuned to ensure that rle is only enabled when it doesn't infalte the input. 
+As algorithms are added sequencing logic and metrics will develop alongside.
+
+---
+
+## License 
+
+**MIT**

simple_compression-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "simple-compression"
+version = "0.1.0"
+description = "A byte-level compression library implementing RLE and LZ77 with explicit encoding formats, manual pipelines, and automatic algorithm selection."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+
+authors = [
+    { name = "Malek Yehya" }
+]
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[tool.setuptools]
+package-dir = {"" = "."}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["simple_compression*"]
+

simple_compression-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

simple_compression-0.1.0/simple_compression/__init__.py

@@ -0,0 +1,4 @@
+from .compression import SimpleCompression
+
+__all__ = ["SimpleCompression"]
+

simple_compression-0.1.0/simple_compression/algorithms/__init__.py

@@ -0,0 +1,3 @@
+from .rle import RLE
+from .lz77 import LZ77
+

simple_compression-0.1.0/simple_compression/algorithms/lz77.py

@@ -0,0 +1,123 @@
+class LZ77:
+    def __init__(self, window_size=4096, min_match=3, max_match=255):
+        self.window_size = window_size
+        self.min_match = min_match
+        self.max_match = max_match
+
+    def encode(self, data):
+        output = bytearray()
+        cursor = 0
+
+        index = {}
+
+        while cursor < len(data):
+            if cursor - self.window_size > 0:
+                back_start = cursor - self.window_size
+            else:
+                back_start = 0
+
+            back_end = cursor
+            ahead_start = cursor
+
+            max_ahead = ahead_start + self.max_match
+            if max_ahead < len(data):
+                ahead_end = max_ahead
+            else:
+                ahead_end = len(data)
+
+            best_length = 0
+            best_distance = 0
+
+            if cursor + 2 < len(data):
+                key = (data[cursor], data[cursor + 1], data[cursor + 2])
+                candidates = index.get(key, [])
+            else:
+                key = None
+                candidates = []
+
+            for j in reversed(candidates):
+                if j < back_start:
+                    break
+
+                k = 0
+                while k < min(ahead_end - ahead_start, back_end - j):
+                    if data[j + k] == data[ahead_start + k]:
+                        k += 1
+                    else:
+                        break
+
+                match_length = k
+                match_distance = cursor - j
+
+                if match_length > best_length:
+                    best_length = match_length
+                    best_distance = match_distance
+
+            if best_length >= self.min_match:
+                output.append(0x01)
+
+                high = (best_distance >> 8) & 0xFF
+                low = best_distance & 0xFF
+
+                output.append(high)
+                output.append(low)
+                output.append(best_length)
+
+                step = best_length
+            else:
+                output.append(0x00)
+                output.append(data[cursor])
+                step = 1
+
+            for i in range(step):
+                pos = cursor + i
+                if pos + 2 < len(data):
+                    k = (data[pos], data[pos + 1], data[pos + 2])
+                    lst = index.setdefault(k, [])
+                    lst.append(pos)
+
+                    if len(lst) > 64:
+                        del lst[0]
+
+            cursor += step
+
+        return output
+
+    def decode(self, data):
+        output = bytearray()
+        cursor = 0
+
+        while cursor < len(data):
+            token = data[cursor]
+            cursor += 1
+
+            if token == 0x00:
+                literal = data[cursor]
+                cursor += 1
+                output.append(literal)
+
+            elif token == 0x01:
+                high = data[cursor]
+                cursor += 1
+                low = data[cursor]
+                cursor += 1
+
+                distance = (high << 8) | low
+
+                length = data[cursor]
+                cursor += 1
+
+                copy_start = len(output) - distance
+                copy_index = copy_start
+                copied = 0
+
+                while copied < length:
+                    output.append(output[copy_index])
+                    copy_index += 1
+                    copied += 1
+
+            else:
+                raise ValueError("Invalid LZ77 token")
+
+        return output
+

simple_compression-0.1.0/simple_compression/algorithms/rle.py

@@ -0,0 +1,77 @@
+class RLE:
+    def __init__(self, min_run=3):
+        self.min_run = min_run
+
+    def encode(self, data):
+        if not isinstance(data, bytearray):
+            raise Exception("RLE encode requires bytearray input")
+
+        if len(data) < self.min_run * 2:
+            return data
+
+        output = bytearray()
+
+        current_value = data[0]
+        count = 1
+        cursor = 1
+
+        def emit_run(count, value):
+            while count > 255:
+                output.append(0x01)
+                output.append(255)
+                output.append(value)
+                count -= 255
+            if count >= self.min_run:
+                output.append(0x01)
+                output.append(count)
+                output.append(value)
+            else:
+                for _ in range(count):
+                    output.append(0x00)
+                    output.append(value)
+
+        while cursor < len(data):
+            if data[cursor] == current_value:
+                count += 1
+            else:
+                emit_run(count, current_value)
+                current_value = data[cursor]
+                count = 1
+            cursor += 1
+
+        emit_run(count, current_value)
+
+        return output
+
+    def decode(self, data):
+        if not isinstance(data, bytearray):
+            raise Exception("RLE decode requires bytearray input")
+
+        output = bytearray()
+        cursor = 0
+
+        while cursor < len(data):
+            token = data[cursor]
+            cursor += 1
+
+            if token == 0x00:
+                value = data[cursor]
+                cursor += 1
+                output.append(value)
+
+            elif token == 0x01:
+                count = data[cursor]
+                cursor += 1
+                value = data[cursor]
+                cursor += 1
+
+                repeated = 0
+                while repeated < count:
+                    output.append(value)
+                    repeated += 1
+
+            else:
+                raise Exception("Invalid RLE token")
+
+        return output
+

simple_compression-0.1.0/simple_compression/compression.py

@@ -0,0 +1,93 @@
+from simple_compression.algorithms.rle import RLE
+from simple_compression.algorithms.lz77 import LZ77
+from simple_compression.probe import CompressionProbe
+
+HDR_RLE = 0x01
+HDR_LZ77 = 0x02
+
+MAGIC_0 = 0x53
+MAGIC_1 = 0x43
+
+
+class SimpleCompression:
+    def __init__(self, min_run=3, window_size=4096):
+        self.rle = RLE(min_run=min_run)
+        self.lz77 = LZ77(window_size=window_size)
+        self.probe = CompressionProbe(min_run=min_run)
+
+    def encode(self, data, sequence=None, auto=False):
+        if not isinstance(data, bytearray):
+            raise Exception("encode requires bytearray input")
+
+        if auto:
+            sequence = self._auto_select(data)
+
+        if not sequence:
+            return data
+
+        output = data
+        headers = bytearray()
+
+        for alg in sequence:
+            if alg == "RLE":
+                output = self.rle.encode(output)
+                headers.append(HDR_RLE)
+            elif alg == "LZ77":
+                output = self.lz77.encode(output)
+                headers.append(HDR_LZ77)
+            else:
+                raise Exception("Unknown algorithm")
+
+        framed = bytearray()
+        framed.append(MAGIC_0)
+        framed.append(MAGIC_1)
+        framed.append(len(headers))
+        framed.extend(headers)
+        framed.extend(output)
+        return framed
+
+    def decode(self, data):
+        if not isinstance(data, bytearray):
+            raise Exception("decode requires bytearray input")
+
+        if len(data) < 3:
+            return data
+
+        if data[0] != MAGIC_0 or data[1] != MAGIC_1:
+            return data
+
+        header_count = data[2]
+        cursor = 3
+
+        if len(data) < cursor + header_count:
+            raise Exception("Invalid frame")
+
+        headers = data[cursor:cursor + header_count]
+        cursor += header_count
+
+        output = data[cursor:]
+
+        i = len(headers) - 1
+        while i >= 0:
+            header = headers[i]
+            if header == HDR_RLE:
+                output = self.rle.decode(output)
+            elif header == HDR_LZ77:
+                output = self.lz77.decode(output)
+            else:
+                raise Exception("Invalid header")
+            i -= 1
+
+        return output
+
+    def _auto_select(self, data):
+        metrics = self.probe.analyze(data)
+        sequence = []
+
+        if metrics["use_rle"]:
+            sequence.append("RLE")
+        if metrics["use_lz77"]:
+            sequence.append("LZ77")
+
+        return sequence
+

simple_compression-0.1.0/simple_compression/probe.py

@@ -0,0 +1,35 @@
+class CompressionProbe:
+    def __init__(self, min_run=3):
+        self.min_run = min_run
+
+    def analyze(self, data):
+        if not isinstance(data, bytearray):
+            raise Exception("probe requires bytearray input")
+
+        has_runs = False
+        has_repetition = False
+
+        i = 0
+        while i < len(data) - 1:
+            run_length = 1
+            while i + run_length < len(data) and data[i] == data[i + run_length]:
+                run_length += 1
+
+            if run_length >= self.min_run:
+                has_runs = True
+                break
+
+            i += run_length
+
+        seen = {}
+        for b in data:
+            seen[b] = seen.get(b, 0) + 1
+            if seen[b] > 2:
+                has_repetition = True
+                break
+
+        return {
+            "use_rle": has_runs,
+            "use_lz77": has_repetition
+        }
+

simple_compression-0.1.0/simple_compression.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: simple-compression
+Version: 0.1.0
+Summary: A byte-level compression library implementing RLE and LZ77 with explicit encoding formats, manual pipelines, and automatic algorithm selection.
+Author: Malek Yehya
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# simple-compression
+
+`simple-compression` is a small Python library that implements classic byte-oriented compression algorithms with an explicit and composable API.
+
+The library is designed to operate directly on `bytearray` data and provides both manual and automatic compression pipelines. All encoded outputs are self-describing and can be decoded without external metadata.
+
+Current version: **v0.1.0**
+
+---
+
+## Scope and goals
+
+This project focuses on:
+
+- Correct, deterministic implementations of classic compression algorithms
+- Explicit encoding formats that are easy to inspect and reason about
+- A simple API for chaining multiple compression stages
+- Safe and strict decoding
+
+This library does **not** attempt to compete with production compressors in performance. It is intended for correctness, clarity, and control.
+
+---
+
+## Implemented algorithms
+
+- Run-Length Encoding (RLE)
+- LZ77
+
+Each algorithm has a fully defined binary format and a strict decoder.
+
+---
+
+## Installation
+
+```bash
+pip install simple-compression
+```
+
+---
+
+## Basic Usage
+
+**Both of these features are expected to improve in effectiveness with more testing and tuning as well as the future implementation of a Huffman Algorithm**
+The first usage uses the `auto=True` argument does a quick pass on the data to gather metrics to automatically select the algorithms and their sequence.
+The second usage passes the algorithm name as arguments to manually select algorithms and determine their sequence.
+
+```python
+from simple_compression.compression import SimpleCompression
+
+compress = SimpleCompression()
+
+data = bytearray(b"AAAAAABBBBBCCDSADDDDDSSSCVZCSSSSWEEEFWEWAFZCVAGQWTQL")
+
+encoded = compress.encode(data, auto=True)
+decoded = compress.decode(encoded)
+
+encoded = compress.encode(data, sequence=["RLE", "LZ77"])
+decoded = compress.decode(encoded)
+```
+The decoder reads header tokens embedded at the start of the bitstream to determine which algorithms were applied and in which order.
+This allows for a really robust decoder which when combined with the spec documentation for each algorithm can be helpful in implementing decoders in other languages.
+
+---
+
+## Algorithm Formatting
+
+Detailed binary formats for each algorithm are documented below.
+[RLE Format](documentation/rle_format.md)
+[LZ77 Format](documentation/lz77_format.md)
+
+---
+
+## Road Map
+
+First is implementing a Huffman algorithm to really take advantage of the sequencing ability of this library.
+As features are added the automatic sequencing feature will be continuously tuned to ensure that rle is only enabled when it doesn't infalte the input. 
+As algorithms are added sequencing logic and metrics will develop alongside.
+
+---
+
+## License 
+
+**MIT**

simple_compression-0.1.0/simple_compression.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+LICENSE
+README.md
+pyproject.toml
+./simple_compression/__init__.py
+./simple_compression/compression.py
+./simple_compression/probe.py
+./simple_compression/algorithms/__init__.py
+./simple_compression/algorithms/lz77.py
+./simple_compression/algorithms/rle.py
+simple_compression/__init__.py
+simple_compression/compression.py
+simple_compression/probe.py
+simple_compression.egg-info/PKG-INFO
+simple_compression.egg-info/SOURCES.txt
+simple_compression.egg-info/dependency_links.txt
+simple_compression.egg-info/top_level.txt
+simple_compression/algorithms/__init__.py
+simple_compression/algorithms/lz77.py
+simple_compression/algorithms/rle.py
+tests/test_auto_pipeline.py
+tests/test_lz77.py
+tests/test_manual_pipeline.py
+tests/test_rle.py

simple_compression-0.1.0/simple_compression.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

simple_compression-0.1.0/simple_compression.egg-info/top_level.txt

@@ -0,0 +1 @@
+simple_compression

simple_compression-0.1.0/tests/test_auto_pipeline.py

@@ -0,0 +1,41 @@
+from simple_compression.compression import SimpleCompression
+
+def test_auto_uses_rle():
+    c = SimpleCompression()
+    data = bytearray(b"AAAAAAAB")
+
+    encoded = c.encode(data, auto=True)
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+
+
+def test_auto_uses_lz77():
+    c = SimpleCompression()
+    data = bytearray(b"ABCABCABCABC")
+
+    encoded = c.encode(data, auto=True)
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+
+
+def test_auto_uses_rle_then_lz77():
+    c = SimpleCompression()
+    data = bytearray(b"AAAAABBBBBCCCCCAAAAABBBBB")
+
+    encoded = c.encode(data, auto=True)
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+
+
+def test_auto_negative_tech_passthrough():
+    c = SimpleCompression()
+    data = bytearray(b"\x01\xA9\x3F\x7C\xD2\x88\x10")
+
+    encoded = c.encode(data, auto=True)
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+

simple_compression-0.1.0/tests/test_lz77.py

@@ -0,0 +1,12 @@
+from simple_compression.algorithms.lz77 import LZ77
+
+def test_lz77_round_trip():
+    lz = LZ77()
+    data = bytearray(b"ABCABCABCABCABC")
+
+    encoded = lz.encode(data)
+    decoded = lz.decode(encoded)
+
+    assert decoded == data
+
+

simple_compression-0.1.0/tests/test_manual_pipeline.py

@@ -0,0 +1,31 @@
+from simple_compression.compression import SimpleCompression
+
+def test_manual_rle_only():
+    c = SimpleCompression()
+    data = bytearray(b"AAAAAAAB")
+
+    encoded = c.encode(data, sequence=["RLE"])
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+
+
+def test_manual_lz77_only():
+    c = SimpleCompression()
+    data = bytearray(b"ABCABCABCABC")
+
+    encoded = c.encode(data, sequence=["LZ77"])
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+
+
+def test_manual_rle_then_lz77():
+    c = SimpleCompression()
+    data = bytearray(b"AAAAABBBBBCCCCCAAAAABBBBB")
+
+    encoded = c.encode(data, sequence=["RLE", "LZ77"])
+    decoded = c.decode(encoded)
+
+    assert decoded == data
+

simple_compression-0.1.0/tests/test_rle.py

@@ -0,0 +1,11 @@
+from simple_compression.algorithms.rle import RLE
+
+def test_rle_round_trip():
+    rle = RLE()
+    data = bytearray(b"AAAAAAABBBBBCCCCDDDDDAA")
+
+    encoded = rle.encode(data)
+    decoded = rle.decode(encoded)
+
+    assert decoded == data
+