unlzw3

Warnings

• gotcha Performance difference compared to CFFI-based or system utilities. `unlzw3` is a pure Python implementation and is significantly slower than `unlzw` (which uses CFFI) or external system utilities like `uncompress` or `gzip` for decompressing .Z files. For high-throughput or large file operations, consider external processes or compiled alternatives.
  Fix: For performance-critical applications, evaluate using `subprocess` to call system utilities (`uncompress`, `gzip`) or consider the `unlzw` library if a C compiler and platform-specific dependencies are acceptable.
• gotcha Input data type and output encoding. The `unlzw` function expects binary data (bytes) as input, typically obtained by reading a .Z file in binary mode (e.g., `Path('file.Z').read_bytes()`). It returns a UTF-8 decoded string, assuming the original compressed content was text.
  Fix: Always provide binary data (bytes) to `unlzw`. If the original content was not UTF-8 encoded text, additional decoding might be required after decompression, or the decoded string might contain mojibake.
• gotcha Confusion with `unlzw` library. While both `unlzw` and `unlzw3` handle .Z files, `unlzw3` is pure Python and cross-platform, whereas `unlzw` relies on CFFI, potentially offering faster performance but with platform-specific build requirements or pre-compiled binaries.
  Fix: Choose `unlzw3` for maximum compatibility and ease of installation across different operating systems without external compilation needs. Opt for `unlzw` if performance is paramount and CFFI dependencies are manageable.

Install

• pip install unlzw3 Install unlzw3

Imports

• unlzw

  from unlzw3 import unlzw

Quickstart

Decompresses a .Z file (Unix compress utility format) into a UTF-8 decoded string. The input to `unlzw` should be bytes, typically read from a .Z file. The quickstart provides a runnable example, noting that for actual functionality, a properly LZW-compressed .Z file is required.

import os
from pathlib import Path
from unlzw3 import unlzw

# Create a dummy .Z file for demonstration (replace with your actual file)
# This is a simplification; real .Z files are generated by 'compress'
# For a true .Z file, you'd use a real compressed file.
# Example: if you have 'data.txt' and run 'compress data.txt', you get 'data.txt.Z'
# For this quickstart, we'll assume 'example.txt.Z' exists.

# Example: decompress a local .Z file
# Assuming 'example.txt.Z' is in the current directory
# In a real scenario, ensure 'example.txt.Z' exists and contains valid LZW compressed data.

# Let's simulate a simple .Z file if it doesn't exist for the example to be runnable.
# NOTE: This compressed data is NOT a real .Z file generated by `compress` utility,
# but it allows the `unlzw` function to run without error for demonstration purposes.
# A real .Z file would contain specific LZW headers and algorithm output.
# For a proper test, you would need a pre-compressed .Z file.
# Here, we'll just demonstrate the function call structure.

compressed_data_path = Path('example.txt.Z')

# To make this runnable without needing an actual `compress` utility, 
# we'll create a placeholder byte array that the `unlzw` function *could* process
# if it were valid LZW data. For a true test, replace this with `compressed_data_path.read_bytes()`
# after creating a valid .Z file.
# For a proper example:
# 1. Create a text file: `echo "Hello, unlzw3!" > original.txt`
# 2. Compress it using system utility: `compress original.txt` (creates `original.txt.Z`)
# 3. Then use `compressed_data = Path('original.txt.Z').read_bytes()`

# For demonstration purposes, creating a dummy file (won't be a valid .Z for real uncompression)
# This part is to make the quickstart self-contained and runnable, 
# but highlights the *type* of data expected by unlzw, not its actual content.
if not compressed_data_path.exists():
    # This is *not* real LZW compressed data, just bytes to make the example runnable.
    # In a real scenario, `compressed_data` would come from `read_bytes()` of a real .Z file.
    dummy_content = b'\x1f\x9d\x90\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00Hello, unlzw3!'
    compressed_data_path.write_bytes(dummy_content)

try:
    compressed_data = compressed_data_path.read_bytes()
    uncompressed_text = unlzw(compressed_data)
    print("Decompressed data:", uncompressed_text)
except Exception as e:
    print(f"Error during decompression: {e}")
    print("Note: For proper decompression, `example.txt.Z` must be a valid LZW-compressed file.")

# Clean up the dummy file
if compressed_data_path.exists():
    os.remove(compressed_data_path)