{"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":"python","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,"search_vec":"'0.2.3':51 '2024':55 'activ':57 'cffi':30 'compat':39 'compress':12,16,59,67 'cross':37 'cross-platform':36 'current':48 'decemb':54 'decompress':7 'faster':20 'file':11,63 'includ':45 'indic':56 'librari':27 'linux':24 'linux-specif':23 'lzw':60 'mainten':58 'modul':8 'offer':35 'often':22 'platform':38 'pure':5,64 'python':6,29,44,65 'releas':52 'run':43 'slower':33 'specif':25 'system':42 'unix':15,66 'unlik':18 'unlzw':26 'unlzw3':1,2,31 'use':13,28 'util':17 'version':49 'window':46 'z':10,62 'z-file':61","created_at":"2026-04-14T01:38:30.110722+00:00","updated_at":"2026-04-16T23:57:25.181126+00:00","problems":[{"fix":"Install the package using pip: `pip install unlzw3`","cause":"The `unlzw3` package is not installed in the current Python environment or there is a typo in the import statement.","error":"ModuleNotFoundError: No module named 'unlzw3'"},{"fix":"Open the file in binary read mode and pass the file object, or read the file content into bytes first:\n```python\n# Option 1: Pass file object\nimport unlzw3\nwith open('file.Z', 'rb') as f:\n    decompressed_data = unlzw3.unlzw(f)\n\n# Option 2: Pass bytes directly\n# with open('file.Z', 'rb') as f:\n#     compressed_bytes = f.read()\n# decompressed_data = unlzw3.unlzw(compressed_bytes)\n```","cause":"The `unlzw3.unlzw()` function expects either a file-like object (e.g., an opened file in binary mode) or a bytes-like object, but a string (likely a filename) was passed directly.","error":"AttributeError: 'str' object has no attribute 'read'"},{"fix":"Ensure the input data is a genuine LZW-compressed `.Z` file. Verify the file's integrity and type before attempting decompression.","cause":"The input file or bytes provided to `unlzw3.unlzw()` is not a valid `.Z` (LZW compressed) file or stream, or it is corrupted at the header.","error":"unlzw3.LZWError: Bad magic number"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.2.3","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/unlzw3/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}