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:

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.

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.

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:

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?")