# `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 de zlib, com taxas de compactação melhores”. 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 de 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)compactaçã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.

Este é um módulo opcional. Se ele estiver faltando na sua cópia do CPython, procure a documentação do seu distribuidor (ou seja, quem lhe forneceu o Python). Se você for o distribuidor, consulte Requisitos para módulos opcionais.

## 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 compactados

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.

  When writing, the options argument can be a dictionary providing advanced compression parameters; see `CompressionParameter` for detailed information about supported parameters. The level argument is the compression level to use when writing compressed data. Only one of level or options may be non-None. The zstd_dict argument is a `ZstdDict` instance to be used during compression.

  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.

  When writing, the options argument can be a dictionary providing advanced compression parameters; see `CompressionParameter` for detailed information about supported parameters. The level argument is the compression level to use when writing compressed data. Only one of level or options may be passed. The zstd_dict argument is a `ZstdDict` instance to be used during compression.

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

## Compactando e descompactando 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 compactados distintos, descompacta todos esses quadros e retorna a concatenação dos resultados.

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

  Cria um objeto compactação, que pode ser usado para compactar 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 compactaçã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 compactador 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 descompactador, que pode ser usado para descompactar 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 descompactados. 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 descompactados 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 compactado.

    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 compactar 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
  > | Dicionário resumido | Dicionário não resumido
  > --- | --- | ---
  > Parâmetros avançados do compactador 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 | Sim. É mais rápido carregar um dicionário resumido novamente com o mesmo nível de compactação. | Não. Se você deseja carregar um dicionário não digerido várias vezes, considere reutilizar um objeto compressor.

  Se passar um `ZstdDict` sem nenhum atributo, um dicionário não digerido será passado por padrão ao compactar e um dicionário digerido será gerado, se necessário, e passado por padrão ao descompactar.

  > dict_content

  >   O conteúdo do dicionário Zstandard, um objeto `bytes`. É o mesmo que o argumento dict_content no método `__init__`. Pode ser usado com outros programas, como o programa de linha de comando `zstd`.

  > dict_id

  >   Identificador do dicionário Zstandard, um valor inteiro não negativo.

  >   Um valor diferente de zero significa que o dicionário é comum, criado por funções Zstandard e seguindo o formato Zstandard.

  >   `0` significa um dicionário de “conteúdo bruto”, livre de qualquer restrição de formato, usado para usuários avançados.

  >   Nota

  >   O significado de `0` para `ZstdDict.dict_id` é diferente do atributo `dictionary_id` da função `get_frame_info()`.

  > as_digested_dict

  >   Carrega como um dicionário resumido.

  > as_undigested_dict

  >   Carrega como um dicionário não digerido.

## Controle avançado de parâmetros

class compression.zstd.CompressionParameter

  Uma `IntEnum` contendo as chaves de parâmetros de compactação avançada que podem ser usadas ao compactar dados.

  O método `bounds()` pode ser usado em qualquer atributo para obter os valores válidos para esse parâmetro.

  Os parâmetros são opcionais; qualquer parâmetro omitido terá seu valor selecionado automaticamente.

  Exemplo de obtenção da delimitação inferior e superior de `compression_level`:

      lower, upper = CompressionParameter.compression_level.bounds()

  Exemplo de configuração do atributo `window_log` para o tamanho máximo:

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

  bounds()

    Retorna a tupla de limites int, `(lower, upper)`, de um parâmetro de compactação. Este método deve ser chamado no atributo cujos limites você deseja recuperar. Por exemplo, para obter os valores válidos para `compression_level`, pode-se verificar o resultado de `CompressionParameter.compression_level.bounds()`.

    Tanto o limite inferior quanto o superior são inclusivos.

  compression_level

    Um meio de alto nível para definir outros parâmetros de compactação que afetam a velocidade e a taxa de compactação de dados.

    Os níveis de compactação regulares são maiores que `0`. Valores maiores que `20` são considerados compactação “ultra” e requerem mais memória do que outros níveis. Valores negativos podem ser usados para compensar uma compactação mais rápida por taxas de compactação piores.

    Define o nível como zero usa `COMPRESSION_LEVEL_DEFAULT`.

  window_log

    Distância máxima de referência reversa permitida que o compactador pode usar ao compactar dados, expressa como potência de dois, `1 << window_log` bytes. Este parâmetro influencia bastante o uso de memória da compactação. Valores mais altos requerem mais memória, mas geram melhores valores de compactação.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  hash_log

    Tamanho da tabela de sondagem inicial, como uma potência de dois. O uso de memória resultante é `1 << (hash_log+2)` bytes. Tabelas maiores melhoram a taxa de compactação de estratégias <= `dfast` e melhoram a velocidade de compactação de estratégias > `dfast`.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  chain_log

    Tamanho da tabela de busca multiprobe, como uma potência de dois. O uso de memória resultante é `1 << (chain_log+2)` bytes. Tabelas maiores resultam em uma compactação melhor e mais lenta. Este parâmetro não tem efeito para a estratégia `fast`. Ele ainda é útil ao usar a estratégia `dfast`, caso em que define uma tabela de sondagem secundária.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  search_log

    Número de tentativas de busca, como uma potência de dois. Mais tentativas resultam em uma compactação melhor e mais lenta. Este parâmetro é inútil para as estratégias `fast` e `dfast`.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  min_match

    Tamanho mínimo das correspondências pesquisadas. Valores maiores aumentam a velocidade de compactação e descompactação, mas diminuem a taxa. Observe que o Zstandard ainda consegue encontrar correspondências de tamanho menor; ele apenas ajusta seu algoritmo de busca para procurar por esse tamanho e por tamanhos maiores. Para todas as estratégias < `btopt`, o mínimo efetivo é `4`; para todas as estratégias > `fast`, o máximo efetivo é `6`.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  target_length

    O impacto deste campo depende da `Strategy` selecionada.

    Para as estratégias `btopt`, `btultra` e `btultra2`, o valor é o comprimento de uma correspondência considerada “boa o suficiente” para interromper a busca. Valores maiores melhoram as taxas de compactação, mas a compactação é mais lenta.

    Para a estratégia `fast`, é a distância entre as amostragens de correspondência. Valores maiores tornam a compactação mais rápida, mas com uma taxa de compactação pior.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  strategy

    Quanto maior o valor da estratégia selecionada, mais complexa será a técnica de compactação usada pelo zstd, resultando em taxas de compactação mais altas, mas em compactação mais lenta.

    Ver também

    `Strategy`

  enable_long_distance_matching

    A correspondência de longa distância pode ser usada para melhorar a compactação de entradas grandes, encontrando correspondências maiores em distâncias maiores. Ela aumenta o uso de memória e o tamanho da janela.

    Os valores `True` ou `1` habilitam a correspondência a longa distância, enquanto os valores `False` ou `0` a desabilitam.

    Habilitar este parâmetro aumenta o tamanho padrão de `window_log` para 128 MiB, exceto quando expressamente definido com um valor diferente. Esta configuração é habilitada por padrão se `window_log` >= 128 MiB e a estratégia de compactação >= `btopt` (nível de compactação 16+).

  ldm_hash_log

    Tamanho da tabela para correspondência de longa distância, como uma potência de dois. Valores maiores aumentam o uso de memória e a taxa de compactação, mas diminuem a velocidade de compactação.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  ldm_min_match

    Tamanho mínimo de correspondência para correspondência de longa distância. Valores maiores ou muito pequenos podem frequentemente diminuir a taxa de compactação.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  ldm_bucket_size_log

    Tamanho do log de cada bucket na tabela hash do comparador de longa distância para resolução de colisões. Valores maiores melhoram a resolução de colisões, mas diminuem a velocidade de compactação.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  ldm_hash_rate_log

    Frequência de inserção/pesquisa de entradas na tabela hash do comparador de longa distância. Valores maiores melhoram a velocidade de compactação. Desvios muito grandes em relação ao valor padrão provavelmente resultarão em uma redução na taxa de compactação.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  content_size_flag

    Escreve o tamanho dos dados a serem compactados no cabeçalho do quadro Zstandard quando conhecido antes da compactação.

    Este sinalizador só entra em vigor nos seguintes cenários:

    - Chamando `compress()` para compactação única

    - Fornecendo todos os dados a serem compactados no quadro em uma única chamada `ZstdCompressor.compress()`, com o modo `ZstdCompressor.FLUSH_FRAME`.

    - Chamando `ZstdCompressor.set_pledged_input_size()` com a quantidade exata de dados que serão fornecidos ao compactador antes de qualquer chamada para `ZstdCompressor.compress()` para o quadro atual. `ZstdCompressor.set_pledged_input_size()` deve ser chamado para cada novo quadro.

    Todas as outras chamadas de compactação podem não escrever as informações de tamanho no cabeçalho do quadro.

    Os valores `True` ou `1` habilitam o sinalizador de tamanho de conteúdo, enquanto os valores `False` ou `0` o desabilitam.

  checksum_flag

    Uma soma de verificação de quatro bytes usando XXHash64 do conteúdo descompactado é estrita ao final de cada quadro. O código de descompactação do Zstandard verifica a soma de verificação. Se houver uma incompatibilidade, uma exceção `ZstdError` é levantada.

    Os valores `True` ou `1` habilitam a geração da soma de integridade, enquanto os valores `False` ou `0` a desabilitam.

  dict_id_flag

    Ao compactar com um `ZstdDict`, o ID do dicionário é escrito no cabeçalho do quadro.

    Os valores `True` ou `1` habilitam o armazenamento do ID de dicionário, enquanto os valores `False` ou `0` o desabilitam.

  nb_workers

    Seleciona quantas threads serão geradas para compactação em paralelo. Quando `nb_workers` > 0, habilita a compactação multithread, um valor `1` significa “modo multithread de uma thread”. Mais workers melhoram a velocidade, mas também aumentam o uso de memória e reduzem ligeiramente a taxa de compactação.

    Um valor zero desabilita multithreading.

  job_size

    Tamanho de um trabalho de compactação, em bytes. Este valor é aplicado somente quando `nb_workers` >= 1. Cada trabalho de compactação é concluído em paralelo, portanto, este valor pode impactar indiretamente o número de threads ativas.

    Um valor zero faz com que o valor seja selecionado automaticamente.

  overlap_log

    Define a quantidade de dados recarregados de trabalhos anteriores (threads) para novos trabalhos a serem usados pela janela “Look Behind” durante a compactação. Este valor só é usado quando `nb_workers` >= 1. Os valores aceitáveis variam de 0 a 9.

    > - 0 significa definir dinamicamente a quantidade de sobreposição

    > - 1 significa nenhuma sobreposição

    > - 9 significa usar o tamanho total da janela do trabalho anterior

    Cada incremento reduz pela metade/dobra o tamanho da sobreposição. “8” significa uma sobreposição de `window_size/2`, “7” significa uma sobreposição de `window_size/4`, etc.

class compression.zstd.DecompressionParameter

  Um `IntEnum` contendo as chaves de parâmetros avançados de descompactação que podem ser usadas ao descompactar dados. Os parâmetros são opcionais; qualquer parâmetro omitido terá seu valor selecionado automaticamente.

  O método `bounds()` pode ser usado em qualquer atributo para obter os valores válidos para esse parâmetro.

  Exemplo de configuração do atributo `window_log_max` para o tamanho máximo:

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

    Retorna a tupla de limites int, `(lower, upper)`, de um parâmetro de descompactação. Este método deve ser chamado no atributo cujos limites você deseja recuperar.

    Tanto o limite inferior quanto o superior são inclusivos.

  window_log_max

    O logaritmo na base dois do tamanho máximo da janela usada durante a descompactação. Isso pode ser útil para limitar a quantidade de memória usada ao descompactar. Um tamanho máximo de janela maior resulta em uma descompactação mais rápida.

    Um valor zero faz com que o valor seja selecionado automaticamente.

class compression.zstd.Strategy

  Um `IntEnum` contendo estratégias de compactação. Estratégias com números mais altos correspondem a compactações mais complexas e lentas.

  Nota

  Os valores dos atributos de `Strategy` não são necessariamente estáveis entre as versões do zstd. Apenas a ordem dos atributos é confiável. Os atributos estão listados abaixo em ordem.

  As seguintes estratégias estão disponíveis:

  fast
  dfast
  greedy
  lazy
  lazy2
  btlazy2
  btopt
  btultra
  btultra2

## Diversos

compression.zstd.get_frame_info(frame_buffer)

  Recupera um objeto `FrameInfo` contendo metadados sobre um quadro Zstandard. Os quadros contêm metadados relacionados aos dados compactados que eles armazenam.

class compression.zstd.FrameInfo

  Metadados relatados a um quadro Zstandard.

  decompressed_size

    O tamanho do conteúdo descompactado do quadro.

  dictionary_id

    Um número inteiro que representa o ID do dicionário Zstandard necessário para descompactar o quadro. `0` significa que o ID do dicionário não foi registrado no cabeçalho do quadro. Isso pode significar que um dicionário Zstandard não é necessário ou que o ID de um dicionário necessário não foi registrado.

compression.zstd.COMPRESSION_LEVEL_DEFAULT

  O nível de compactação padrão para Zstandard é: `3`.

compression.zstd.zstd_version_info

  Número da versão da biblioteca zstd em tempo de execução, representada por uma tupla de inteiros (principal, secundária, lançamento).

## Exemplos

Lendo em um arquivo compactado:

    from compression import zstd

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

Criando um arquivo compactado:

    from compression import zstd

    data = b"Inserir dados arquivo"
    with zstd.open("file.zst", "w") as f:
        f.write(data)

Compactando dados em memória:

    from compression import zstd

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

Compactação incremental:

    from compression import zstd

    comp = zstd.ZstdCompressor()
    out1 = comp.compress(b"Alguns dados\n")
    out2 = comp.compress(b"Outro pedaço de dados\n")
    out3 = comp.compress(b"Ainda mais dados\n")
    out4 = comp.flush()
    # Concatena todos os resultados parciais:
    result = b"".join([out1, out2, out3, out4])

Escrevendo dados compactados para um arquivo já aberto:

    from compression import zstd

    with open("myfile", "wb") as f:
        f.write(b"Estes dados não serão compactados\n")
        with zstd.open(f, "w") as zstf:
            zstf.write(b"Isso *vai* ser compactado\n")
        f.write(b"Não compactado\n")

Criando um arquivo compactado usando parâmetros de compactação:

    from compression import zstd

    options = {
       zstd.CompressionParameter.checksum_flag: 1
    }
    with zstd.open("file.zst", "w", options=options) as f:
        f.write(b"Se importa se eu me juntar?")