Typing Stubs for zstd

Common errors

• ModuleNotFoundError: No module named 'zstd'

  cause The `python-zstandard` runtime library, which provides the `zstd` module, is not installed. `types-zstd` only provides type hints.
  fix Install the runtime library: `pip install python-zstandard`

• error: Library "zstd" has no attribute "compress"  [attr-defined]

  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.
  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).

• error: Argument "level" to "compress" has incompatible type "str"; expected "int"  [arg-type]

  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`.
  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`.

Warnings

• gotcha `types-zstd` only provides type hints; it does not install the actual `zstd` compression library. For runtime functionality, you must install `python-zstandard` separately.
  Fix: Ensure you run `pip install python-zstandard` in addition to `pip install types-zstd`.
• gotcha 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.
  Fix: Install and configure a type checker (e.g., `pip install mypy`) and run it (e.g., `mypy your_script.py`) on your project.
• breaking 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`.
  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.

Install

• pip install types-zstd Install types-zstd

Imports

• zstd
  wrong:

  import types_zstd

  correct:

  import zstd

  `types-zstd` provides type stubs for the `zstd` module (from `python-zstandard`), it is not imported directly at runtime.
• compress

  from zstd import compress

• ZstdCompressor

  from zstd import ZstdCompressor

Quickstart

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.

import zstd
from typing import Optional

# Ensure python-zstandard is installed: pip install python-zstandard

def compress_data(data: bytes, level: Optional[int] = None) -> bytes:
    """Compresses bytes using zstd."""
    if level is not None:
        return zstd.compress(data, level)
    return zstd.compress(data)

def decompress_data(compressed_data: bytes) -> bytes:
    """Decompresses bytes using zstd."""
    return zstd.decompress(compressed_data)

if __name__ == '__main__':
    original_data = b"This is some data to be compressed by zstd! " * 100
    
    # Use type-checked functions
    compressed = compress_data(original_data, level=3)
    decompressed = decompress_data(compressed)

    print(f"Original size: {len(original_data)} bytes")
    print(f"Compressed size: {len(compressed)} bytes")
    print(f"Decompressed matches original: {original_data == decompressed}")

    # Example of using the streaming API (also type-checked)
    compressor = zstd.ZstdCompressor(level=1)
    decompressor = zstd.ZstdDecompressor()

    with compressor.stream_writer() as writer:
        writer.write(b"Hello ")
        writer.write(b"World!")
        compressed_stream = writer.read()
    
    with decompressor.stream_reader(compressed_stream) as reader:
        decompressed_stream = reader.read()
    
    print(f"Stream compression works: {decompressed_stream == b'Hello World!'}")