py-lzstring 0.1.0__tar.gz

py_lzstring-0.1.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright 2026 Frank Hoffmann
+
+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.

py_lzstring-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: py-lzstring
+Version: 0.1.0
+Summary: LZ-based string compression - Python port of lz-string@1.5.0 (JavaScript)
+Author-email: "Original Code: Pieroxy pieroxy@pieroxy.net, Port: Frank Hoffmann" <frank.h.dev@protonmail.com>
+License: Copyright 2026 Frank Hoffmann
+        
+        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.
+Project-URL: Homepage, https://github.com/Frank-Hoffmann-Dev/py-lzstring
+Project-URL: Bug Tracker, https://github.com/Frank-Hoffmann-Dev/py-lzstring/issues
+Keywords: compression,lz-string,lzstring,lz78,lzw
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-benchmark>=4; extra == "dev"
+Dynamic: license-file
+
+# py-lzstring
+
+Python port of [lz-string](https://github.com/pieroxy/lz-string) - byte-for-byte compatible with lz-string@1.5.0.
+
+
+## Installation
+```bash
+pip install py-lzstring
+```
+
+No runtime dependencies. Requires Python 3.10+.
+
+
+## Quickstart
+
+```python
+import lzstring
+
+# Compress to base64 (safe for HTTP, JSON, localStorage);
+compressed = lzstring.compress_to_base64("Hello, World!")
+print(compressed)       # 'BIUwNmD2A0AEDqkBOYAmBCIA';
+
+original = lzstring.decompress_from_base64(compressed)
+print(original)     # 'Hello, World!';
+```
+
+
+## Encodings
+
+| Function pair | bits/char | Use case |
+|---|---|---|
+| `compress` / `decompress` | 16 | In-memory; smallest output |
+| `compress_to_utf16` / `decompress_from_utf16` | 15 | localStorage (all browsers) |
+| `compress_to_base64` / `decompress_from_base64` | 6 | HTTP, JSON, data-URLs |
+| `compress_to_encoded_uri_component` / `decompress_from_encoded_uri_component` | 6 | URL query strings |
+| `compress_to_uint8array` / `decompress_from_uint8array` | — | Binary I/O, `bytes` output |
+
+## Interoperability with JavaScript
+ 
+All encodings are bit-exact with lz-string@1.5.0:
+ 
+```js
+// JavaScript
+const LZString = require("lz-string");
+const compressed = LZString.compressToBase64("Hello, World!");
+// "BIUwNmD2A0AEDqkBOYAmBCIA"
+```
+ 
+```python
+# Python
+import lzstring
+lzstring.decompress_from_base64("BIUwNmD2A0AEDqkBOYAmBCIA")
+# "Hello, World!"
+```
+ 
+## API reference
+ 
+All compress functions accept `str | None` and return `str` (or `bytes` for the
+Uint8Array variant).  Passing `None` mirrors the JavaScript null-handling and
+returns `""`.
+ 
+All decompress functions accept `str | None` (or `bytes | None` for Uint8Array)
+and return `str | None`.  An empty string returns `None` (like JS `null`),
+indicating invalid input.
+ 
+```python
+import lzstring
+ 
+# Raw (most compact, arbitrary Unicode output)
+lzstring.compress("...")
+lzstring.decompress("...")
+ 
+# UTF-16 (printable characters only, safe for all localStorage implementations)
+lzstring.compress_to_utf16("...")
+lzstring.decompress_from_utf16("...")
+ 
+# Base64 (standard alphabet with = padding)
+lzstring.compress_to_base64("...")
+lzstring.decompress_from_base64("...")
+ 
+# URI component (URL-safe, no padding)
+lzstring.compress_to_encoded_uri_component("...")
+lzstring.decompress_from_encoded_uri_component("...")
+ 
+# Uint8Array (returns / accepts bytes)
+lzstring.compress_to_uint8array("...")      # → bytes
+lzstring.decompress_from_uint8array(b"...") # → str | None
+```
+
+
+## License
+
+MIT License
+```
+Copyright 2026 Frank Hoffmann
+
+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.
+```
+
+
+## Thanks
+
+Many thanks to all the developers of the libraries used and to the community for creating so many incredibly useful tools.
+
+
+## AI Usage
+
+I used the AI assistant **Anthropic Claude AI - Sonnet 4.6** to create this tool.
+
+As a computer scientist, I have reviewed and approved every single line of code, and I understand the tool’s internal processes and how it works.
+I didn’t just copy and paste the code from the AI.
+Instead, I wrote it by hand, line by line, making changes whenever I deemed it necessary.
+
+Nevertheless, there may still be errors or poor design choices.
+Everyone is free to examine, modify, improve, fork the code or call it AI slop :D

py_lzstring-0.1.0/README.md

@@ -0,0 +1,120 @@
+# py-lzstring
+
+Python port of [lz-string](https://github.com/pieroxy/lz-string) - byte-for-byte compatible with lz-string@1.5.0.
+
+
+## Installation
+```bash
+pip install py-lzstring
+```
+
+No runtime dependencies. Requires Python 3.10+.
+
+
+## Quickstart
+
+```python
+import lzstring
+
+# Compress to base64 (safe for HTTP, JSON, localStorage);
+compressed = lzstring.compress_to_base64("Hello, World!")
+print(compressed)       # 'BIUwNmD2A0AEDqkBOYAmBCIA';
+
+original = lzstring.decompress_from_base64(compressed)
+print(original)     # 'Hello, World!';
+```
+
+
+## Encodings
+
+| Function pair | bits/char | Use case |
+|---|---|---|
+| `compress` / `decompress` | 16 | In-memory; smallest output |
+| `compress_to_utf16` / `decompress_from_utf16` | 15 | localStorage (all browsers) |
+| `compress_to_base64` / `decompress_from_base64` | 6 | HTTP, JSON, data-URLs |
+| `compress_to_encoded_uri_component` / `decompress_from_encoded_uri_component` | 6 | URL query strings |
+| `compress_to_uint8array` / `decompress_from_uint8array` | — | Binary I/O, `bytes` output |
+
+## Interoperability with JavaScript
+ 
+All encodings are bit-exact with lz-string@1.5.0:
+ 
+```js
+// JavaScript
+const LZString = require("lz-string");
+const compressed = LZString.compressToBase64("Hello, World!");
+// "BIUwNmD2A0AEDqkBOYAmBCIA"
+```
+ 
+```python
+# Python
+import lzstring
+lzstring.decompress_from_base64("BIUwNmD2A0AEDqkBOYAmBCIA")
+# "Hello, World!"
+```
+ 
+## API reference
+ 
+All compress functions accept `str | None` and return `str` (or `bytes` for the
+Uint8Array variant).  Passing `None` mirrors the JavaScript null-handling and
+returns `""`.
+ 
+All decompress functions accept `str | None` (or `bytes | None` for Uint8Array)
+and return `str | None`.  An empty string returns `None` (like JS `null`),
+indicating invalid input.
+ 
+```python
+import lzstring
+ 
+# Raw (most compact, arbitrary Unicode output)
+lzstring.compress("...")
+lzstring.decompress("...")
+ 
+# UTF-16 (printable characters only, safe for all localStorage implementations)
+lzstring.compress_to_utf16("...")
+lzstring.decompress_from_utf16("...")
+ 
+# Base64 (standard alphabet with = padding)
+lzstring.compress_to_base64("...")
+lzstring.decompress_from_base64("...")
+ 
+# URI component (URL-safe, no padding)
+lzstring.compress_to_encoded_uri_component("...")
+lzstring.decompress_from_encoded_uri_component("...")
+ 
+# Uint8Array (returns / accepts bytes)
+lzstring.compress_to_uint8array("...")      # → bytes
+lzstring.decompress_from_uint8array(b"...") # → str | None
+```
+
+
+## License
+
+MIT License
+```
+Copyright 2026 Frank Hoffmann
+
+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.
+```
+
+
+## Thanks
+
+Many thanks to all the developers of the libraries used and to the community for creating so many incredibly useful tools.
+
+
+## AI Usage
+
+I used the AI assistant **Anthropic Claude AI - Sonnet 4.6** to create this tool.
+
+As a computer scientist, I have reviewed and approved every single line of code, and I understand the tool’s internal processes and how it works.
+I didn’t just copy and paste the code from the AI.
+Instead, I wrote it by hand, line by line, making changes whenever I deemed it necessary.
+
+Nevertheless, there may still be errors or poor design choices.
+Everyone is free to examine, modify, improve, fork the code or call it AI slop :D

py_lzstring-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "py-lzstring"
+version = "0.1.0"
+description = "LZ-based string compression - Python port of lz-string@1.5.0 (JavaScript)"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Original Code: Pieroxy pieroxy@pieroxy.net, Port: Frank Hoffmann", email = "frank.h.dev@protonmail.com" }
+]
+keywords = ["compression", "lz-string", "lzstring", "lz78", "lzw"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Archiving :: Compression",
+    "Typing :: Typed"
+]
+
+dependencies = []       # Pure stdlib - no runtime dependencies;
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-benchmark>=4"
+]
+
+[project.scripts]
+lz_string = "lz_string.main:main"
+
+[project.urls]
+Homepage = "https://github.com/Frank-Hoffmann-Dev/py-lzstring"
+"Bug Tracker" = "https://github.com/Frank-Hoffmann-Dev/py-lzstring/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.ruff]
+line-length = 99
+target-version = "py310"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src"]

py_lzstring-0.1.0/setup.cfg

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

py_lzstring-0.1.0/src/lzstring/__init__.py

@@ -0,0 +1,47 @@
+"""
+py-lzstring - Python port of lz-string (https://github.com/pieroxy/lz-string).
+
+LZ-based string compression compatible with the JavaScript library v1.5.0.
+Five encoding variants are available for different transport or storage needs.
+
+Quick Start:
+    >>> import lzstring
+    >>> compressed = lzstring.compress_to_base64("Hello, World!")
+    >>> lzstring.decompress_from_base64(compressed)
+    'Hello, World!'
+
+All functions accept 'str | None' and return 'str | None' or 'bytes'.
+Passing 'None' mirror the JavaScript library's null-handling behaviour (compress and decompress functions return '""').
+
+
+Encoding Overview:
+
+Function pair                                                               bits/char  Best suited for
+--------------------------------------------------------------------------- ---------  -------------------------
+compress / decompress                                                       16         In-memory; smallest output
+compress_to_utf16 / decompress_from_utf16                                   15         localStorage (all browsers)
+compress_to_base64 / decompress_from_base64                                  6         HTTP, JSON, data-URLs
+compress_to_encoded_uri_component / decompress_from_encoded_uri_component    6         URL query strings
+compress_to_uint8array / decompress_from_uint8array                          8         (bytes) Binary I/O, Node-style
+
+Compability:
+All functions are byte-for-byte compatible with lz-string@1.5.0 and verified against its JavaScript test suits.
+"""
+from lzstring._encodings import (
+    compress, decompress,
+    compress_to_utf16, decompress_from_utf16,
+    compress_to_base64, decompress_from_base64,
+    compress_to_encoded_uri_component, decompress_from_encoded_uri_component,
+    compress_to_uint8array, decompress_from_uint8array
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "compress", "decompress",
+    "compress_to_utf16", "decompress_from_utf16",
+    "compress_to_base64", "decompress_from_base64",
+    "compress_to_encoded_uri_component", "decompress_from_encoded_uri_component",
+    "compress_to_uint8array", "decompress_from_uint8array"
+]

py_lzstring-0.1.0/src/lzstring/_bitstream.py

@@ -0,0 +1,196 @@
+"""
+Bit-level I/O primitives for the LZString compression algorithm.
+
+The LZString format packs variable-width token codes (starting at 2 bits, growing as the directory expands) into a stream of fixed-width 'characters'.
+Each output character holds exactly 'bits_per_char' bits, where bits_per_char is determined by the encoding:
+
+    - Raw / UTF-16      -> 15 bits per character
+    - Base64 / URI      ->  6 bits per character
+    - Uint8Array        ->  8 bits per character (handled at a higher layer)
+
+Bit order within every character is LSB-first: the first token bit lands in bit-0 of the accumulator, the next in bit-1, and so on.
+Once the accumulator is full (position reaches bits_per_char) it's integer value is handed to a caller-supplied 'emit(value: int) -> None' callback, then it resets to 0.
+
+This LSB-first, fixed-width-character packing is the exact scheme used by the original JavaScript implementation and all compatible ports.
+"""
+from __future__ import annotations
+
+from typing import Callable
+
+
+# ----------------------------------------------------------------------------------------------------------------
+# BitWriter;
+# ----------------------------------------------------------------------------------------------------------------
+class BitWriter:
+    """
+    Accumulate individual bits and flush them as fixed-width characters.
+
+    :param bits_per_char:   Number of bits that make up a single output character (e.g. 15 for the raw/UTF-16 encoding, 6 for base64/URI).
+    :param emit:            Callback invoked with the integer value of each completed character.
+                            The caller is responsible for mapping that integer to the appropriate output character (e.g. 'chr(value)') for raw, or a lookup into a base64 alphabet.
+    :return:                None
+
+    Usage:
+    >>> chunks: list[int] = []
+    >>> w = BitWriter(bits_per_char=6, emit=chunks.append)
+    >>> w.write_bits(value=0b10110, n_bits=5)
+    >>> w.flush()
+    """
+    __slots__ = ("_bits_per_char", "_emit", "_val", "_position")
+
+    def __init__(self, bits_per_char: int, emit: Callable[[int], None]) -> None:
+        if bits_per_char < 1:
+            raise ValueError(f"bits_per_char must be >= 1, got {bits_per_char}")
+
+        self._bits_per_char = bits_per_char
+        self._emit = emit
+        self._val: int = 0          # Accumulator;
+        self._position: int = 0     # How many bits are currently in _val;
+
+
+    # ----------------------------------------------------------------------------------------------------------------
+    # Public Interface;
+    # ----------------------------------------------------------------------------------------------------------------
+    def write_bits(self, value: int, n_bits: int) -> None:
+        """
+        Write the lowest *n_bits* bits of *value* into the stream, LSB first.
+
+        Mirrors the inner loop found in every LZString compress implementation:
+            for i in range(n_bits):
+                val = (val << 1) | (value & 1)      # Push LSB into accumulator
+                value >>= 1
+
+        :param value:       The integer whose lowest 'n_bits' bits will be written.
+        :param n_bits:      Number of bits to write (must be >= 0).
+        """
+        for _ in range(n_bits):
+            # Shift the accumulator left and OR in the current LSB;
+            self._val = (self._val << 1) | (value & 1)
+            value >>= 1
+            self._position += 1
+
+            if self._position == self._bits_per_char:
+                self._flush_char()
+
+    
+    def flush(self) -> None:
+        """
+        Flush any remaining bits as a final (zero-padded) character.
+
+        The original JS flush loop checks 'position == bitsPerChar - 1' (not '== bitsPerChar'),
+        so it always emits exactly one character, even when the accumulator is completely empty.
+        This garantees that every compress stream ends with a sentinel character, which the
+        decompressor can safely peek at without an out-of-bounds read.
+
+        This must be called exactly once after all tokens have been written.
+        """
+        while True:
+            self._val <<= 1
+
+            if self._position == self._bits_per_char - 1:
+                self._flush_char()
+                break
+
+            self._position += 1
+
+
+
+    # ----------------------------------------------------------------------------------------------------------------
+    # Internal Helper Functions;
+    # ----------------------------------------------------------------------------------------------------------------
+    def _flush_char(self) -> None:
+        self._emit(self._val)
+        self._val = 0
+        self._position = 0
+
+
+
+# ----------------------------------------------------------------------------------------------------------------
+# BitReader;
+# ----------------------------------------------------------------------------------------------------------------
+class BitReader:
+    """
+    Read individual bits from a sequence of fixed-width characters.
+
+    :param get_char_value:      Callable that accepts a 0-based *index* and returns the integer value of the character at that position in the compressed input.
+                                For the raw encoding this is simply 'ord(compressed[index])'; for base64 it would be a reverse-alphabet lookup.
+    :param reset_value:         The integer whose single set bit marks the *start* position within the first character.
+                                For 'bits_per_char = N' this is '1 << (N - 1)'.
+    :return:                    None
+
+    Examples:
+    - Raw (15 bit):     reset_value = 16384     (0x4000, i.e. 1 << 14)
+    - Base64 (6 bit):   reset_value = 32        (0x20,   i.e. 1 << 5)
+    - UTF-16 (15 bit):  reset_value = 16384
+
+    The decompressor checks the *current bit* by ANDing 'data_val' with 'data_position', then shifts 'data_position' right by one.
+    When 'data_position' reaches 0, the next character is loaded and 'data_position' is reset to 'reset_value'.
+
+    Usage:
+    >>> data = [0b101101]           # One 6-bit char;
+    >>> r = BitReader(lambda i: data[i], reset_value=32)
+    >>> r.read_bits(3)              # Reads lowest 3 bits: 1, 0, 1 -> integer: 5;
+    """
+    __slots__ = ("_get_char_value", "_reset_value", "_val", "_position", "_index")
+
+    def __init__(self, get_char_value: Callable[[int], int], reset_value: int) -> None:
+        if reset_value < 1:
+            raise ValueError(f"reset_value must be >= 1, got {reset_value}")
+        
+        self._get_char_value = get_char_value
+        self._reset_value = reset_value
+
+        # Start with position=0 so the very first read_bits call loads chars[0];
+        self._val: int = 0
+        self._position: int = 0
+        self._index: int = 0        # Next character index to fetch
+
+
+    # ----------------------------------------------------------------------------------------------------------------
+    # Public Interface;
+    # ----------------------------------------------------------------------------------------------------------------
+    def read_bits(self, n_bits: int) -> int:
+        """
+        Read 'n_bits' bits and return them as an integer, LSB first.
+
+        This mirrors the inner loop in the original decompressor:
+            bits = 0
+            power = 1
+            while power != (1 << n_bits):
+                resb = data_val & data_position
+                data_position >>= 1
+                if data_position == 0:
+                    data_position = reset_value
+                    data_val = get_next_value(data_index++)
+                bits |= (1 if resb > 0 else 0) * power
+                power <<= 1
+
+        :param n_bits:      Number of bits to read(must be >= 1).
+        :return:            int - The reconstructed integer value (LSB-first accumulation).
+        """
+        result = 0
+        power = 1
+        max_power = 1 << n_bits
+
+        while power != max_power:
+            # If position == 0, the previous read_bits call exhausted the last character;
+            # Load the next one now, at the start of this bit read;
+            if self._position == 0:
+                self._position = self._reset_value
+                self._val = self._get_char_value(self._index)
+                self._index += 1
+
+            resb = self._val & self._position
+            self._position >>= 1
+            result |= (1 if resb > 0 else 0) * power
+            power <<= 1
+
+        return result
+
+
+    @property
+    def index(self) -> int:
+        """
+        The index of the next character that *would* be fetched.
+        """
+        return self._index