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 classeZstdFile
para leitura e escrita de arquivos compactados.As classes
ZstdCompressor
eZstdDecompressor
para (des)compactação incremental.As funções
compress()
edecompress()
para (des)compressão de uma só vez.As funções
train_dict()
efinalize_dict()
e a classeZstdDict
para treinar e gerenciar dicionários Zstandard.As classes
CompressionParameter
,DecompressionParameter
eStrategy
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 deZstdDict
a ser usada durante a descompactação. Durante a leitura, se o argumento level não for None, uma exceçãoTypeError
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 deZstdDict
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ânciaio.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 objetostr
,bytes
ou objeto caminho ou similar). Se estiver envolvendo um objeto arquivo existente, o arquivo envolvido não será fechado quando oZstdFile
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 deZstdDict
a ser usada durante a descompactação. Durante a leitura, se o argumento level não for None, uma exceçãoTypeError
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 deZstdDict
a ser usada durante a compactação.ZstdFile
oferece suporte a todos os membros especificados porio.BufferedIOBase
, excetodetach()
etruncate()
. Iteração e a instruçãowith
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).
- 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. Usebounds()
emcompression_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âmetroCompressionParameter.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çãotrain_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. Usebounds()
emcompression_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âmetroCompressionParameter.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çãotrain_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 objetobytes
vazio. Alguns dos data podem ser armazenados internamente em buffer, para uso em chamadas posteriores acompress()
eflush()
. Os dados retornados devem ser concatenados com a saída de quaisquer chamadas anteriores acompress()
.O argumento mode é um atributo
ZstdCompressor
, podendo ser definido comCONTINUE
,FLUSH_BLOCK
ouFLUSH_FRAME
.Quando todos os dados forem fornecidos ao compactador, chama o método
flush()
para finalizar o processo de compactação. Secompress()
for chamado com mode definido comoFLUSH_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 comFLUSH_BLOCK
ouFLUSH_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
sejaFalse
ou0
. Um tamanho0
significa que o quadro está vazio. Se size forNone
, 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 forFLUSH_FRAME
, umaValueError
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 paracompress()
, chamadas futuras paracompress()
ouflush()
poderão levantarZstdError
e o último bloco de dados poderá ser perdido.Depois que
flush()
oucompress()
são chamados com o modoFLUSH_FRAME
, o próximo quadro não incluirá o tamanho do quadro no cabeçalho, a menos queset_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()
ouflush()
. O valor pode serCONTINUE
,FLUSH_BLOCK
ouFLUSH_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 classeZstdFile
. Para descompactar uma entrada com múltiplos quadros, você deve usardecompress()
,ZstdFile
se estiver trabalhando com um objeto arquivo ou múltiplas instâncias deZstdDecompressor
.- 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 paradecompress()
.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 comoFalse
. Neste caso, a próxima chamada paradecompress()
pode fornecer data comob''
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 comoTrue
.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 atributounused_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étododecompress()
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
comdict_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 atributosas_digested_dict
eas_undigested_dict
podem controlar como o dicionário é carregado, passando-os como o argumentozstd_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 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árioSim. É 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¶
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 thezstd
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
forZstdDict.dict_id
is different from thedictionary_id
attribute to theget_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¶
Uma
IntEnum
contendo as chaves de parâmetros de compactação avançada que podem ser usadas ao compactar dados.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.
Exemplo de obtenção da delimitação inferior e superior de
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()¶
Retorna a tupla de limites int,
(lower, upper)
, de um parâmetro de compressão. Este método deve ser chamado no atributo cujos limites você deseja recuperar. Por exemplo, para obter os valores válidos paracompression_level
, pode-se verificar o resultado deCompressionParameter.compression_level.bounds()
.Both the lower and upper bounds are inclusive.
- 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 que20
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 compressor 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.A value of zero causes the value to be selected automatically.
- 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 compressão de estratégias <=dfast
e melhoram a velocidade de compactação de estratégias >dfast
.A value of zero causes the value to be selected automatically.
- 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égiafast
. Ele ainda é útil ao usar a estratégiadfast
, caso em que define uma tabela de sondagem secundária.A value of zero causes the value to be selected automatically.
- search_log¶
Número de tentativas de busca, como uma potência de dois. Mais tentativas resultam em uma compressão melhor e mais lenta. Este parâmetro é inútil para as estratégias
fast
edfast
.A value of zero causes the value to be selected automatically.
- 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
.A value of zero causes the value to be selected automatically.
- target_length¶
The impact of this field depends on the selected
Strategy
.Para as estratégias
btopt
,btultra
ebtultra2
, 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.A value of zero causes the value to be selected automatically.
- 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
- 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.
True
or1
enable long distance matching whileFalse
or0
disable it.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 sewindow_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.
A value of zero causes the value to be selected automatically.
- 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.
A value of zero causes the value to be selected automatically.
- 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.
A value of zero causes the value to be selected automatically.
- 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.
A value of zero causes the value to be selected automatically.
- content_size_flag¶
Escreve o tamanho dos dados a serem compactados no cabeçalho do quadro Zstandard quando conhecido antes da compactação.
This flag only takes effect under the following scenarios:
Chamando
compress()
para compactação únicaFornecendo todos os dados a serem compactados no quadro em uma única chamada
ZstdCompressor.compress()
, com o modoZstdCompressor.FLUSH_FRAME
.Chamando
ZstdCompressor.set_pledged_input_size()
com a quantidade exata de dados que serão fornecidos ao compressor antes de qualquer chamada paraZstdCompressor.compress()
para o quadro atual.ZstdCompressor.set_pledged_input_size()
deve ser chamado para cada novo quadro.
Todas as outras chamadas de compressão podem não escrever as informações de tamanho no cabeçalho do quadro.
True
or1
enable the content size flag whileFalse
or0
disable it.
- 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.True
or1
enable checksum generation whileFalse
or0
disable it.
- dict_id_flag¶
Ao compactar com um
ZstdDict
, o ID do dicionário é escrito no cabeçalho do quadro.True
or1
enable storing the dictionary ID whileFalse
or0
disable it.
- nb_workers¶
Seleciona quantas threads serão geradas para compactação em paralelo. Quando
nb_workers
> 0, habilita a compactação multithread, um valor1
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.A value of zero disables multi-threading.
- 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.A value of zero causes the value to be selected automatically.
- 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 dewindow_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?")