lzma —使用 LZMA 算法压缩
版本 3.3 中的新Function。
源代码: Lib/lzma.py
该模块提供了用于使用 LZMA 压缩算法压缩和解压缩数据的类和便利Function。还包括一个文件界面,支持 xz Util 使用的.xz
和旧版.lzma
文件格式,以及原始压缩流。
该模块提供的接口与bz2模块的接口非常相似。但是,请注意LZMAFile是不是线程安全的,与bz2.BZ2File不同,因此,如果您需要使用多个线程中的单个LZMAFile实例,则必须使用锁来保护它。
- exception
lzma.
LZMAError
- 在压缩或解压缩期间或初始化压缩器/解压缩器状态时发生错误时,会引发此异常。
读写 zipfile
lzma.
open
(* filename , mode =“ rb” ,**,* format = None , check = -1 , preset = None , filters = None , encoding = None *, * errors = None , newline = None *)- 以二进制或文本模式打开 LZMAzipfile,返回file object。
-
filename *参数可以是实际的文件名(以str,bytes或path-like对象的形式提供),在这种情况下,已打开命名文件,也可以是要读取或写入的现有文件对象。
-
mode *参数对于二进制模式可以是
"r"
,"rb"
,"w"
,"wb"
,"x"
,"xb"
,"a"
或"ab"
之一,对于文本模式则可以是"rt"
,"wt"
,"xt"
或"at"
。默认值为"rb"
。
当打开文件进行读取时,* format 和 filters 参数的含义与LZMADecompressor相同。在这种情况下,不应使用 check 和 preset *参数。
打开文件进行写入时,* format , check , preset 和 filters *参数的含义与LZMACompressor相同。
对于二进制模式,此函数等效于LZMAFile构造函数:LZMAFile(filename, mode, ...)
。在这种情况下,不能提供* encoding , errors 和 newline *参数。
对于文本模式,将创建一个LZMAFile对象,并将其包装在具有指定编码,错误处理行为和行尾的io.TextIOWrapper实例中。
在版本 3.4 中进行了更改:添加了对"x"
,"xb"
和"xt"
模式的支持。
在版本 3.6 中更改:接受path-like object。
-
- class *
lzma.
LZMAFile
(* filename = None , mode =“ r” ,**,* format = None , check = -1 , preset = None , filters = None *)
- 以二进制模式打开 LZMAzipfile。
- class *
LZMAFile可以包装已打开的file object,或直接对命名文件进行操作。 * filename *参数指定要包装的文件对象或要打开的文件的名称(作为str,bytes或path-like对象)。打包现有文件对象时,关闭LZMAFile时不会关闭打包的文件。
- mode *参数可以是
"r"
(用于读取)(默认值),"w"
(用于覆盖),"x"
(用于独占创建)或"a"
(用于附加)。可以等效地分别将它们指定为"rb"
,"wb"
,"xb"
和"ab"
。
如果* filename *是文件对象(而不是实际的文件名),则模式"w"
不会截断该文件,而是等效于"a"
。
当打开文件进行读取时,Importing 文件可能是多个单独的压缩流的串联。这些被透明解码为单个逻辑流。
当打开文件进行读取时,* format 和 filters 参数的含义与LZMADecompressor相同。在这种情况下,不应使用 check 和 preset *参数。
打开文件进行写入时,* format , check , preset 和 filters *参数的含义与LZMACompressor相同。
LZMAFile支持io.BufferedIOBase指定的所有成员,但detach()
和truncate()
除外。支持迭代和with语句。
还提供了以下方法:
peek
(* size = -1 *)- 返回缓冲的数据而无需提前文件位置。除非已达到 EOF,否则将至少返回一个字节的数据。未指定返回的确切字节数(忽略* size *参数)。
在版本 3.4 中进行了更改:添加了对"x"
和"xb"
模式的支持。
在版本 3.5 中进行了更改:read()方法现在接受参数None
。
在版本 3.6 中更改:接受path-like object。
压缩和解压缩内存中的数据
-
- class *
lzma.
LZMACompressor
(* format = FORMAT_XZ , check = -1 , preset = None , filters = None *)
- 创建一个压缩器对象,该对象可用于增量压缩数据。
- class *
有关压缩单个数据块的更便捷方法,请参见compress()。
- format *参数指定应使用的容器格式。可能的值为:
-
-
FORMAT_XZ
:.xz
容器格式。- 这是默认格式。
-
-
-
FORMAT_ALONE
:旧版.lzma
容器格式。- 此格式比
.xz
受更多限制–它不支持完整性检查或多个过滤器。
- 此格式比
-
-
-
FORMAT_RAW
:未使用任何容器格式的原始数据流。- 该格式说明符不支持完整性检查,并且要求您始终指定一个自定义过滤器链(用于压缩和解压缩)。此外,以这种方式压缩的数据无法使用
FORMAT_AUTO
解压缩(请参阅LZMADecompressor)。
- 该格式说明符不支持完整性检查,并且要求您始终指定一个自定义过滤器链(用于压缩和解压缩)。此外,以这种方式压缩的数据无法使用
-
- check *参数指定要包含在压缩数据中的完整性检查的类型。解压缩时使用此检查,以确保数据未损坏。可能的值为:
-
CHECK_NONE
:无完整性检查。这是FORMAT_ALONE
和FORMAT_RAW
的默认值(也是唯一可接受的值)。 -
CHECK_CRC32
:32 位循环冗余校验。 -
CHECK_CRC64
:64 位循环冗余校验。这是FORMAT_XZ
的默认设置。 -
CHECK_SHA256
:256 位安全哈希算法。
如果不支持指定的检查,则引发LZMAError。
压缩设置可以指定为预设压缩级别(使用* preset 参数),也可以指定为自定义过滤器链(使用 filters *参数)。
- preset 参数(如果提供)应该是
0
和9
(包括)之间的整数,可以选择与常量PRESET_EXTREME
进行或运算。如果既未提供 preset 也未提供 filters *,则默认行为是使用PRESET_DEFAULT
(预设级别6
)。较高的预设产生较小的输出,但会使压缩过程变慢。
Note
除了占用更多的 CPU 资源外,使用更高的预设进行压缩还需要更多的内存(并且产生需要更多内存进行解压缩的输出)。例如,使用预设9
时,LZMACompressor对象的开销可能高达 800 MiB。因此,通常最好保留默认预设。
- filters *参数(如果提供)应为过滤器链说明符。有关详情,请参见指定自定义过滤器链。
-
compress
(* data *)- 压缩* data (一个bytes对象),返回一个bytes对象,其中包含至少一部分 Importing 的压缩数据。一些 data *可以在内部进行缓冲,以供以后调用compress()和flush()时使用。返回的数据应与对compress()的任何先前调用的输出连接在一起。
-
flush
( )- 完成压缩过程,返回一个bytes对象,该对象包含压缩器内部缓冲区中存储的所有数据。
调用此方法后,无法使用压缩机。
-
- class *
lzma.
LZMADecompressor
(* format = FORMAT_AUTO , memlimit = None , filters = None *)
- 创建一个解压缩器对象,该对象可用于增量解压缩数据。
- class *
有关一次更方便地一次解压缩整个压缩流的方法,请参见decompress()。
-
format *参数指定应使用的容器格式。默认值为
FORMAT_AUTO
,可以解压缩.xz
和.lzma
文件。其他可能的值为FORMAT_XZ
,FORMAT_ALONE
和FORMAT_RAW
。 -
memlimit *参数指定对解压缩器可以使用的内存量的限制(以字节为单位)。使用此参数时,如果无法在给定的内存限制内对 Importing 进行解压缩,则解压缩将失败并显示LZMAError。
-
filters 参数指定用于创建要解压缩的流的过滤器链。如果 format *为
FORMAT_RAW
,则此参数是必需的,但不应用于其他格式。有关过滤器链的更多信息,请参见指定自定义过滤器链。
Note
与decompress()和LZMAFile不同,此类不会透明地处理包含多个压缩流的 Importing。要使用LZMADecompressor解压缩多流 Importing,必须为每个流创建一个新的解压缩器。
decompress
(* data , max_length = -1 *)- 解压缩 data (bytes-like object),以字节为单位返回未压缩的数据。某些 data *可能会在内部进行缓冲,以用于以后对decompress()的调用。返回的数据应与对decompress()的任何先前调用的输出连接在一起。
如果* max_length 为非负数,则最多返回 max_length 个字节的解压缩数据。如果达到此限制并可以产生进一步的输出,则needs_input属性将设置为False
。在这种情况下,对decompress()的下一次调用可以提供 data *作为b''
以获得更多的输出。
如果所有 Importing 数据都已解压缩并返回(或者因为这小于* max_length 个字节,或者因为 max_length *为负数),则needs_input属性将设置为True
。
在达到流的末尾后try解压缩数据会引发 EOFError。流结束后找到的所有数据将被忽略并保存在unused_data属性中。
在版本 3.5 中进行了更改:添加了* max_length *参数。
-
check
- Importing 流使用的完整性检查的 ID。这可能是
CHECK_UNKNOWN
,直到已对足够多的 Importing 进行解码以确定其使用的完整性检查为止。
- Importing 流使用的完整性检查的 ID。这可能是
-
eof
True
如果已到达流结束标记。
-
unused_data
- 在压缩流结束后找到数据。
在到达流的末尾之前,该值为b""
。
needs_input
False
(如果decompress()方法可以在需要新的未压缩 Importing 之前提供更多解压缩的数据)。
3.5 版中的新Function。
lzma.
compress
(* data , format = FORMAT_XZ , check = -1 , preset = None , filters = None *)
请参阅上面的LZMACompressor以获取* format , check , preset 和 filters *参数的描述。
lzma.
decompress
(* data , format = FORMAT_AUTO , memlimit = None , filters = None *)
如果* data *是多个不同压缩流的串联,请解压缩所有这些流,然后返回结果的串联。
有关* format , memlimit 和 filters *参数的描述,请参见上面的LZMADecompressor。
Miscellaneous
lzma.
is_check_supported
(* check *)- 如果此系统支持给定的完整性检查,则返回
True
。
- 如果此系统支持给定的完整性检查,则返回
始终支持CHECK_NONE
和CHECK_CRC32
。如果您使用的 liblzma 版本是使用有限Function集编译的,则CHECK_CRC64
和CHECK_SHA256
可能不可用。
指定自定义过滤器链
过滤器链说明符是词典的序列,其中每个字典都包含单个过滤器的 ID 和选项。每个字典必须包含键"id"
,并且可以包含其他键以指定依赖于过滤器的选项。有效的过滤器 ID 如下:
-
-
Compression filters:
-
FILTER_LZMA1
(用于FORMAT_ALONE
)
-
FILTER_LZMA2
(用于FORMAT_XZ
和FORMAT_RAW
)
-
-
-
Delta filter:
-
FILTER_DELTA
-
-
-
分支呼叫跳跃(BCJ)过滤器:
-
FILTER_X86
-
FILTER_IA64
-
FILTER_ARM
-
FILTER_ARMTHUMB
-
FILTER_POWERPC
-
FILTER_SPARC
-
一个过滤器链最多可以包含 4 个过滤器,并且不能为空。链中的最后一个过滤器必须是压缩过滤器,其他任何过滤器都必须是 delta 或 BCJ 过滤器。
压缩过滤器支持以下选项(在表示过滤器的字典中指定为其他条目):
Note
-
preset
:压缩预设,用作未明确指定的选项的默认值。 -
dict_size
:字典大小(以字节为单位)。该值应介于 4 KiB 和 1.5 GiB(含)之间。 -
lc
:Literals 上下文位数。 -
lp
:Literals 位置位数。总数lc + lp
必须最大为 4. -
pb
:位置位数;最多为 4. -
mode
:MODE_FAST
或MODE_NORMAL
。 -
nice_len
:应将其视为 match 的“不错的长度”。不应超过 273. -
mf
:要使用的匹配查找器–MF_HC3
,MF_HC4
,MF_BT2
,MF_BT3
或MF_BT4
。 -
depth
:匹配查找器使用的最大搜索深度。 0(默认)表示根据其他过滤器选项自动选择。
增量过滤器存储字节之间的差异,在某些情况下为压缩器产生更多重复的 Importing。它支持一个选项dist
。这表明要减去的字节之间的距离。默认值为 1,即取相邻字节之间的差。
BCJ 过滤器旨在应用于机器代码。它们转换代码中的相关分支,调用和跳转以使用绝对寻址,目的是增加压缩程序可以利用的冗余。这些过滤器支持一个选项start_offset
。这指定了应该 Map 到 Importing 数据开头的地址。默认值为 0.
Examples
读取 zipfile:
import lzma
with lzma.open("file.xz") as f:
file_content = f.read()
创建一个 zipfile:
import lzma
data = b"Insert Data Here"
with lzma.open("file.xz", "w") as f:
f.write(data)
压缩内存中的数据:
import lzma
data_in = b"Insert Data Here"
data_out = lzma.compress(data_in)
Incremental compression:
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])
将压缩数据写入已经打开的文件:
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")
使用自定义过滤器链创建 zipfile:
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")