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 *参数可以是实际的文件名(以strbytespath-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。

LZMAFile可以包装已打开的file object,或直接对命名文件进行操作。 * filename *参数指定要包装的文件对象或要打开的文件的名称(作为strbytespath-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 *参数)。

Note

虽然调用peek()不会更改LZMAFile的文件位置,但可能会更改基础文件对象的位置(例如LZMAFile是pass为* filename *传递文件对象构造的)。

在版本 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 *)
    • 创建一个压缩器对象,该对象可用于增量压缩数据。

有关压缩单个数据块的更便捷方法,请参见compress()

  • format *参数指定应使用的容器格式。可能的值为:
    • FORMAT_XZ.xz容器格式。

      • 这是默认格式。
    • FORMAT_ALONE:旧版.lzma容器格式。

      • 此格式比.xz受更多限制–它不支持完整性检查或多个过滤器。
    • FORMAT_RAW:未使用任何容器格式的原始数据流。

      • 该格式说明符不支持完整性检查,并且要求您始终指定一个自定义过滤器链(用于压缩和解压缩)。此外,以这种方式压缩的数据无法使用FORMAT_AUTO解压缩(请参阅LZMADecompressor)。
  • check *参数指定要包含在压缩数据中的完整性检查的类型。解压缩时使用此检查,以确保数据未损坏。可能的值为:
  • CHECK_NONE:无完整性检查。这是FORMAT_ALONEFORMAT_RAW的默认值(也是唯一可接受的值)。

  • CHECK_CRC32:32 位循环冗余校验。

  • CHECK_CRC64:64 位循环冗余校验。这是FORMAT_XZ的默认设置。

  • CHECK_SHA256:256 位安全哈希算法。

如果不支持指定的检查,则引发LZMAError

压缩设置可以指定为预设压缩级别(使用* preset 参数),也可以指定为自定义过滤器链(使用 filters *参数)。

  • preset 参数(如果提供)应该是09(包括)之间的整数,可以选择与常量PRESET_EXTREME进行或运算。如果既未提供 preset 也未提供 filters *,则默认行为是使用PRESET_DEFAULT(预设级别6)。较高的预设产生较小的输出,但会使压缩过程变慢。

Note

除了占用更多的 CPU 资源外,使用更高的预设进行压缩还需要更多的内存(并且产生需要更多内存进行解压缩的输出)。例如,使用预设9时,LZMACompressor对象的开销可能高达 800 MiB。因此,通常最好保留默认预设。

  • compress(* data *)

    • 压缩* data (一个bytes对象),返回一个bytes对象,其中包含至少一部分 Importing 的压缩数据。一些 data *可以在内部进行缓冲,以供以后调用compress()flush()时使用。返回的数据应与对compress()的任何先前调用的输出连接在一起。
  • flush ( )

    • 完成压缩过程,返回一个bytes对象,该对象包含压缩器内部缓冲区中存储的所有数据。

调用此方法后,无法使用压缩机。

    • class * lzma. LZMADecompressor(* format = FORMAT_AUTO memlimit = None filters = None *)
    • 创建一个解压缩器对象,该对象可用于增量解压缩数据。

有关一次更方便地一次解压缩整个压缩流的方法,请参见decompress()

  • format *参数指定应使用的容器格式。默认值为FORMAT_AUTO,可以解压缩.xz.lzma文件。其他可能的值为FORMAT_XZFORMAT_ALONEFORMAT_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 进行解码以确定其使用的完整性检查为止。
  • 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 *)
    • Compress * data *(bytes对象),将压缩后的数据作为bytes对象返回。

请参阅上面的LZMACompressor以获取* format check preset filters *参数的描述。

  • lzma. decompress(* data format = FORMAT_AUTO memlimit = None filters = None *)
    • 解压缩 data(一个bytes对象),将未压缩的数据作为bytes对象返回。

如果* data *是多个不同压缩流的串联,请解压缩所有这些流,然后返回结果的串联。

有关* format memlimit filters *参数的描述,请参见上面的LZMADecompressor

Miscellaneous

  • lzma. is_check_supported(* check *)
    • 如果此系统支持给定的完整性检查,则返回True

始终支持CHECK_NONECHECK_CRC32。如果您使用的 liblzma 版本是使用有限Function集编译的,则CHECK_CRC64CHECK_SHA256可能不可用。

指定自定义过滤器链

过滤器链说明符是词典的序列,其中每个字典都包含单个过滤器的 ID 和选项。每个字典必须包含键"id",并且可以包含其他键以指定依赖于过滤器的选项。有效的过滤器 ID 如下:

    • Compression filters:

      • FILTER_LZMA1(用于FORMAT_ALONE)
    • FILTER_LZMA2(用于FORMAT_XZFORMAT_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.

  • modeMODE_FASTMODE_NORMAL

  • nice_len:应将其视为 match 的“不错的长度”。不应超过 273.

  • mf:要使用的匹配查找器– MF_HC3MF_HC4MF_BT2MF_BT3MF_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")