listcrunch

1.0.1 · active · verified Thu Apr 16

listcrunch is a Python utility library (current version 1.0.1) that provides a simple, human-readable way to compress redundant sequential data within lists into a string format, and to decompress it back. It is a stable, focused library with no active new feature development since its last release in 2020.

Common errors

```
ModuleNotFoundError: No module named 'listcrunch'
```
cause The `listcrunch` library has not been installed in your current Python environment.

fix Run `pip install listcrunch` in your terminal to install the library.
```
TypeError: 'str' object is not callable (when calling crunch or uncrunch)
```
cause This usually happens if you've accidentally defined a local variable named `crunch` or `uncrunch` that overwrites the imported function, or if you tried `import listcrunch` and then called `listcrunch.crunch()` directly, which is incorrect as `crunch` is directly imported from the module.

fix Ensure you are importing the functions correctly using `from listcrunch import crunch, uncrunch` and that no other variables in your scope share these names.
```
ValueError: Invalid compressed string format (when calling uncrunch)
```
cause The string provided to the `uncrunch` function does not conform to the expected `VALUE:START-END;...` format generated by `listcrunch`.

fix Verify that the string passed to `uncrunch` was either originally produced by the `crunch` function or meticulously follows its specified format.

Warnings

gotcha The `crunch` function is designed for lists of hashable items where sequential redundancy is meaningful. Providing non-list iterables or complex, unhashable objects might lead to unexpected behavior or errors (e.g., `TypeError` for unhashable types if the internal mechanism attempts hashing).
Fix: Ensure input to `crunch` is a list of hashable elements where sequential compression makes sense. For lists of unhashable objects, you might need to process them into a hashable representation first.
gotcha While the compressed string format (e.g., `1:0-8;2:9`) is human-readable, directly parsing this string format in your application logic, rather than using the `uncrunch` function, can lead to brittle code. Future (though unlikely) changes to the internal string representation could break such custom parsers.
Fix: Always use the `uncrunch` function for decompression to ensure forward compatibility and robust parsing of the compressed format.
gotcha The library was last updated and tested against Python 3.7.6. While it is `py3-none-any` (Python 3 compatible), very old Python 3 versions (e.g., <3.6) or potential future major Python releases might introduce subtle incompatibilities. No known issues currently exist.
Fix: If encountering unexpected behavior with very old or new Python versions, test within a Python 3.7+ environment. Report any compatibility issues to the library's GitHub repository.

Install

pip install listcrunch Install with pip

Imports

crunch
```
from listcrunch import crunch
```
uncrunch
```
from listcrunch import uncrunch
```

Quickstart

This quickstart demonstrates how to use the `crunch` function to compress a list of sequential, redundant data into a human-readable string format, and then use the `uncrunch` function to restore the original list. The output format `VALUE:START-END;...` indicates that 'VALUE' appears from 'START' index to 'END' index (inclusive) in the original list.

from listcrunch import crunch, uncrunch

# Example data
data = [1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 1]

# Compress the data
compressed_string = crunch(data)
print(f"Original: {data}")
print(f"Compressed: {compressed_string}")
# Expected output: Original: [1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 1]
# Expected output: Compressed: 1:0-8;2:9-10;3:11-13;1:14

# Uncompress the data
decompressed_list = uncrunch(compressed_string)
print(f"Decompressed: {decompressed_list}")
# Expected output: Decompressed: [1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 3, 3, 3, 1]

# Verify round trip
assert data == decompressed_list

view raw JSON →