lzma
— Compression using the LZMA algorithm¶
Adicionado na versão 3.3.
Código-fonte: Lib/lzma.py
Este módulo fornece classes e funções de conveniência para compactar e descompactar dados usando o algoritmo de compactação LZMA. Também está incluída uma interface de arquivo que oferece suporte aos formatos de arquivo .xz
e legado .lzma
usados pelo utilitário xz, bem como fluxos brutos compactados.
A interface fornecida por este módulo é muito semelhante à do módulo bz2
. Observe que LZMAFile
e bz2.BZ2File
não são seguro para thread, portanto, se você precisar usar uma única instância LZMAFile
de vários threads, é necessário protegê-la com uma trava.
- exception lzma.LZMAError¶
Essa exceção é levantada quando ocorre um erro durante a compactação ou descompactação ou durante a inicialização do estado compactador/descompactador.
Lendo e escrevendo arquivos compactados¶
- lzma.open(filename, mode='rb', *, format=None, check=-1, preset=None, filters=None, encoding=None, errors=None, newline=None)¶
Abre um arquivo compactado com LZMA no modo binário ou texto, retornando um objeto arquivo.
O argumento filename pode ser um nome de arquivo real (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 qualquer um de
"r"
,"rb"
,"w"
,"wb"
,"x"
,"xb"
,"a"
ou"ab"
para modo binário, ou"rt"
,"wt"
,"xt"
, ou"at"
para o modo de texto. O padrão é"rb"
.Ao abrir um arquivo para leitura, os argumentos format e filters têm os mesmos significados que em
LZMADecompressor
. Neste caso, os argumentos check e preset não devem ser usados.Ao abrir um arquivo para escrita, os argumentos format, check, preset e filters têm os mesmos significados que em
LZMACompressor
.Para o modo binário, esta função é equivalente ao construtor
LZMAFile
:LZMAFile(filename, mode, ...)
. Nesse caso, os argumentos encoding, errors e newline não devem ser fornecidos.Para o modo texto, um objeto
LZMAFile
é criado e encapsulado em uma instânciaio.TextIOWrapper
com a codificação especificada, comportamento de tratamento de erros e final(is) de linha.Alterado na versão 3.4: Adicionado suporte para os modos
"x"
,"xb"
e"xt"
.Alterado na versão 3.6: Aceita um objeto caminho ou similar.
- class lzma.LZMAFile(filename=None, mode='r', *, format=None, check=-1, preset=None, filters=None)¶
Abre um arquivo compactado com LZMA no modo binário.
Um
LZMAFile
pode envolver um objeto arquivo já aberto, ou operar diretamente em um arquivo nomeado. O argumento filename especifica o objeto arquivo a ser encapsulado ou o nome do arquivo a ser aberto (como um objetostr
,bytes
ou caminho ou similar). Ao agrupar um objeto de arquivo existente, o arquivo agrupado não será fechado quando oLZMAFile
for fechado.O argumento mode pode ser
"r"
para leitura (padrão),"w"
para substituição,"x"
para criação exclusiva ou"a"
para anexar. Estes podem ser equivalentemente dados como"rb"
,"wb"
,"xb"
e"ab"
respectivamente.Se filename for um objeto arquivo (em vez de um nome de arquivo real), um modo de
"w"
não truncará o arquivo e será equivalente a"a"
.Ao abrir um arquivo para leitura, o arquivo de entrada pode ser a concatenação de vários fluxos compactados separados. Estes são decodificados de forma transparente como um único fluxo lógico.
Ao abrir um arquivo para leitura, os argumentos format e filters têm os mesmos significados que em
LZMADecompressor
. Neste caso, os argumentos check e preset não devem ser usados.Ao abrir um arquivo para escrita, os argumentos format, check, preset e filters têm os mesmos significados que em
LZMACompressor
.LZMAFile
supports all the members specified byio.BufferedIOBase
, except fordetach()
andtruncate()
. Iteration and thewith
statement are supported.The following method and attributes are also provided:
- 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.Adicionado na versão 3.13.
- name¶
The lzma file name. Equivalent to the
name
attribute of the underlying file object.Adicionado na versão 3.13.
Alterado na versão 3.4: Adicionado suporte para os modos
"x"
e"xb"
.Alterado na versão 3.5: O método
read()
agora aceita um argumento deNone
.Alterado na versão 3.6: Aceita um objeto caminho ou similar.
Compactando e descompactando dados na memória¶
- class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
Cria um objeto compactador, que pode ser usado para compactar dados de forma incremental.
Para uma maneira mais conveniente de compactar um único bloco de dados, consulte
compress()
.O argumento format especifica qual formato de contêiner deve ser usado. Os valores possíveis são:
FORMAT_XZ
: O formato de contêiner.xz
.Este é o formato padrão.
FORMAT_ALONE
: O formato de contêiner legado.lzma
.Este formato é mais limitado que
.xz
– ele não oferece suporte a verificações de integridade ou filtros múltiplos.
FORMAT_RAW
: Um fluxo de dados brutos, que não usa nenhum formato de contêiner.Esse especificador de formato não oferece suporte a verificações de integridade e exige que você sempre especifique uma cadeia de filtros personalizada (para compactação e descompactação). Além disso, dados compactados dessa maneira não podem ser descompactados usando
FORMAT_AUTO
(vejaLZMADecompressor
).
O argumento check especifica o tipo de verificação de integridade a ser incluída nos dados compactados. Essa verificação é usada ao descompactar, para garantir que os dados não foram corrompidos. Os valores possíveis são:
CHECK_NONE
: Sem verificação de integridade. Este é o padrão (e o único valor aceitável) paraFORMAT_ALONE
eFORMAT_RAW
.CHECK_CRC32
: Verificação de redundância cíclica de 32 bits.CHECK_CRC64
: Verificação de redundância cíclica de 64 bits. Este é o padrão paraFORMAT_XZ
.CHECK_SHA256
: Algoritmo de hash seguro de 256 bits.
Se a verificação especificada não for suportada, uma exceção
LZMAError
será levantada.As configurações de compactação podem ser especificadas como um nível de compactação predefinido (com o argumento preset) ou em detalhes como uma cadeia de filtros personalizada (com o argumento filters).
O argumento preset (se fornecido) deve ser um inteiro entre
0
e9
(inclusive), opcionalmente com OR com a constantePRESET_EXTREME
. Se nem preset nem filters forem fornecidos, o comportamento padrão é usarPRESET_DEFAULT
(nível predefinido6
). Predefinições mais altas produzem uma saída menor, mas tornam o processo de compactação mais lento.Nota
Além de consumir mais CPU, a compactação com predefinições mais altas também requer muito mais memória (e produz uma saída que precisa de mais memória para descompactar). Com a predefinição
9
por exemplo, a sobrecarga para um objetoLZMACompressor
pode chegar a 800 MiB. Por esse motivo, geralmente é melhor ficar com a predefinição padrão.O argumento filters (se fornecido) deve ser um especificador de cadeia de filtros. Veja Specifying custom filter chains para detalhes.
- compress(data)¶
Compress data (a
bytes
object), returning abytes
object containing compressed data for at least part of the input. Some of data may be buffered internally, for use in later calls tocompress()
andflush()
. The returned data should be concatenated with the output of any previous calls tocompress()
.
- class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)¶
Create a decompressor object, which can be used to decompress data incrementally.
For a more convenient way of decompressing an entire compressed stream at once, see
decompress()
.The format argument specifies the container format that should be used. The default is
FORMAT_AUTO
, which can decompress both.xz
and.lzma
files. Other possible values areFORMAT_XZ
,FORMAT_ALONE
, andFORMAT_RAW
.The memlimit argument specifies a limit (in bytes) on the amount of memory that the decompressor can use. When this argument is used, decompression will fail with an
LZMAError
if it is not possible to decompress the input within the given memory limit.The filters argument specifies the filter chain that was used to create the stream being decompressed. This argument is required if format is
FORMAT_RAW
, but should not be used for other formats. See Specifying custom filter chains for more information about filter chains.Nota
This class does not transparently handle inputs containing multiple compressed streams, unlike
decompress()
andLZMAFile
. To decompress a multi-stream input withLZMADecompressor
, you must create a new decompressor for each stream.- 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, 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 comoFalse
. Neste caso, a próxima chamada paradecompress()
pode fornecer data comob''
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 comoTrue
.A tentativa de descompactar os dados após o final do fluxo ser atingido gera um
EOFError
. Quaisquer dados encontrados após o final do fluxo são ignorados e salvos no atributounused_data
.Alterado na versão 3.5: Adicionado o parâmetro max_length.
- check¶
The ID of the integrity check used by the input stream. This may be
CHECK_UNKNOWN
until enough of the input has been decoded to determine what integrity check it uses.
- eof¶
True
se o marcador de fim de fluxo foi atingido.
- unused_data¶
Dados encontrados após o término do fluxo compactado.
Before the end of the stream is reached, this will be
b""
.
- needs_input¶
False
se o métododecompress()
puder fornecer mais dados descompactados antes de exigir uma nova entrada descompactada.Adicionado na versão 3.5.
- lzma.compress(data, format=FORMAT_XZ, check=-1, preset=None, filters=None)¶
Compress data (a
bytes
object), returning the compressed data as abytes
object.See
LZMACompressor
above for a description of the format, check, preset and filters arguments.
- lzma.decompress(data, format=FORMAT_AUTO, memlimit=None, filters=None)¶
Decompress data (a
bytes
object), returning the uncompressed data as abytes
object.If data is the concatenation of multiple distinct compressed streams, decompress all of these streams, and return the concatenation of the results.
See
LZMADecompressor
above for a description of the format, memlimit and filters arguments.
Diversos¶
- lzma.is_check_supported(check)¶
Return
True
if the given integrity check is supported on this system.CHECK_NONE
andCHECK_CRC32
are always supported.CHECK_CRC64
andCHECK_SHA256
may be unavailable if you are using a version of liblzma that was compiled with a limited feature set.
Specifying custom filter chains¶
A filter chain specifier is a sequence of dictionaries, where each dictionary
contains the ID and options for a single filter. Each dictionary must contain
the key "id"
, and may contain additional keys to specify filter-dependent
options. Valid filter IDs are as follows:
Filtro Compression:
FILTER_LZMA1
(para ser usado comFORMAT_ALONE
)FILTER_LZMA2
(para ser utilizado comFORMAT_XZ
andFORMAT_RAW
)
Delta filter:
FILTER_DELTA
Branch-Call-Jump (BCJ) filters:
FILTER_X86
FILTER_IA64
FILTER_ARM
FILTER_ARMTHUMB
FILTER_POWERPC
FILTER_SPARC
A filter chain can consist of up to 4 filters, and cannot be empty. The last filter in the chain must be a compression filter, and any other filters must be delta or BCJ filters.
Compression filters support the following options (specified as additional entries in the dictionary representing the filter):
preset
: A compression preset to use as a source of default values for options that are not specified explicitly.dict_size
: Dictionary size in bytes. This should be between 4 KiB and 1.5 GiB (inclusive).lc
: Number of literal context bits.lp
: Number of literal position bits. The sumlc + lp
must be at most 4.pb
: Number of position bits; must be at most 4.mode
:MODE_FAST
orMODE_NORMAL
.nice_len
: What should be considered a “nice length” for a match. This should be 273 or less.mf
: What match finder to use –MF_HC3
,MF_HC4
,MF_BT2
,MF_BT3
, orMF_BT4
.depth
: Maximum search depth used by match finder. 0 (default) means to select automatically based on other filter options.
The delta filter stores the differences between bytes, producing more repetitive
input for the compressor in certain circumstances. It supports one option,
dist
. This indicates the distance between bytes to be subtracted. The
default is 1, i.e. take the differences between adjacent bytes.
The BCJ filters are intended to be applied to machine code. They convert
relative branches, calls and jumps in the code to use absolute addressing, with
the aim of increasing the redundancy that can be exploited by the compressor.
These filters support one option, start_offset
. This specifies the address
that should be mapped to the beginning of the input data. The default is 0.
Exemplos¶
Reading in a compressed file:
import lzma
with lzma.open("file.xz") as f:
file_content = f.read()
Criando um arquivo comprimido:
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
f.write(data)
Compressing data in memory:
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
Compressão incremental:
import lzma
lzc = lzma.LZMACompressor()
out1 = lzc.compress(b"Some data\n")
out2 = lzc.compress(b"Another piece of data\n")
out3 = lzc.compress(b"Even more data\n")
out4 = lzc.flush()
# Concatenate all the partial results:
result = b"".join([out1, out2, out3, out4])
Writing compressed data to an already-open file:
import lzma
with open("file.xz", "wb") as f:
f.write(b"This data will not be compressed\n")
with lzma.open(f, "w") as lzf:
lzf.write(b"This *will* be compressed\n")
f.write(b"Not compressed\n")
Creating a compressed file using a custom filter chain:
import lzma
my_filters = [
{"id": lzma.FILTER_DELTA, "dist": 5},
{"id": lzma.FILTER_LZMA2, "preset": 7 | lzma.PRESET_EXTREME},
]
with lzma.open("file.xz", "w", filters=my_filters) as f:
f.write(b"blah blah blah")