# `compression.zstd` — Compactação compatível com o formato Zstandard

Adicionado na versão 3.14.

Código-fonte: Lib/compression/zstd/__init__.py

Este módulo fornece classes e funções para compactar e descompactar dados usando o algoritmo de compactação Zstandard (ou zstd). O manual do zstd descreve o Zstandard como “um algoritmo de compactação rápido e sem perdas, voltado para cenários de compactação em tempo real no nível zlib e melhores taxas de compactação”. Também está incluída uma interface de arquivo que oferece suporte à leitura e à gravação do conteúdo de arquivos `.zst` criados pelo utilitário zstd, bem como fluxos compactados zstd brutos.

O módulo `compression.zstd` contém:

- A função `open()` e a classe `ZstdFile` para leitura e escrita de arquivos compactados.

- As classes `ZstdCompressor` e `ZstdDecompressor` para (des)compactação incremental.

- As funções `compress()` e `decompress()` para (des)compressão de uma só vez.

- As funções `train_dict()` e `finalize_dict()` e a classe `ZstdDict` para treinar e gerenciar dicionários Zstandard.

- As classes `CompressionParameter`, `DecompressionParameter` e `Strategy` para definir parâmetros avançados de (des)compactação.

## Exceções

exception compression.zstd.ZstdError

  Essa exceção é levantada quando ocorre um erro durante a compactação ou descompactação ou durante a inicialização do estado (des)compactador.

## Lendo e escrevendo arquivos comprimidos

compression.zstd.open(file, /, mode='rb', *, level=None, options=None, zstd_dict=None, encoding=None, errors=None, newline=None)

  Abre um arquivo compactado com Zstandard em modo binário ou texto, retornando objeto arquivo.

  O argumento file pode ser um nome de arquivo (dado como um objeto `str`, `bytes` ou caminho ou similar), neste caso o arquivo nomeado é aberto , ou pode ser um objeto arquivo existente para leitura ou escrita.

  O argumento mode pode ser `'rb'` para leitura (padrão), `'wb'` para sobrescrever, `'ab'` para anexar ou `'xb'` para criação exclusiva. Estes podem ser fornecidos como `'r'`, `'w'`, `'a'` e `'x'`, respectivamente. Você também pode abrir em modo texto com `'rt'`, `'wt'`, `'at'` e `'xt'`, respectivamente.

  Durante a leitura, o argumento options pode ser um dicionário que fornece parâmetros avançados de descompactação; consulte `DecompressionParameter` para obter informações detalhadas sobre os parâmetros suportados. O argumento zstd_dict é uma instância de `ZstdDict` a ser usada durante a descompactação. Durante a leitura, se o argumento level não for None, uma exceção `TypeError` será levantada.

  Ao escrever, o argumento options pode ser um dicionário que fornece parâmetros avançados de descompactação; consulte `CompressionParameter` para obter informações detalhadas sobre os parâmetros suportados. O argumento level é o nível de compactação a ser usado ao escrever dados compactados. Apenas level ou options pode ser diferente de None. O argumento zstd_dict é uma instância de `ZstdDict` a ser usada durante a compactação.

  Em modo binário, esta função equivale ao construtor `ZstdFile`: `ZstdFile(file, mode, ...)`. Nesse caso, os parâmetros encoding, errors e newline não devem ser fornecidos.

  Em modo texto, um objeto `ZstdFile` é criado e encapsulado em uma instância `io.TextIOWrapper` com a codificação especificada, comportamento de tratamento de erros e fins de linha.

class compression.zstd.ZstdFile(file, /, mode='rb', *, level=None, options=None, zstd_dict=None)

  Abre um arquivo compactado com Zstandard no modo binário.

  Um `ZstdFile` pode envolver um objeto arquivo já aberto, ou operar diretamente em um arquivo nomeado. O argumento file especifica o objeto arquivo a ser envolvido ou o nome do arquivo a ser aberto (como um objeto `str`, `bytes` ou objeto caminho ou similar). Se estiver envolvendo um objeto arquivo existente, o arquivo envolvido não será fechado quando o `ZstdFile` for fechado.

  O argumento mode pode ser `'rb'` para leitura (padrão), `'wb'` para substituição, `'xb'` para criação exclusiva ou `'ab'` para anexar. Estes podem ser equivalentemente dados como `'r'`, `'w'`, `'x'` e `'a'` respectivamente.

  Se file for um objeto arquivo (ao invés de um nome de arquivo real), um modo de `'w'` não truncará o arquivo e será equivalente a `'a'`.

  Durante a leitura, o argumento options pode ser um dicionário que fornece parâmetros avançados de descompactação; consulte `DecompressionParameter` para obter informações detalhadas sobre os parâmetros suportados. O argumento zstd_dict é uma instância de `ZstdDict` a ser usada durante a descompactação. Durante a leitura, se o argumento level não for None, uma exceção `TypeError` será levantada.

  Ao escrever, o argumento options pode ser um dicionário que fornece parâmetros avançados de descompactação; consulte `CompressionParameter` para obter informações detalhadas sobre os parâmetros suportados. O argumento level é o nível de compactação a ser usado ao escrever dados compactados. Apenas level ou options pode ser passado. O argumento zstd_dict é uma instância de `ZstdDict` a ser usada durante a compactação.

  `ZstdFile` oferece suporte a todos os membros especificados por `io.BufferedIOBase`, exceto `detach()` e `truncate()`. Iteração e a instrução `with` são suportadas.

  O método e os atributos a seguir também são fornecidos:

  peek(size=-1)

    Retorna dados armazenados em buffer sem avançar a posição do arquivo. Pelo menos um byte de dados será retornado, a menos que o EOF tenha sido atingido. O número exato de bytes retornados não é especificado (o argumento size é ignorado).

    Nota

    Enquanto chamar `peek()` não altera a posição do arquivo de `ZstdFile`, pode alterar a posição do objeto arquivo subjacente (por exemplo, se o `ZstdFile` foi construído passando um objeto arquivo para file).

  mode

    `'rb'` para leitura e `'wb'` para escrita.

  name

    O nome do arquivo Zstandard. Equivalente ao atributo `name` do objeto arquivo subjacente.

## Comprimindo e descomprimindo dados na memória

compression.zstd.compress(data, level=None, options=None, zstd_dict=None)

  Compacta data (um objeto bytes ou similar), retornando os dados compactados como um objeto `bytes`.

  O argumento level é um inteiro que controla o nível de compactação. level é uma alternativa à configuração `CompressionParameter.compression_level` em options. Use `bounds()` em `compression_level` para obter os valores que podem ser passados para level. Se opções avançadas de compactação forem necessárias, o argumento level deve ser omitido e, no dicionário options, o parâmetro `CompressionParameter.compression_level` deve ser definido.

  O argumento options é um dicionário Python que contém parâmetros de compactação avançados. As chaves e valores válidos para parâmetros de compactação estão documentados na documentação `CompressionParameter`.

  O argumento zstd_dict é uma instância de `ZstdDict` contendo dados treinados para melhorar a eficiência da compactação. A função `train_dict()` pode ser usada para gerar um dicionário Zstandard.

compression.zstd.decompress(data, zstd_dict=None, options=None)

  Descompacta data (um objeto bytes ou similar), retornando os dados descompactados como um objeto `bytes`.

  O argumento options é um dicionário Python que contém parâmetros de descompactação avançados. As chaves e valores válidos para parâmetros de compactação estão documentados na documentação `DecompressionParameter`.

  O argumento zstd_dict é uma instância de `ZstdDict` contendo dados treinados usados durante a compactação. Este deve ser o mesmo dicionário Zstandard usado durante a compactação.

  Se data forem a concatenação de vários quadros comprimidos distintos, descomprime todos esses quadros e retorna a concatenação dos resultados.

class compression.zstd.ZstdCompressor(level=None, options=None, zstd_dict=None)

  Cria um objeto compressão, que pode ser usado para comprimir dados de forma incremental.

  Para uma maneira mais conveniente de compactar um único bloco de dados, consulte a função a nível de módulo `compress()`.

  O argumento level é um inteiro que controla o nível de compactação. level é uma alternativa à configuração `CompressionParameter.compression_level` em options. Use `bounds()` em `compression_level` para obter os valores que podem ser passados para level. Se opções avançadas de compactação forem necessárias, o argumento level deve ser omitido e, no dicionário options, o parâmetro `CompressionParameter.compression_level` deve ser definido.

  O argumento options é um dicionário Python que contém parâmetros de compactação avançados. As chaves e valores válidos para parâmetros de compactação estão documentados na documentação `CompressionParameter`.

  O argumento zstd_dict é uma instância opcional de `ZstdDict` contendo dados treinados para melhorar a eficiência da compactação. A função `train_dict()` pode ser usada para gerar um dicionário Zstandard.

  compress(data, mode=ZstdCompressor.CONTINUE)

    Compacte data (um objeto bytes ou similar), retornando um objeto `bytes` com dados compactados, se possível, ou, caso contrário, um objeto `bytes` vazio. Alguns dos data podem ser armazenados internamente em buffer, para uso em chamadas posteriores a `compress()` e `flush()`. Os dados retornados devem ser concatenados com a saída de quaisquer chamadas anteriores a `compress()`.

    O argumento mode é um atributo `ZstdCompressor`, podendo ser definido com `CONTINUE`, `FLUSH_BLOCK` ou `FLUSH_FRAME`.

    Quando todos os dados forem fornecidos ao compactador, chama o método `flush()` para finalizar o processo de compactação. Se `compress()` for chamado com mode definido como `FLUSH_FRAME`, `flush()` não deve ser chamado, pois gravaria um novo quadro vazio.

  flush(mode=ZstdCompressor.FLUSH_FRAME)

    Conclui o processo de compressão, retornando um objeto `bytes` contendo todos os dados armazenados nos buffers internos do compressor.

    O argumento mode é um atributo `ZstdCompressor`, podendo ser definido com `FLUSH_BLOCK` ou `FLUSH_FRAME`.

  set_pledged_input_size(size)

    Especifica a quantidade de size dados descompactados que será fornecida para o próximo quadro. size será gravado no cabeçalho do quadro do próximo quadro, a menos que `CompressionParameter.content_size_flag` seja `False` ou `0`. Um tamanho `0` significa que o quadro está vazio. Se size for `None`, o cabeçalho do quadro omitirá o tamanho do quadro. Quadros que incluem o tamanho dos dados descompactados requerem menos memória para descompactação, especialmente em níveis de compactação mais altos.

    Se `last_mode` não for `FLUSH_FRAME`, uma `ValueError` será levantada, pois o compressor não está no início de um quadro. Se o tamanho prometido não corresponder ao tamanho real dos dados fornecidos para `compress()`, chamadas futuras para `compress()` ou `flush()` poderão levantar `ZstdError` e o último bloco de dados poderá ser perdido.

    Depois que `flush()` ou `compress()` são chamados com o modo `FLUSH_FRAME`, o próximo quadro não incluirá o tamanho do quadro no cabeçalho, a menos que `set_pledged_input_size()` seja chamado novamente.

  CONTINUE

    Coleta mais dados para compactação, o que pode ou não gerar saída imediata. Este modo otimiza a taxa de compactação maximizando a quantidade de dados por bloco e quadro.

  FLUSH_BLOCK

    Conclui e grava um bloco no fluxo de dados. Os dados retornados até o momento podem ser descompactados imediatamente. Dados anteriores ainda podem ser referenciados em blocos futuros gerados por chamadas a `compress()`, melhorando a compactação.

  FLUSH_FRAME

    Conclui e escreve um quadro. Dados futuros fornecidos a `compress()` serão gravados em um novo quadro e não poderão fazer referência a dados passados.

  last_mode

    O último modo passado para `compress()` ou `flush()`. O valor pode ser `CONTINUE`, `FLUSH_BLOCK` ou `FLUSH_FRAME`. O valor inicial é `FLUSH_FRAME`, significando que o compactador está no início de um novo quadro.

class compression.zstd.ZstdDecompressor(zstd_dict=None, options=None)

  Cria um objeto descompressor, que pode ser usado para descomprimir dados de forma incremental.

  Para uma maneira mais conveniente de descompactar todo um fluxo compactado de uma só vez, consulte a função a nível de módulo `decompress()`.

  O argumento options é um dicionário Python que contém parâmetros de descompactação avançados. As chaves e valores válidos para parâmetros de compactação estão documentados na documentação `DecompressionParameter`.

  O argumento zstd_dict é uma instância de `ZstdDict` contendo dados treinados usados durante a compactação. Este deve ser o mesmo dicionário Zstandard usado durante a compactação.

  Nota

  Esta classe não lidam de forma transparente entradas contendo múltiplos quadros compactados, ao contrário da função `decompress()` e da classe `ZstdFile`. Para descompactar uma entrada com múltiplos quadros, você deve usar `decompress()`, `ZstdFile` se estiver trabalhando com um objeto arquivo ou múltiplas instâncias de `ZstdDecompressor`.

  decompress(data, max_length=-1)

    Descompacta dados data (um objeto bytes ou similar), retornando dados não compactados como bytes. Alguns dos data podem ser armazenados em buffer internamente, para uso em chamadas posteriores para `decompress()`. Os dados retornados devem ser concatenados com a saída de qualquer chamada anterior para `decompress()`.

    Se max_length for não negativo, o método retornará no máximo max_length bytes de dados descomprimidos. Se este limite for atingido e mais saída puder ser produzida, o atributo `needs_input` será definido como `False`. Neste caso, a próxima chamada para `decompress()` pode fornecer data como `b''` para obter mais saída.

    Se todos os dados de entrada foram descomprimidos e retornados (seja porque era menor que max_length bytes, ou porque max_length era negativo), o atributo `needs_input` será definido como `True` .

    Tentar descompactar dados após o final de um quadro levantará um erro `ZstdError`. Quaisquer dados encontrados após o final do quadro serão ignorados e salvos no atributo `unused_data`.

  eof

    `True` se o marcador de fim de fluxo foi atingido.

  unused_data

    Dados encontrados após o término do fluxo comprimido.

    Antes do final do fluxo ser alcançado, isso será `b''`.

  needs_input

    `False` se o método `decompress()` puder fornecer mais dados descompactados antes de exigir uma nova entrada compactada.

## Dicionários de Zstandard

compression.zstd.train_dict(samples, dict_size)

  Treina um dicionário Zstandard, retornando uma instância `ZstdDict`. Os dicionários Zstandard permitem uma compactação mais eficiente de dados menores, que tradicionalmente são difíceis de comprimir devido à menor repetição. Se você estiver compactando vários grupos de dados semelhantes (como arquivos semelhantes), os dicionários Zstandard podem melhorar significativamente as taxas de compactação e a velocidade.

  O argumento samples (um iterável de objetos `bytes`) é a população de amostras usada para treinar o dicionário Zstandard.

  O argumento dict_size, um inteiro, é o tamanho máximo (em bytes) que o dicionário Zstandard deve ter. A documentação do Zstandard sugere um máximo absoluto de no máximo 100 KB, mas o máximo pode ser menor dependendo dos dados. Dicionários maiores geralmente reduzem a compactação, mas melhoram as taxas de compactação. Dicionários menores levam a uma compactação mais rápida, mas reduzem a taxa de compactação.

compression.zstd.finalize_dict(zstd_dict, /, samples, dict_size, level)

  Uma função avançada para converter um dicionário Zstandard de “conteúdo bruto” em um dicionário Zstandard comum. Dicionários de “conteúdo bruto” são uma sequência de bytes que não precisa seguir a estrutura de um dicionário Zstandard comum.

  O argumento zstd_dict é uma instância `ZstdDict` com `dict_content` contendo o conteúdo bruto do dicionário.

  O argumento samples (um iterável de objetos `bytes`) contém dados de amostra para gerar o dicionário Zstandard.

  O argumento dict_size, um inteiro, é o tamanho máximo (em bytes) que o dicionário Zstandard deve ter. Consulte `train_dict()` para sugestões sobre o tamanho máximo do dicionário.

  O argumento level (um inteiro) é o nível de compactação que se espera que seja passado aos compactadores usando este dicionário. As informações do dicionário variam para cada nível de compactação, portanto, ajustar o nível de compactação adequado pode tornar a compactação mais eficiente.

class compression.zstd.ZstdDict(dict_content, /, *, is_raw=False)

  Um invólucro para dicionários Zstandard. Dicionários podem ser usados para melhorar a compactação de muitos pequenos blocos de dados. Use `train_dict()` se precisar treinar um novo dicionário a partir de dados de amostra.

  O argumento dict_content (um objeto bytes ou similar) é a informação do dicionário já treinada.

  O argumento is_raw, um booleano, é um parâmetro avançado que controla o significado de dict_content. `True` significa que dict_content é um dicionário de “conteúdo bruto”, sem nenhuma restrição de formato. `False` significa que dict_content é um dicionário Zstandard comum, criado a partir de funções Zstandard, por exemplo, `train_dict()` ou a CLI externa zstd.

  Ao passar um `ZstdDict` para uma função, os atributos `as_digested_dict` e `as_undigested_dict` podem controlar como o dicionário é carregado, passando-os como o argumento `zstd_dict`, por exemplo, `compress(data, zstd_dict=zd.as_digested_dict)`. A digestão de um dicionário é uma operação custosa que ocorre ao carregar um dicionário Zstandard. Ao fazer várias chamadas para compactação ou descompactação, passar um dicionário digerido reduzirá a sobrecarga de carregamento do dicionário.

  > Diferença para compactação
  > | Digested dictionary | Undigested dictionary
  > --- | --- | ---
  > Parâmetros avançados do compressor que podem ser substituídos pelos parâmetros do dicionário | `window_log`, `hash_log`, `chain_log`, `search_log`, `min_match`, `target_length`, `strategy`, `enable_long_distance_matching`, `ldm_hash_log`, `ldm_min_match`, `ldm_bucket_size_log`, `ldm_hash_rate_log` e alguns parâmetros não-públicos. | None
  > `ZstdDict` armazena em cache internamente o dicionário | Yes. It’s faster when loading a digested dictionary again with the same compression level. | No. If you wish to load an undigested dictionary multiple times, consider reusing a compressor object.

  If passing a `ZstdDict` without any attribute, an undigested dictionary is passed by default when compressing and a digested dictionary is generated if necessary and passed by default when decompressing.

  > dict_content

  >   The content of the Zstandard dictionary, a `bytes` object. It’s the same as the dict_content argument in the `__init__` method. It can be used with other programs, such as the `zstd` CLI program.

  > dict_id

  >   Identifier of the Zstandard dictionary, a non-negative int value.

  >   Non-zero means the dictionary is ordinary, created by Zstandard functions and following the Zstandard format.

  >   `0` means a “raw content” dictionary, free of any format restriction, used for advanced users.

  >   Nota

  >   The meaning of `0` for `ZstdDict.dict_id` is different from the `dictionary_id` attribute to the `get_frame_info()` function.

  > as_digested_dict

  >   Load as a digested dictionary.

  > as_undigested_dict

  >   Load as an undigested dictionary.

## Advanced parameter control

class compression.zstd.CompressionParameter

  An `IntEnum` containing the advanced compression parameter keys that can be used when compressing data.

  The `bounds()` method can be used on any attribute to get the valid values for that parameter.

  Parameters are optional; any omitted parameter will have it’s value selected automatically.

  Example getting the lower and upper bound of `compression_level`:

      lower, upper = CompressionParameter.compression_level.bounds()

  Example setting the `window_log` to the maximum size:

      _lower, upper = CompressionParameter.window_log.bounds()
      options = {CompressionParameter.window_log: upper}
      compress(b'venezuelan beaver cheese', options=options)

  bounds()

    Return the tuple of int bounds, `(lower, upper)`, of a compression parameter. This method should be called on the attribute you wish to retrieve the bounds of. For example, to get the valid values for `compression_level`, one may check the result of `CompressionParameter.compression_level.bounds()`.

    Both the lower and upper bounds are inclusive.

  compression_level

    A high-level means of setting other compression parameters that affect the speed and ratio of compressing data.

    Regular compression levels are greater than `0`. Values greater than `20` are considered “ultra” compression and require more memory than other levels. Negative values can be used to trade off faster compression for worse compression ratios.

    Setting the level to zero uses `COMPRESSION_LEVEL_DEFAULT`.

  window_log

    Maximum allowed back-reference distance the compressor can use when compressing data, expressed as power of two, `1 << window_log` bytes. This parameter greatly influences the memory usage of compression. Higher values require more memory but gain better compression values.

    A value of zero causes the value to be selected automatically.

  hash_log

    Size of the initial probe table, as a power of two. The resulting memory usage is `1 << (hash_log+2)` bytes. Larger tables improve compression ratio of strategies <= `dfast`, and improve compression speed of strategies > `dfast`.

    A value of zero causes the value to be selected automatically.

  chain_log

    Size of the multi-probe search table, as a power of two. The resulting memory usage is `1 << (chain_log+2)` bytes. Larger tables result in better and slower compression. This parameter has no effect for the `fast` strategy. It’s still useful when using `dfast` strategy, in which case it defines a secondary probe table.

    A value of zero causes the value to be selected automatically.

  search_log

    Number of search attempts, as a power of two. More attempts result in better and slower compression. This parameter is useless for `fast` and `dfast` strategies.

    A value of zero causes the value to be selected automatically.

  min_match

    Minimum size of searched matches. Larger values increase compression and decompression speed, but decrease ratio. Note that Zstandard can still find matches of smaller size, it just tweaks its search algorithm to look for this size and larger. For all strategies < `btopt`, the effective minimum is `4`; for all strategies > `fast`, the effective maximum is `6`.

    A value of zero causes the value to be selected automatically.

  target_length

    The impact of this field depends on the selected `Strategy`.

    For strategies `btopt`, `btultra` and `btultra2`, the value is the length of a match considered “good enough” to stop searching. Larger values make compression ratios better, but compresses slower.

    For strategy `fast`, it is the distance between match sampling. Larger values make compression faster, but with a worse compression ratio.

    A value of zero causes the value to be selected automatically.

  strategy

    The higher the value of selected strategy, the more complex the compression technique used by zstd, resulting in higher compression ratios but slower compression.

    Ver também

    `Strategy`

  enable_long_distance_matching

    Long distance matching can be used to improve compression for large inputs by finding large matches at greater distances. It increases memory usage and window size.

    `True` or `1` enable long distance matching while `False` or `0` disable it.

    Enabling this parameter increases default `window_log` to 128 MiB except when expressly set to a different value. This setting is enabled by default if `window_log` >= 128 MiB and the compression strategy >= `btopt` (compression level 16+).

  ldm_hash_log

    Size of the table for long distance matching, as a power of two. Larger values increase memory usage and compression ratio, but decrease compression speed.

    A value of zero causes the value to be selected automatically.

  ldm_min_match

    Minimum match size for long distance matcher. Larger or too small values can often decrease the compression ratio.

    A value of zero causes the value to be selected automatically.

  ldm_bucket_size_log

    Log size of each bucket in the long distance matcher hash table for collision resolution. Larger values improve collision resolution but decrease compression speed.

    A value of zero causes the value to be selected automatically.

  ldm_hash_rate_log

    Frequency of inserting/looking up entries into the long distance matcher hash table. Larger values improve compression speed. Deviating far from the default value will likely result in a compression ratio decrease.

    A value of zero causes the value to be selected automatically.

  content_size_flag

    Write the size of the data to be compressed into the Zstandard frame header when known prior to compressing.

    This flag only takes effect under the following scenarios:

    - Calling `compress()` for one-shot compression

    - Providing all of the data to be compressed in the frame in a single `ZstdCompressor.compress()` call, with the `ZstdCompressor.FLUSH_FRAME` mode.

    - Calling `ZstdCompressor.set_pledged_input_size()` with the exact amount of data that will be provided to the compressor prior to any calls to `ZstdCompressor.compress()` for the current frame. `ZstdCompressor.set_pledged_input_size()` must be called for each new frame.

    All other compression calls may not write the size information into the frame header.

    `True` or `1` enable the content size flag while `False` or `0` disable it.

  checksum_flag

    A four-byte checksum using XXHash64 of the uncompressed content is written at the end of each frame. Zstandard’s decompression code verifies the checksum. If there is a mismatch a `ZstdError` exception is raised.

    `True` or `1` enable checksum generation while `False` or `0` disable it.

  dict_id_flag

    When compressing with a `ZstdDict`, the dictionary’s ID is written into the frame header.

    `True` or `1` enable storing the dictionary ID while `False` or `0` disable it.

  nb_workers

    Select how many threads will be spawned to compress in parallel. When `nb_workers` > 0, enables multi-threaded compression, a value of `1` means “one-thread multi-threaded mode”. More workers improve speed, but also increase memory usage and slightly reduce compression ratio.

    A value of zero disables multi-threading.

  job_size

    Size of a compression job, in bytes. This value is enforced only when `nb_workers` >= 1. Each compression job is completed in parallel, so this value can indirectly impact the number of active threads.

    A value of zero causes the value to be selected automatically.

  overlap_log

    Sets how much data is reloaded from previous jobs (threads) for new jobs to be used by the look behind window during compression. This value is only used when `nb_workers` >= 1. Acceptable values vary from 0 to 9.

    > - 0 means dynamically set the overlap amount

    > - 1 means no overlap

    > - 9 means use a full window size from the previous job

    Each increment halves/doubles the overlap size. “8” means an overlap of `window_size/2`, “7” means an overlap of `window_size/4`, etc.

class compression.zstd.DecompressionParameter

  An `IntEnum` containing the advanced decompression parameter keys that can be used when decompressing data. Parameters are optional; any omitted parameter will have it’s value selected automatically.

  The `bounds()` method can be used on any attribute to get the valid values for that parameter.

  Example setting the `window_log_max` to the maximum size:

      data = compress(b'Some very long buffer of bytes...')

      _lower, upper = DecompressionParameter.window_log_max.bounds()

      options = {DecompressionParameter.window_log_max: upper}
      decompress(data, options=options)

  bounds()

    Return the tuple of int bounds, `(lower, upper)`, of a decompression parameter. This method should be called on the attribute you wish to retrieve the bounds of.

    Both the lower and upper bounds are inclusive.

  window_log_max

    The base-two logarithm of the maximum size of the window used during decompression. This can be useful to limit the amount of memory used when decompressing data. A larger maximum window size leads to faster decompression.

    A value of zero causes the value to be selected automatically.

class compression.zstd.Strategy

  An `IntEnum` containing strategies for compression. Higher-numbered strategies correspond to more complex and slower compression.

  Nota

  The values of attributes of `Strategy` are not necessarily stable across zstd versions. Only the ordering of the attributes may be relied upon. The attributes are listed below in order.

  The following strategies are available:

  fast
  dfast
  greedy
  lazy
  lazy2
  btlazy2
  btopt
  btultra
  btultra2

## Diversos

compression.zstd.get_frame_info(frame_buffer)

  Retrieve a `FrameInfo` object containing metadata about a Zstandard frame. Frames contain metadata related to the compressed data they hold.

class compression.zstd.FrameInfo

  Metadata related to a Zstandard frame.

  decompressed_size

    The size of the decompressed contents of the frame.

  dictionary_id

    An integer representing the Zstandard dictionary ID needed for decompressing the frame. `0` means the dictionary ID was not recorded in the frame header. This may mean that a Zstandard dictionary is not needed, or that the ID of a required dictionary was not recorded.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

  The default compression level for Zstandard: `3`.

compression.zstd.zstd_version_info

  Version number of the runtime zstd library as a tuple of integers (major, minor, release).

## Exemplos

Reading in a compressed file:

    from compression import zstd

    with zstd.open("file.zst") as f:
        file_content = f.read()

Creating a compressed file:

    from compression import zstd

    data = b"Insert Data Here"
    with zstd.open("file.zst", "w") as f:
        f.write(data)

Compressing data in memory:

    from compression import zstd

    data_in = b"Insert Data Here"
    data_out = zstd.compress(data_in)

Incremental compression:

    from compression import zstd

    comp = zstd.ZstdCompressor()
    out1 = comp.compress(b"Some data\n")
    out2 = comp.compress(b"Another piece of data\n")
    out3 = comp.compress(b"Even more data\n")
    out4 = comp.flush()
    # Concatenate all the partial results:
    result = b"".join([out1, out2, out3, out4])

Writing compressed data to an already-open file:

    from compression import zstd

    with open("myfile", "wb") as f:
        f.write(b"This data will not be compressed\n")
        with zstd.open(f, "w") as zstf:
            zstf.write(b"This *will* be compressed\n")
        f.write(b"Not compressed\n")

Creating a compressed file using compression parameters:

    from compression import zstd

    options = {
       zstd.CompressionParameter.checksum_flag: 1
    }
    with zstd.open("file.zst", "w", options=options) as f:
        f.write(b"Mind if I squeeze in?")