{"id":5546,"library":"unlzw3","title":"unlzw3","description":"unlzw3 is a pure Python decompression module for .Z files compressed using the Unix compress utility. Unlike the faster, but often Linux-specific, `unlzw` library using Python CFFI, unlzw3 is slower but offers cross-platform compatibility on any system running Python, including Windows. The current version is 0.2.3, released in December 2024, indicating active maintenance.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/scivision/unlzw3","tags":["compression","lzw","z-file","pure python","unix compress"],"install":[{"cmd":"pip install unlzw3","lang":"bash","label":"Install unlzw3"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"Python","optional":false}],"imports":[{"symbol":"unlzw","correct":"from unlzw3 import unlzw"}],"quickstart":{"code":"import os\nfrom pathlib import Path\nfrom unlzw3 import unlzw\n\n# Create a dummy .Z file for demonstration (replace with your actual file)\n# This is a simplification; real .Z files are generated by 'compress'\n# For a true .Z file, you'd use a real compressed file.\n# Example: if you have 'data.txt' and run 'compress data.txt', you get 'data.txt.Z'\n# For this quickstart, we'll assume 'example.txt.Z' exists.\n\n# Example: decompress a local .Z file\n# Assuming 'example.txt.Z' is in the current directory\n# In a real scenario, ensure 'example.txt.Z' exists and contains valid LZW compressed data.\n\n# Let's simulate a simple .Z file if it doesn't exist for the example to be runnable.\n# NOTE: This compressed data is NOT a real .Z file generated by `compress` utility,\n# but it allows the `unlzw` function to run without error for demonstration purposes.\n# A real .Z file would contain specific LZW headers and algorithm output.\n# For a proper test, you would need a pre-compressed .Z file.\n# Here, we'll just demonstrate the function call structure.\n\ncompressed_data_path = Path('example.txt.Z')\n\n# To make this runnable without needing an actual `compress` utility, \n# we'll create a placeholder byte array that the `unlzw` function *could* process\n# if it were valid LZW data. For a true test, replace this with `compressed_data_path.read_bytes()`\n# after creating a valid .Z file.\n# For a proper example:\n# 1. Create a text file: `echo \"Hello, unlzw3!\" > original.txt`\n# 2. Compress it using system utility: `compress original.txt` (creates `original.txt.Z`)\n# 3. Then use `compressed_data = Path('original.txt.Z').read_bytes()`\n\n# For demonstration purposes, creating a dummy file (won't be a valid .Z for real uncompression)\n# This part is to make the quickstart self-contained and runnable, \n# but highlights the *type* of data expected by unlzw, not its actual content.\nif not compressed_data_path.exists():\n    # This is *not* real LZW compressed data, just bytes to make the example runnable.\n    # In a real scenario, `compressed_data` would come from `read_bytes()` of a real .Z file.\n    dummy_content = b'\\x1f\\x9d\\x90\\x01\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00Hello, unlzw3!'\n    compressed_data_path.write_bytes(dummy_content)\n\ntry:\n    compressed_data = compressed_data_path.read_bytes()\n    uncompressed_text = unlzw(compressed_data)\n    print(\"Decompressed data:\", uncompressed_text)\nexcept Exception as e:\n    print(f\"Error during decompression: {e}\")\n    print(\"Note: For proper decompression, `example.txt.Z` must be a valid LZW-compressed file.\")\n\n# Clean up the dummy file\nif compressed_data_path.exists():\n    os.remove(compressed_data_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}