{"id":9380,"library":"types-zstd","title":"Typing Stubs for zstd","description":"The `types-zstd` library provides static type annotations for the `python-zstandard` compression library, enabling type checkers like MyPy to validate the correct usage of `zstd` in Python projects. It is part of the `typeshed` project, which regularly updates stubs to reflect changes in popular Python libraries and new Python versions. The current version is 1.5.7.3.20260408.","status":"active","version":"1.5.7.3.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","zstd","compression","typeshed","mypy"],"install":[{"cmd":"pip install types-zstd","lang":"bash","label":"Install types-zstd"}],"dependencies":[{"reason":"Provides the actual zstd compression/decompression functionality that these stubs type-check. `types-zstd` is only for type hints, not runtime functionality.","package":"python-zstandard","optional":false}],"imports":[{"note":"`types-zstd` provides type stubs for the `zstd` module (from `python-zstandard`), it is not imported directly at runtime.","wrong":"import types_zstd","symbol":"zstd","correct":"import zstd"},{"symbol":"compress","correct":"from zstd import compress"},{"symbol":"ZstdCompressor","correct":"from zstd import ZstdCompressor"}],"quickstart":{"code":"import zstd\nfrom typing import Optional\n\n# Ensure python-zstandard is installed: pip install python-zstandard\n\ndef compress_data(data: bytes, level: Optional[int] = None) -> bytes:\n    \"\"\"Compresses bytes using zstd.\"\"\"\n    if level is not None:\n        return zstd.compress(data, level)\n    return zstd.compress(data)\n\ndef decompress_data(compressed_data: bytes) -> bytes:\n    \"\"\"Decompresses bytes using zstd.\"\"\"\n    return zstd.decompress(compressed_data)\n\nif __name__ == '__main__':\n    original_data = b\"This is some data to be compressed by zstd! \" * 100\n    \n    # Use type-checked functions\n    compressed = compress_data(original_data, level=3)\n    decompressed = decompress_data(compressed)\n\n    print(f\"Original size: {len(original_data)} bytes\")\n    print(f\"Compressed size: {len(compressed)} bytes\")\n    print(f\"Decompressed matches original: {original_data == decompressed}\")\n\n    # Example of using the streaming API (also type-checked)\n    compressor = zstd.ZstdCompressor(level=1)\n    decompressor = zstd.ZstdDecompressor()\n\n    with compressor.stream_writer() as writer:\n        writer.write(b\"Hello \")\n        writer.write(b\"World!\")\n        compressed_stream = writer.read()\n    \n    with decompressor.stream_reader(compressed_stream) as reader:\n        decompressed_stream = reader.read()\n    \n    print(f\"Stream compression works: {decompressed_stream == b'Hello World!'}\")","lang":"python","description":"This quickstart demonstrates how to use the `zstd` library (from `python-zstandard`) with type hints. Installing `types-zstd` allows type checkers like MyPy to validate the arguments and return types of these `zstd` calls, catching potential errors before runtime. Remember to install `python-zstandard` for the runtime functionality."},"warnings":[{"fix":"Ensure you run `pip install python-zstandard` in addition to `pip install types-zstd`.","message":"`types-zstd` only provides type hints; it does not install the actual `zstd` compression library. For runtime functionality, you must install `python-zstandard` separately.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install and configure a type checker (e.g., `pip install mypy`) and run it (e.g., `mypy your_script.py`) on your project.","message":"To benefit from `types-zstd`, you need a static type checker (e.g., MyPy) configured to analyze your Python code. Without a type checker, the stubs have no effect.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Keep `types-zstd` and `python-zstandard` versions in sync, or pin specific versions that are known to be compatible. Review `python-zstandard` release notes for breaking changes and adapt your code accordingly.","message":"If the underlying `python-zstandard` library introduces significant API changes, `types-zstd` will eventually be updated to reflect these changes. This might cause type errors in your existing code if it relies on an older `zstd` API but you've updated `types-zstd`.","severity":"breaking","affected_versions":"Dependent on `python-zstandard` API changes"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the runtime library: `pip install python-zstandard`","cause":"The `python-zstandard` runtime library, which provides the `zstd` module, is not installed. `types-zstd` only provides type hints.","error":"ModuleNotFoundError: No module named 'zstd'"},{"fix":"Verify that `python-zstandard` is installed and its version is compatible with `types-zstd`. Ensure MyPy is running correctly and has access to the installed stubs (e.g., by running in the same virtual environment).","cause":"This MyPy error indicates that the type checker cannot find the `compress` function on the `zstd` module. This could mean either `python-zstandard` is too old/new for the stubs, or MyPy isn't properly picking up the `types-zstd` stubs.","error":"error: Library \"zstd\" has no attribute \"compress\"  [attr-defined]"},{"fix":"Correct the type of the argument being passed to match the expected type. For example, pass an `int` for the compression `level` instead of a `str`.","cause":"This is a typical type checker error, indicating that you're passing an argument of the wrong type (e.g., a string) to a function that expects a different type (e.g., an integer) according to `types-zstd`.","error":"error: Argument \"level\" to \"compress\" has incompatible type \"str\"; expected \"int\"  [arg-type]"}]}