### Initialize Zstandard Compression Parameters

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Use these examples to initialize ZstdCompressionParameters with custom settings. The first example shows basic parameter setup, the second demonstrates advanced parameters for high compression, and the third illustrates configuration for Long Distance Matching on repetitive data. A ZstdCompressor can then be created using these parameters.

```python
import zstandard

# Basic custom parameters
params = zstandard.ZstdCompressionParameters(
    window_log=12,
    hash_log=13,
)

# Advanced parameters for high compression
params = zstandard.ZstdCompressionParameters(
    compression_level=22,
    window_log=31,
    strategy=zstandard.STRATEGY_BTULTRA2,
    threads=4,
)

# Long Distance Matching for highly repetitive data
params = zstandard.ZstdCompressionParameters(
    compression_level=15,
    enable_ldm=1,
    ldm_hash_log=16,
    ldm_min_match=64,
)

cctx = zstandard.ZstdCompressor(compression_params=params)
```

--------------------------------

### Install zstandard from PyPI

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Use pip to install the zstandard package. This is the standard method for most users.

```bash
$ pip install zstandard
```

--------------------------------

### Set up Development Environment

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/contributing.md

Create a virtual environment and install development dependencies from ci/requirements.txt.

```bash
python3 -m venv venv

source venv/bin/activate
pip install -r ci/requirements.txt
```

--------------------------------

### Install python-zstandard

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/README.md

Install the library using pip.

```bash
pip install zstandard
```

--------------------------------

### Install zstandard with CFFI support

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Install zstandard with the CFFI backend enabled. This is necessary if your Python distribution does not support compiled extensions using the Python C API, such as PyPy.

```bash
pip install 'zstandard[cffi]'
```

--------------------------------

### Common Parameter Combinations

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Examples of common zstandard compression parameter configurations for different use cases.

```APIDOC
### Common Parameter Combinations

#### Fast Compression
```python
params = zstandard.ZstdCompressionParameters.from_level(1)
```

#### Balanced (Default)
```python
params = zstandard.ZstdCompressionParameters.from_level(3)
```

#### High Compression
```python
params = zstandard.ZstdCompressionParameters.from_level(20)
```

#### Ultra Compression
```python
params = zstandard.ZstdCompressionParameters.from_level(
    22,
    strategy=zstandard.STRATEGY_BTULTRA2,
)
```

#### Streaming with Checksum
```python
params = zstandard.ZstdCompressionParameters.from_level(
    10,
    write_checksum=1,
    write_content_size=1,
)
```

#### Multi-threaded High Compression
```python
params = zstandard.ZstdCompressionParameters.from_level(
    15,
    threads=-1,  # Auto-detect CPU count
    job_size=262144,
)
```
```

--------------------------------

### Install zstandard without CFFI backend directly via setup.py

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Directly invoke setup.py with the --no-cffi-backend option to prevent the compilation of the CFFI-based backend. This is for older packaging tools.

```bash
python3 setup.py --no-cffi-backend
```

--------------------------------

### Install zstandard with legacy format support

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Install zstandard with legacy zstd format support enabled. This is required to handle files compressed with zstd versions prior to 1.0.

```bash
$ pip install zstandard --config-settings='--global-option=--legacy'
```

--------------------------------

### Install zstandard without CFFI backend using config-settings

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Use pip with config-settings to prevent the compilation of the CFFI-based backend. This is an alternative to directly invoking setup.py for newer packaging tools.

```bash
python3 -m pip install zstandard --config-settings='--global-option=--no-cffi-backend'
```

--------------------------------

### Install zstandard without CFFI backend using install-option

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Use pip with install-option to prevent the compilation of the CFFI-based backend. This method is for older packaging tools.

```bash
python3 -m pip install zstandard --install-option --no-cffi-backend
```

--------------------------------

### Get Zstd Frame Header Size

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/zstandard-module.md

The `frame_header_size` function returns the exact byte length of a zstd frame header. This can be used to manually parse or skip headers in a stream of compressed data. It raises `ZstdError` if the provided data does not start with a valid header.

```python
import zstandard

# Example usage would require compressed data
# compressed_data = zstandard.compress(b'some data')
# header_size = zstandard.frame_header_size(compressed_data)
# print(f"Header size: {header_size} bytes")
```

--------------------------------

### Build zstandard against external libzstd using setup.py

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Build the zstandard package by linking against an external, system-provided libzstd library instead of the bundled version. This is done by passing the --system-zstd option to setup.py.

```bash
python3.14 setup.py --system-zstd
```

--------------------------------

### Build C Extension

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/contributing.md

Build the C extension for the Python-Zstandard library using setup.py.

```bash
python setup.py build_ext
```

--------------------------------

### Use Recommended Buffer Sizes for Streaming Compression

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/types.md

Demonstrates how to use recommended input and output buffer sizes for streaming compression operations with zstandard. This helps in optimizing memory usage and performance.

```python
import zstandard

# Use recommended sizes for streaming
read_size = zstandard.COMPRESSION_RECOMMENDED_INPUT_SIZE
write_size = zstandard.COMPRESSION_RECOMMENDED_OUTPUT_SIZE

cctx = zstandard.ZstdCompressor(level=10)
reader = cctx.stream_reader(source, read_size=read_size)
```

--------------------------------

### memory_size

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/decompressor.md

Get the estimated memory usage of the decompressor instance in bytes.

```APIDOC
## Method: `memory_size`

### Description
Get estimated memory usage of this decompressor instance.

### Returns
`int` — Estimated bytes of memory consumed

### Example
```python
dctx = zstandard.ZstdDecompressor()
print(f"Memory usage: {dctx.memory_size()} bytes")
```
```

--------------------------------

### ZstdCompressionDict Properties

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Access properties of a ZstdCompressionDict object to get training parameters.

```APIDOC
## Property: `k`

Get the segment size parameter from training.

**Type:** `int` (read-only)

---

## Property: `d`

Get the distance parameter from training.

**Type:** `int` (read-only)
```

--------------------------------

### Initialize ZstdDecompressor

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/decompressor.md

Instantiate a ZstdDecompressor. Use a pre-trained dictionary or specify a maximum window size if needed.

```python
import zstandard

# Basic decompressor
dctx = zstandard.ZstdDecompressor()

# With pre-trained dictionary
dict_data = zstandard.ZstdCompressionDict(b"...")
dctx = zstandard.ZstdDecompressor(dict_data=dict_data)

# With window size limit
dctx = zstandard.ZstdDecompressor(max_window_size=67108864)  # 64 MB
```

--------------------------------

### Ultra Compression Parameters

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Configure Zstandard for ultra compression using the BTULTRA2 strategy. This offers the highest compression ratio at the cost of speed.

```python
params = zstandard.ZstdCompressionParameters.from_level(
    22,
    strategy=zstandard.STRATEGY_BTULTRA2,
)
```

--------------------------------

### Get Dictionary as Bytes

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Obtain the raw byte representation of the dictionary. This is useful for saving the dictionary to a file or for transmitting it.

```python
dict_obj = zstandard.ZstdCompressionDict(b"...")
dict_bytes = dict_obj.as_bytes()
# Can be written to file and reused later
with open('dictionary.zstd', 'wb') as f:
    f.write(dict_bytes)
```

--------------------------------

### Get Dictionary Size

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Retrieve the size of the dictionary in bytes. This is useful for understanding memory usage or for logging purposes.

```python
dict_obj = zstandard.ZstdCompressionDict(b"dictionary content")
size = len(dict_obj)
print(f"Dictionary size: {size} bytes")
```

--------------------------------

### Check Zstandard Backend Information

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/README.md

Prints the currently active backend implementation and its supported features. Useful for diagnosing performance or compatibility issues.

```python
import zstandard
print(f"Backend: {zstandard.backend}")
print(f"Features: {zstandard.backend_features}")
```

--------------------------------

### Get Zstandard Frame Format

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Access the frame format setting of Zstandard compression parameters. This is a read-only integer property.

```python
params = zstandard.ZstdCompressionParameters.from_level(10)
fmt = params.format
```

--------------------------------

### Build zstandard against external libzstd using pip install-option

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/installing.md

Build the zstandard package by linking against an external, system-provided libzstd library using pip's install-option. This is an alternative to directly invoking setup.py.

```bash
python3.14 -m pip install zstandard --install-option="--system-zstd"
```

--------------------------------

### Get ZstdCompressor Memory Usage

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compressor.md

Call the `memory_size` method on a ZstdCompressor instance to estimate its memory footprint. This is useful for resource monitoring.

```python
cctx = zstandard.ZstdCompressor(level=20)
print(f"Memory usage: {cctx.memory_size()} bytes")
```

--------------------------------

### Get Decompressor Memory Usage

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/decompressor.md

Retrieve the estimated memory footprint of an initialized ZstdDecompressor instance. This is useful for monitoring resource consumption.

```python
dctx = zstandard.ZstdDecompressor()
print(f"Memory usage: {dctx.memory_size()} bytes")
```

--------------------------------

### Initialize ZstdCompressor

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compressor.md

Instantiate a ZstdCompressor with various configuration options. Use default settings for basic compression, higher levels for better ratios, multiple threads for speed, or provide a pre-trained dictionary or custom compression parameters for advanced control.

```python
import zstandard

# Basic compressor with default settings
cctx = zstandard.ZstdCompressor()
```

```python
# Higher compression level
cctx = zstandard.ZstdCompressor(level=22)
```

```python
# Multi-threaded compression
cctx = zstandard.ZstdCompressor(level=10, threads=4)
```

```python
# With pre-trained dictionary
dict_data = zstandard.train_dictionary(...)
cctx = zstandard.ZstdCompressor(dict_data=dict_data)
```

```python
# Custom parameters
params = zstandard.ZstdCompressionParameters.from_level(
    10,
    source_size=1048576,
)
cctx = zstandard.ZstdCompressor(compression_params=params)
```

--------------------------------

### Get Dictionary ID

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Retrieve the numeric ID associated with the dictionary. This ID can be embedded within compressed data for later decompression.

```python
dict_obj = zstandard.ZstdCompressionDict(b"...")
dict_id = dict_obj.dict_id()
print(f"Dictionary ID: {dict_id}")
```

--------------------------------

### Using the open() Function for Files

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/README.md

Read from or write to compressed files transparently using the `zstandard.open()` function. This simplifies file handling for compressed data.

```python
import zstandard

# Read compressed file as if it were uncompressed
with zstandard.open('archive.zst', 'rb') as f:
    data = f.read()

# Write file that is automatically compressed
with zstandard.open('archive.zst', 'wb') as f:
    f.write(data)
```

--------------------------------

### Fast Compression Parameters

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Configure Zstandard for fast compression. Use this when compression speed is the primary concern.

```python
params = zstandard.ZstdCompressionParameters.from_level(1)
```

--------------------------------

### ZstdDecompressionObj.unconsumed_tail

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/low-level-objects.md

Get bytes from input that could not be immediately processed. This property is primarily for compatibility with the zlib interface and is generally less useful than `unused_data`.

```APIDOC
## ZstdDecompressionObj.unconsumed_tail

### Description
Get bytes from input that could not be immediately processed. This property is primarily for compatibility with the zlib interface and is generally less useful than `unused_data`.

### Property
`unconsumed_tail` (bytes) - read-only
```

--------------------------------

### ZstdDecompressionObj.unused_data

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/low-level-objects.md

Get bytes after decompression is complete but were not consumed. This property is useful for identifying any trailing data in the input buffer that is not part of the zstd frame.

```APIDOC
## ZstdDecompressionObj.unused_data

### Description
Get bytes after decompression is complete but were not consumed. This property is useful for identifying any trailing data in the input buffer that is not part of the zstd frame.

### Property
`unused_data` (bytes) - read-only

### Example
```python
obj = dctx.decompressobj()
decompressed = obj.decompress(compressed_with_extra)
remaining = obj.unused_data  # Data after the zstd frame
```
```

--------------------------------

### Initialize ZstdCompressor with Default Settings

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Create a ZstdCompressor instance with default compression settings. This uses compression level 3 and default options for checksums and content size.

```python
import zstandard

# Default: level 3, no dictionary, default checksums
cctx = zstandard.ZstdCompressor()
```

--------------------------------

### Checking for Valid Zstd Frame

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/errors.md

Verify if data starts with the zstandard frame magic number before attempting decompression to prevent format errors.

```python
import zstandard

# Assuming 'data' is your byte string
if data.startswith(zstandard.FRAME_HEADER):
    print("Valid zstd frame")
else:
    print("Not zstd format")
```

--------------------------------

### Balanced Compression Parameters (Default)

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Configure Zstandard for a balanced approach between compression speed and ratio. This is the default configuration.

```python
params = zstandard.ZstdCompressionParameters.from_level(3)
```

--------------------------------

### BufferSegments Class

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

An array-like view of the (offset, length) pairs that describe segments in a `BufferWithSegments`. It allows getting the number of segments and accessing individual segment descriptors.

```APIDOC
## BufferSegments Class

An array of segment descriptors.

### Overview

`BufferSegments` is an array-like view of the (offset, length) pairs that describe segments in a `BufferWithSegments`.

### Methods

#### `__len__`

Get the number of segments in the descriptor array.

**Signature:**
```python
def __len__(self) -> int
```

**Returns:** `int` — Number of segments

---

#### `__getitem__(i)`

Get the i-th descriptor.

**Signature:**
```python
def __getitem__(self, i: int) -> BufferSegment
```

**Returns:** `BufferSegment` — The segment at index i

---
```

--------------------------------

### Programmatically Check Backend and Features

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Check the currently loaded zstandard backend and its supported features. This is useful for verifying the import policy or understanding available functionality.

```python
import zstandard
print(f"Current backend: {zstandard.backend}")
print(f"Backend features: {zstandard.backend_features}")
```

--------------------------------

### Get Total Segment Count

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

Retrieve the total number of segments across all buffers in the collection. This method is used to understand the total number of discrete data chunks.

```python
# If buf1 has 2 segments and buf2 has 3 segments
collection = zstandard.BufferWithSegmentsCollection(buf1, buf2)
print(len(collection))  # 5
```

--------------------------------

### Import Zstandard Module

Source: https://github.com/indygreg/python-zstandard/blob/main/docs/api_usage.md

Import the zstandard module for Zstandard compression and decompression functionalities. This is the primary way to begin using the library.

```python
import zstandard
```

--------------------------------

### Estimate Decompression Context Memory

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/zstandard-module.md

Call `estimate_decompression_context_size` to get an estimate of the memory in bytes required to initialize a Zstandard decompressor instance. This is useful for resource planning before creating a decompressor.

```python
import zstandard

memory_needed = zstandard.estimate_decompression_context_size()
print(f"Memory needed for decompressor: {memory_needed} bytes")
```

--------------------------------

### Initialize BufferWithSegments

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

Demonstrates initializing a BufferWithSegments with raw data and segment descriptors. Use this to create a buffer that references multiple logical items within a single memory region.

```python
import struct
import zstandard

# Create buffer with two 5-byte segments
data = b"helloworld"
segments = struct.pack('<QQ', 0, 5) + struct.pack('<QQ', 5, 5)  # Offsets and lengths
buf = zstandard.BufferWithSegments(data, segments)

seg0 = buf[0].tobytes()  # b"hello"
seg1 = buf[1].tobytes()  # b"world"
```

--------------------------------

### Get Specific Segment by Index

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

Access a specific segment from the collection using its sequential index across all combined buffers. This allows retrieving individual data chunks for processing.

```python
# buf1 has 2 segments, buf2 has 3 segments
collection = zstandard.BufferWithSegmentsCollection(buf1, buf2)

# buf1[0] via collection[0]
# buf1[1] via collection[1]
# buf2[0] via collection[2]
# buf2[1] via collection[3]
# buf2[2] via collection[4]
seg = collection[3]
data = seg.tobytes()
```

--------------------------------

### Initialize ZstdCompressionParameters Directly

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Instantiate `ZstdCompressionParameters` directly to set all available parameters. This provides the most granular control over compression and frame settings.

```python
params = zstandard.ZstdCompressionParameters(
    format: int = 0,
    compression_level: int = 0,
    window_log: int = 0,
    hash_log: int = 0,
    chain_log: int = 0,
    search_log: int = 0,
    min_match: int = 0,
    target_length: int = 0,
    strategy: int = -1,
    write_content_size: int = 1,
    write_checksum: int = 0,
    write_dict_id: int = 0,
    job_size: int = 0,
    overlap_log: int = -1,
    force_max_window: int = 0,
    enable_ldm: int = 0,
    ldm_hash_log: int = 0,
    ldm_min_match: int = 0,
    ldm_bucket_size_log: int = 0,
    ldm_hash_rate_log: int = -1,
    threads: int = 0,
)
```

--------------------------------

### High Compression Parameters

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Configure Zstandard for high compression ratio. Use this when achieving the smallest possible file size is critical.

```python
params = zstandard.ZstdCompressionParameters.from_level(20)
```

--------------------------------

### Streaming Large Files

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Process large files efficiently by streaming data. This example reads from an input file and writes compressed output to another, using a large read size for better performance.

```python
cctx = zstandard.ZstdCompressor(level=10)
with open('input.bin', 'rb') as ifh:
    with open('output.zst', 'wb') as ofh:
        reader = cctx.stream_reader(ifh)
        # Use large read_size for efficiency
        for chunk in iter(lambda: reader.read(1048576), b''):
            ofh.write(chunk)
```

--------------------------------

### File Organization Structure

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/README.md

Overview of the directory structure for the python-zstandard project.

```bash
output/
├── README.md                               (this file)
├── api-reference/
│   ├── zstandard-module.md                 Module exports and functions
│   ├── compressor.md                       ZstdCompressor class
│   ├── decompressor.md                     ZstdDecompressor class
│   ├── compression-parameters.md           ZstdCompressionParameters class
│   ├── compression-dict.md                 ZstdCompressionDict class
│   ├── stream-readers-writers.md           Stream I/O classes
│   ├── low-level-objects.md                Incremental compression objects
│   └── buffer-classes.md                   Memory buffer classes
├── types.md                                Type definitions and constants
├── configuration.md                        Configuration options
└── errors.md                               Error handling and recovery
```

--------------------------------

### BufferSegment Class

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

Represents a logical item within a larger buffer, avoiding object allocation overhead for large numbers of small items. It provides methods to get the segment length and a copy of the segment data.

```APIDOC
## BufferSegment Class

A reference to a portion of a buffer.

### Overview

`BufferSegment` represents a logical item within a larger buffer, avoiding object allocation overhead for large numbers of small items.

### Properties

#### `offset`

Byte offset of segment within its parent buffer.

**Type:** `int` (read-only)

---

### Methods

#### `__len__`

Get the segment length in bytes.

**Signature:**
```python
def __len__(self) -> int
```

**Returns:** `int` — Segment size

---

#### `tobytes()`

Get a copy of segment data as bytes.

**Signature:**
```python
def tobytes(self) -> bytes
```

**Returns:** `bytes` — Copy of segment data

---
```

--------------------------------

### Building Buffers Manually with Segments

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/buffer-classes.md

Demonstrates how to manually construct a BufferWithSegments object by defining data and segment descriptors. This allows for fine-grained control over buffer structure without immediate copying.

```python
import struct
import zstandard

# Prepare three items
items = [b"data1", b"data2", b"data3"]

# Combine into single buffer
data = b"".join(items)

# Create segment descriptors
segments = b""
offset = 0
for item in items:
    segments += struct.pack('<QQ', offset, len(item))
    offset += len(item)

# Create buffer
buf = zstandard.BufferWithSegments(data, segments)

# Access items without copying (until tobytes)
for i in range(len(buf)):
    print(f"Item {i}: {buf[i].tobytes()}")
```

--------------------------------

### Using ZstdCompressionDict with ZstdCompressor

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Demonstrates how to use an initialized ZstdCompressionDict object with a ZstdCompressor to compress data. The dictionary is passed during the compressor's initialization.

```python
import zstandard

# Assume dict_obj is already initialized as shown in previous examples
# dict_obj = zstandard.ZstdCompressionDict(dict_data.as_bytes())

# Use with compressor
cctx = zstandard.ZstdCompressor(dict_data=dict_obj)
compressed = cctx.compress(b"data to compress")
```

--------------------------------

### Get Zstandard Frame Compression Progress

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compressor.md

The `frame_progression` method retrieves the current compression progress, returning a tuple of processed input bytes, processed output bytes, and the total expected input bytes. This is useful for monitoring long compression tasks.

```python
import zstandard

cctx = zstandard.ZstdCompressor(level=10)
obj = cctx.compressobj(size=1000000)
progress_tuple = cctx.frame_progression()
print(f"Processed: {progress_tuple[0]}/{progress_tuple[2]} bytes")
```

--------------------------------

### Initialize ZstdCompressor with a Pre-trained Dictionary

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Instantiate ZstdCompressor with a pre-trained dictionary to improve compression ratios for similar data. The dictionary must be trained beforehand using zstandard.train_dictionary.

```python
# With dictionary
dict_data = zstandard.train_dictionary(8192, samples)
cctx = zstandard.ZstdCompressor(dict_data=dict_data, level=10)
```

--------------------------------

### Get Decompressed Content Size from Zstd Frame

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/zstandard-module.md

Use `frame_content_size` to retrieve the uncompressed size of data from a zstd frame header. This is useful for pre-allocating buffers or verifying data integrity. The function returns `CONTENTSIZE_UNKNOWN` if the size is not stored or `CONTENTSIZE_ERROR` for invalid frames.

```python
import zstandard

compressed = zstandard.compress(b"Hello" * 100)
size = zstandard.frame_content_size(compressed)
print(f"Decompressed size: {size} bytes")
```

--------------------------------

### High Compression Configuration

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Employ level 20 with checksums enabled for strong compression ratios, though it will be slower. Checksums help verify data integrity.

```python
cctx = zstandard.ZstdCompressor(level=20, write_checksum=True)
```

--------------------------------

### Using ZstdCompressionChunker for Chunked Compression

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/low-level-objects.md

This snippet demonstrates how to use ZstdCompressionChunker to compress data in chunks and send them over a network. It shows the typical workflow of iterating through input data, compressing each chunk, and then finishing the compression process. Ensure to call finish() to get the final compressed data.

```python
cctx = zstandard.ZstdCompressor(level=10)
chunker = cctx.chunker(chunk_size=65536)

for input_chunk in data_source:
    for compressed_chunk in chunker.compress(input_chunk):
        send_to_network(compressed_chunk)

# Don't forget to finish
for compressed_chunk in chunker.finish():
    send_to_network(compressed_chunk)
```

--------------------------------

### Create Default ZstdDecompressor

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Instantiate a ZstdDecompressor with default settings. No special imports are needed beyond the zstandard library.

```python
import zstandard

# Default decompressor
dctx = zstandard.ZstdDecompressor()
```

--------------------------------

### Initialize ZstdCompressor with Higher Compression Level

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Create a ZstdCompressor instance configured for higher compression. This increases the compression ratio at the cost of slower compression speed.

```python
# Higher compression
cctx = zstandard.ZstdCompressor(level=20)
```

--------------------------------

### Ultra Compression Configuration

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Achieve maximum compression using level 22 with the BTULTRA2 strategy. This is the slowest option and should be used when storage space is paramount.

```python
params = zstandard.ZstdCompressionParameters.from_level(
    22,
    strategy=zstandard.STRATEGY_BTULTRA2,
)
cctx = zstandard.ZstdCompressor(compression_params=params)
```

--------------------------------

### Train Zstandard Dictionary with Defaults

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Train a Zstandard dictionary using default parameters. Ensure you have representative sample data available.

```python
import zstandard

samples = [document for document in get_json_documents(1000)]

# Train with defaults
dict_obj = zstandard.train_dictionary(
    dict_size=8192,
    samples=samples,
)
```

--------------------------------

### zstandard.open

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/zstandard-module.md

Creates a file object with zstd (de)compression, supporting various modes and optional compression/decompression contexts.

```APIDOC
## zstandard.open

### Description
Create a file object with zstd (de)compression.

### Method
`open(
    filename,
    mode='rb',
    cctx=None,
    dctx=None,
    encoding=None,
    errors=None,
    newline=None,
    closefd=None,
) -> ZstdCompressionReader | ZstdCompressionWriter | io.TextIOWrapper`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **filename** (`str | bytes | os.PathLike | BinaryIO`) - Required - File path or file-like object
- **mode** (`str`) - Optional - File open mode: `'rb'`, `'wb'`, `'ab'`, `'xb'`, or text mode variants. Defaults to `'rb'`.
- **cctx** (`ZstdCompressor`) - Optional - Compressor instance for writing. If `None` and mode is write, defaults to `ZstdCompressor()`.
- **dctx** (`ZstdDecompressor`) - Optional - Decompressor instance for reading. If `None` and mode is read, defaults to `ZstdDecompressor()`.
- **encoding** (`str`) - Optional - Text encoding for text-mode files (e.g., `'utf-8'`).
- **errors** (`str`) - Optional - Text encoding error handling mode (e.g., `'strict'`, `'ignore'`).
- **newline** (`str`) - Optional - Newline character for text-mode files.
- **closefd** (`bool`) - Optional - Whether to close the underlying file when returned object is closed. Only used if a file object is passed. Ignored for file paths. Defaults to `None`.

### Returns
`ZstdCompressionReader | ZstdCompressionWriter | io.TextIOWrapper` depending on mode

### Raises
`ValueError` — If mode is invalid; `TypeError` — If filename is not a valid type

### Example
```python
import zstandard

# Read compressed file
with zstandard.open('archive.zst', 'rb') as f:
    data = f.read()

# Write compressed file
with zstandard.open('archive.zst', 'wb') as f:
    f.write(b'Hello, world!')

# Text mode with encoding
with zstandard.open('text.zst', 'rt', encoding='utf-8') as f:
    text = f.read()
```
```

--------------------------------

### Initialize ZstdCompressor with Custom Compression Parameters

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/configuration.md

Create a ZstdCompressor using a ZstdCompressionParameters object for fine-grained control over compression settings. This overrides individual parameters like level and flags.

```python
# With custom parameters
params = zstandard.ZstdCompressionParameters.from_level(
    10,
    threads=4,
    write_checksum=1,
)
cctx = zstandard.ZstdCompressor(compression_params=params)
```

--------------------------------

### Using ZstdCompressionWriter with Context Manager

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/stream-readers-writers.md

Demonstrates how to use ZstdCompressionWriter as a context manager to automatically handle compression and frame finalization. Ensure the underlying file handle is opened in binary write mode ('wb').

```python
cctx = zstandard.ZstdCompressor(level=10)
with open('output.zst', 'wb') as ofh:
    with cctx.stream_writer(ofh) as writer:
        writer.write(b'chunk 1')
        writer.write(b'chunk 2')
        # Frame is finalized on __exit__
```

--------------------------------

### ZstdCompressionParameters Constructor

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-parameters.md

Initialize compression parameters with explicit values. This constructor allows for fine-grained control over the compression process by setting various parameters related to frame format, compression level, window size, hash tables, search parameters, and more.

```APIDOC
## Constructor: `__init__`

Initialize compression parameters with explicit values.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | `int` | `0` | Frame format: `FORMAT_ZSTD1` (with magic) or `FORMAT_ZSTD1_MAGICLESS`. `0` = default |
| `compression_level` | `int` | `0` | Compression level (0-22). `0` uses default for strategy |
| `window_log` | `int` | `0` | Window log exponent. Controls sliding window size: 2^window_log. Range: `WINDOWLOG_MIN` to `WINDOWLOG_MAX`. `0` = default |
| `hash_log` | `int` | `0` | Hash table log exponent. Range: `HASHLOG_MIN` to `HASHLOG_MAX`. `0` = default |
| `chain_log` | `int` | `0` | Chain log exponent for hash chain. Range: `CHAINLOG_MIN` to `CHAINLOG_MAX`. `0` = default |
| `search_log` | `int` | `0` | Search log exponent. Range: `SEARCHLOG_MIN` to `SEARCHLOG_MAX`. `0` = default |
| `min_match` | `int` | `0` | Minimum match length. Range: `MINMATCH_MIN` to `MINMATCH_MAX`. `0` = default |
| `target_length` | `int` | `0` | Target match length. Range: `TARGETLENGTH_MIN` to `TARGETLENGTH_MAX`. `0` = default |
| `strategy` | `int` | `-1` | Compression strategy: `STRATEGY_*` constants. `-1` = default for level. `0` = disabled |
| `write_content_size` | `int` | `1` | Include uncompressed content size in frame header (0=no, 1=yes) |
| `write_checksum` | `int` | `0` | Include content checksum in frame (0=no, 1=yes) |
| `write_dict_id` | `int` | `0` | Include dictionary ID in frame (0=no, 1=yes) |
| `job_size` | `int` | `0` | Job size for multi-threaded compression in bytes. `0` = default |
| `overlap_log` | `int` | `-1` | Overlap log for multi-threaded compression. `-1` = default. `0` = disabled |
| `force_max_window` | `int` | `0` | Force maximum window size (0=no, 1=yes) |
| `enable_ldm` | `int` | `0` | Enable Long Distance Matching (0=no, 1=yes) |
| `ldm_hash_log` | `int` | `0` | LDM hash log exponent. Range: `HASHLOG_MIN` to `HASHLOG_MAX`. `0` = default |
| `ldm_min_match` | `int` | `0` | LDM minimum match length. Range: `LDM_MINMATCH_MIN` to `LDM_MINMATCH_MAX`. `0` = default |
| `ldm_bucket_size_log` | `int` | `0` | LDM bucket size log. Range: 0 to `LDM_BUCKETSIZELOG_MAX`. `0` = default |
| `ldm_hash_rate_log` | `int` | `-1` | LDM hash rate log. `-1` = default. `0` = disabled |
| `threads` | `int` | `0` | Number of threads for multi-threaded compression. `0` = CPU count; `-1` = single-threaded; positive = explicit count |

**Raises:** `ZstdError` — If any parameter is out of valid range

**Example:**
```python
import zstandard

# Basic custom parameters
params = zstandard.ZstdCompressionParameters(
    window_log=12,
    hash_log=13,
)

# Advanced parameters for high compression
params = zstandard.ZstdCompressionParameters(
    compression_level=22,
    window_log=31,
    strategy=zstandard.STRATEGY_BTULTRA2,
    threads=4,
)

# Long Distance Matching for highly repetitive data
params = zstandard.ZstdCompressionParameters(
    compression_level=15,
    enable_ldm=1,
    ldm_hash_log=16,
    ldm_min_match=64,
)

cctx = zstandard.ZstdCompressor(compression_params=params)
```
```

--------------------------------

### Train a Zstandard Compression Dictionary

Source: https://github.com/indygreg/python-zstandard/blob/main/_autodocs/api-reference/compression-dict.md

Train a compression dictionary from a collection of representative data samples. The trained dictionary can then be saved and reused. Ensure sufficient samples are provided for effective dictionary training.

```python
import zstandard

# Collect representative samples
samples = [
    b"JSON document 1..." for _ in range(10)
]

# Train dictionary
dict_obj = zstandard.train_dictionary(
    dict_size=8192,
    samples=samples,
    level=10,
)

# Save for later use
dict_bytes = dict_obj.as_bytes()
with open('my_dict.bin', 'wb') as f:
    f.write(dict_bytes)

print(f"Dictionary ID: {dict_obj.dict_id()}")
```