lz-string-python

lzstring is a Python 2/3 port of pieroxy’s LZ-String JavaScript compression library, letting Python applications compress and decompress plain-text strings using the exact same algorithm and output formats as the original JS implementation. It exposes a single LZString class with static methods for compressing to and decompressing from Base64, UTF-16, URI-encoded, and raw Uint8Array representations.

The primary use case is interoperability: data compressed in a browser with the original lz-string JS library, for example payloads squeezed into localStorage or URL query strings, can be decompressed on a Python backend, and vice versa, without any format mismatch.

What You Get

• Six encoding variants - compress/decompress to plain string, UTF-16, Base64, URI-encoded-component, and Uint8Array formats
• Byte-for-byte JS compatibility - output matches the original lz-string.js implementation so payloads produced in a browser can be decompressed in Python and vice versa
• Zero-config static API - a single LZString class with static methods, no instantiation or configuration required
• Python 2/3 support - written to run on both Python 2.6+ and Python 3.x via the future backport package

Common Use Cases

• Decoding browser-compressed payloads - a Python backend receives a string that a JS client compressed with lz-string, e.g. from localStorage or a URL parameter, and needs to decompress it losslessly
• Compressing large text for URL parameters - shrinking JSON state or query data with compressToEncodedURIComponent before embedding it in a URL
• Cross-language data interchange - a service written in Python needs to produce or consume compressed strings that a JavaScript frontend or another lz-string-compatible system also reads and writes
• Lightweight string compression without external C dependencies - a pure-Python alternative to zlib-based approaches when byte-for-byte JS compatibility matters more than compression ratio

Under The Hood

Architecture The library is a single-file module, lzstring/__init__.py (446 lines), built around two module-level functions, _compress and _decompress, that implement the core LZ78-style bit-encoding state machine, plus a small Object helper class that simulates JS-style attribute objects (data.val, data.position, data.index) for the decompression loop. A LZString class exposes static methods (compressToBase64, compressToUTF16, compressToEncodedURIComponent, compressToUint8Array, and their decompress counterparts) that are thin adapters over the two core functions, differing only in bit-width and the character-mapping callback passed in. It is a flat, single-purpose module with no dependency injection, no I/O, and no configuration surface — pure in-memory string transformation. Because every public method funnels through the same core functions, a change to the core bit-packing logic would ripple through all six encoding variants at once.

Tech Stack Pure Python, packaged with setuptools via a conventional setup.py, with future>=0.14.0 as its only runtime dependency to back-port Python 3 builtins (range, int, chr) and enable __future__ imports for Python 2/3 compatibility. There is no web framework, ORM, or database involved — it’s a standalone utility library distributed on PyPI. CI is configured via a legacy .travis.yml targeting Python 2.6 through 3.6, with no modern GitHub Actions workflow in the repo.

Code Quality The only test artifact is a root-level test.py script that prints compression/decompression results and compares them against known-good strings generated by the original JS library, functioning more as a manual verification demo than an automated pytest/unittest suite with real assertions. Error handling is minimal: methods return None or an empty string for edge cases like None or empty input rather than raising typed exceptions. There are no type hints, no linter or formatter configuration, and variable naming closely mirrors the original JavaScript source’s context_-prefixed style rather than idiomatic PEP 8 conventions.

What Makes It Unique lzstring is not algorithmically novel — it is a faithful, line-by-line port of pieroxy’s original LZ-String JavaScript compression library, offering the same encoding variants so Python code can produce or consume strings compressed by the JS library. Its value is compatibility and interoperability rather than a new compression technique or improved ratio.