zstandard 0.11.1

实用方法

frame_progression()返回一个包含字节数的3元组 由当前压缩操作摄取、消耗和产生的。

memory_size()获取底层zstd的内存利用率 压缩上下文（字节）：

cctx = zstd.ZstdCompressor()
memory = cctx.memory_size()

简单的API

compress(data)压缩并返回数据作为一次性操作。：

cctx = zstd.ZstdCompressor()
compressed = cctx.compress(b'data to compress')

参数data可以是实现缓冲区协议的任何对象。

流读取器API

stream_reader(source)可用于获取符合 io.RawIOBase接口，用于将压缩输出读取为流：

with open(path, 'rb') as fh:
    cctx = zstd.ZstdCompressor()
    reader = cctx.stream_reader(fh)
    while True:
        chunk = reader.read(16384)
        if not chunk:
            break

        # Do something with compressed chunk.

实例也可以用作上下文管理器：

with open(path, 'rb') as fh:
    with cctx.stream_reader(fh) as reader:
        while True:
            chunk = reader.read(16384)
            if not chunk:
                break

            # Do something with compressed chunk.

当上下文管理器退出或^ {TT34 }被调用时，THE流关闭， 底层资源被释放，未来针对压缩的操作 流将失败。

stream_reader()的source参数可以是具有 read(size)方法或实现缓冲区协议的任何对象。

stream_reader()接受指定输入大小的size参数 溪流是。这是用来调整压缩参数的 根据源大小定制。

with open(path, 'rb') as fh:
    cctx = zstd.ZstdCompressor()
    with cctx.stream_reader(fh, size=os.stat(path).st_size) as reader:
        ...

如果source是流，则可以指定read()请求的大小 应该通过read_size参数到达该流。它默认为 zstandard.COMPRESSION_RECOMMENDED_INPUT_SIZE。：

with open(path, 'rb') as fh:
    cctx = zstd.ZstdCompressor()
    # Will perform fh.read(8192) when obtaining data to feed into the
    # compressor.
    with cctx.stream_reader(fh, read_size=8192) as reader:
        ...

stream_reader()返回的流既不可写也不可查找 （即使底层源代码是可查看的）。readline()和 readlines()未实现，因为它们对 压缩数据。tell()返回压缩字节数 到目前为止。

流式输入API

stream_writer(fh)允许您将{em1}$stream数据放入压缩器。

返回的实例实现了io.RawIOBase接口。只有方法 涉及写作的东西会有用的。

stream_writer()的参数必须有一个write(data)方法。作为 压缩数据可用，write()将使用压缩 数据作为它的论据。许多常见的python类型实现write()，包括 打开文件句柄和io.BytesIO。

write(data)方法用于将数据馈送到压缩器中。

可以调用flush([flush_mode=FLUSH_BLOCK])方法来逐出 数据保持在压缩机的内部状态，进入输出对象。这个 可能导致对输出对象的0个或多个write()调用。这种方法 接受可选的flush_mode参数来控制刷新行为。 它的值可以是任何FLUSH_*常量。

write()和flush()都返回写入 对象的write()。在许多情况下，小的投入积累不够 导致写入和write()的数据将返回0。

调用close()将流标记为已关闭和后续I/O 操作将提高ValueError（根据 io.RawIOBase）。close()还将调用基础上的close()。 流，如果存在这样的方法。

通常用法如下：

cctx = zstd.ZstdCompressor(level=10)
compressor = cctx.stream_writer(fh)

compressor.write(b'chunk 0\n')
compressor.write(b'chunk 1\n')
compressor.flush()
# Receiver will be able to decode ``chunk 0\nchunk 1\n`` at this point.
# Receiver is also expecting more data in the zstd *frame*.

compressor.write(b'chunk 2\n')
compressor.flush(zstd.FLUSH_FRAME)
# Receiver will be able to decode ``chunk 0\nchunk 1\nchunk 2``.
# Receiver is expecting no more data, as the zstd frame is closed.
# Any future calls to ``write()`` at this point will construct a new
# zstd frame.

实例可以用作上下文管理器。退出上下文管理器是 相当于调用close()，相当于调用 flush(zstd.FLUSH_FRAME)：

cctx = zstd.ZstdCompressor(level=10)
with cctx.stream_writer(fh) as compressor:
    compressor.write(b'chunk 0')
    compressor.write(b'chunk 1')
    ...

重要

如果不调用flush(FLUSH_FRAME)，则发出的数据不构成 完整的zstdframe和此数据的使用者可能会抱怨格式错误 输入。建议使用实例作为上下文管理器，以确保 frames已正确完成。

如果输入到这个流压缩程序的数据的大小是已知的， 您可以在压缩开始之前声明它：

cctx = zstd.ZstdCompressor()
with cctx.stream_writer(fh, size=data_len) as compressor:
    compressor.write(chunk0)
    compressor.write(chunk1)
    ...

声明源数据的大小允许压缩参数 调整一下。如果使用write_content_size，也会导致 写入输出数据的帧头的内容大小。

可以指定到目的地的write()块的大小：

cctx = zstd.ZstdCompressor()
with cctx.stream_writer(fh, write_size=32768) as compressor:
    ...

要查看流式压缩程序使用了多少内存：

cctx = zstd.ZstdCompressor()
with cctx.stream_writer(fh) as compressor:
    ...
    byte_size = compressor.memory_size()

到目前为止写入的字节总数通过tell()：

cctx = zstd.ZstdCompressor()
with cctx.stream_writer(fh) as compressor:
    ...
    total_written = compressor.tell()

stream_writer()接受一个write_return_read布尔参数来控制 write()的返回值。当False（默认值）时，write()返回 字节数是write()``en to the underlying object. When ``True，write()返回从输入中读取的字节数 随后写信给压缩机。True是正确的行为 对于由io.RawIOBase接口指定的write()，将成为 将来版本中的默认值。

流式输出API

read_to_iter(reader)提供了从 压缩程序作为数据块的迭代器。

cctx = zstd.ZstdCompressor()
for chunk in cctx.read_to_iter(fh):
     # Do something with emitted data.

read_to_iter()接受obj具有read(size)方法或 符合缓冲协议。

未压缩的数据通过调用^{tt37}从源获取$ 或者直接从对象中获取数据片段（在 正在使用缓冲区协议）。返回的迭代器由块组成 压缩数据。

如果通过read()从源读取，则read()将被调用，直到 它引发或返回空字节（b''）。它完全适用于 要传递的字节数少于read(size)所请求的字节数的源。

像stream_writer()，read_to_iter()也接受size参数 声明输入流的大小：

cctx = zstd.ZstdCompressor()
for chunk in cctx.read_to_iter(fh, size=some_int):
    pass

您还可以控制源和 输出块的理想大小：

cctx = zstd.ZstdCompressor()
for chunk in cctx.read_to_iter(fh, read_size=16384, write_size=8192):
    pass

与stream_writer()不同，read_to_iter()不提供直接控制 超过送入压缩机的大块。相反，块大小将 无论从中读取的对象传递什么。这些通常是 大小一致。

流复制api

copy_stream(ifh, ofh)可用于在 压缩。：

cctx = zstd.ZstdCompressor()
cctx.copy_stream(ifh, ofh)

例如，假设要压缩文件：

cctx = zstd.ZstdCompressor()
with open(input_path, 'rb') as ifh, open(output_path, 'wb') as ofh:
    cctx.copy_stream(ifh, ofh)

还可以声明源流的大小：

cctx = zstd.ZstdCompressor()
cctx.copy_stream(ifh, ofh, size=len_of_input)

您还可以指定read()和^{tt52}的块有多大$ 从流到流：

cctx = zstd.ZstdCompressor()
cctx.copy_stream(ifh, ofh, read_size=32768, write_size=16384)

流复制器返回读取和写入的2元组字节：

cctx = zstd.ZstdCompressor()
read_count, write_count = cctx.copy_stream(ifh, ofh)

压缩机API

compressobj()返回一个公开compress(data)和 flush()方法。每个返回压缩数据或空字节。

compressobj()的目的是提供与api兼容的接口 使用zlib.compressobj、bz2.BZ2Compressor等，这允许调用者 使用相同的api时交换不同的压缩程序对象。

flush()接受指示如何结束流的可选参数。 zstd.COMPRESSOBJ_FLUSH_FINISH（默认值）结束压缩流。 执行此类刷新后，compress()和flush()可以 不再被呼叫。必须调用这种类型的flush，才能结束 压缩上下文。如果不调用，返回的数据可能不完整。

flush()的zstd.COMPRESSOBJ_FLUSH_BLOCK参数将刷新 zstd块。这种类型的刷新可以执行多次。下一个 调用compress()将开始一个新的zstd块。

下面是该api的使用方法：

cctx = zstd.ZstdCompressor()
cobj = cctx.compressobj()
data = cobj.compress(b'raw input 0')
data = cobj.compress(b'raw input 1')
data = cobj.flush()

或刷新块：

cctx.zstd.ZstdCompressor()
cobj = cctx.compressobj()
data = cobj.compress(b'chunk in first block')
data = cobj.flush(zstd.COMPRESSOBJ_FLUSH_BLOCK)
data = cobj.compress(b'chunk in second block')
data = cobj.flush()

为了获得最佳性能结果，请将输入块保持在256kb以下。这样可以避免 对大型输出对象的额外分配。

可以声明将输入的数据的输入大小 压缩机：

cctx = zstd.ZstdCompressor()
cobj = cctx.compressobj(size=6)
data = cobj.compress(b'foobar')
data = cobj.flush()

分块器API

chunker(size=None, chunk_size=COMPRESSION_RECOMMENDED_OUTPUT_SIZE)返回 一种对象，可用于迭代地将数据块馈送到压缩器中 并产生大小一致的输出块。

chunker()返回的对象公开以下方法：

compress(data)

将新的输入数据输入压缩机。

flush()

刷新压缩机中当前的所有数据。

finish()

表示输入数据结束。在此之后不能压缩新数据 方法被调用。

compress()、flush()和finish()都返回 bytes保存压缩数据的实例。迭代器可能为空。呼叫者 在执行 对对象的另一个操作。

由compress()发出的所有块的长度都是chunk_size。

flush()和finish()可能返回小于 chunk_size。

下面是API的使用方法：

cctx = zstd.ZstdCompressor()
chunker = cctx.chunker(chunk_size=32768)

with open(path, 'rb') as fh:
    while True:
        in_chunk = fh.read(32768)
        if not in_chunk:
            break

        for out_chunk in chunker.compress(in_chunk):
            # Do something with output chunk of size 32768.

    for out_chunk in chunker.finish():
        # Do something with output chunks that finalize the zstd frame.

chunker()api通常是compressobj()更好的替代品。

compressobj()将在可用时发出输出数据。这将导致 stream不同大小的输出块。输出块的一致性 带chunker()的大小是mor适用于许多用途，如发送 将数据压缩到套接字。

compressobj()还可以执行额外的内存重新分配，以便 动态调整输出块的大小。自chunker()输出以来 块都是相同大小的（除了刷新或最终块），有 更少的内存分配开销。

批量压缩API

（实验性的。cffi绑定中尚不支持。）

multi_compress_to_buffer(data, [threads=0])执行多个 作为单个操作的输入。

要压缩的数据可以作为BufferWithSegmentsCollection传递，a BufferWithSegments，或包含类字节对象的列表。每个元素 将使用配置的参数单独压缩容器 在ZstdCompressor实例上。

参数threads控制要用于压缩的线程数。这个 默认值是0，这意味着使用单个线程。负值使用 计算机中的逻辑CPU数。

函数返回BufferWithSegmentsCollection。此类型表示 n个离散内存分配，每个分配包含一个或多个压缩帧。

输出数据被写入共享内存缓冲区。这意味着不像 常规python对象，对集合中any对象的引用 使共享缓冲区保持活动状态，从而使支持它的内存保持活动状态。这个可以有 对进程内存使用的不良影响。

这个函数的api和行为是实验性的，可能会改变。 已知缺陷包括：

• 如果要求使用多个线程，它总是会生成这么多线程， 即使输入太小，无法使用它们。它会自动降低 额外线程只会增加开销时的线程计数。
• 缓冲区分配策略是固定的。有空间让它充满活力， 甚至可能允许每个输入都有一个输出缓冲区，从而促进了变化 返回一个列表而不受共享内存的不利影响 缓冲器。

实用方法

memory_size()获取底层zstd解压上下文的大小， 以字节为单位。：

dctx = zstd.ZstdDecompressor()
size = dctx.memory_size()

简单的API

decompress(data)可用于解压缩整个压缩zstd 一次操作一帧。

dctx = zstd.ZstdDecompressor()
decompressed = dctx.decompress(data)

默认情况下，decompress(data)将只对使用内容写入的数据起作用 在其头中编码的大小（这是 ZstdCompressor().compress()，但对于流式压缩可能不是这样）。如果 显示没有嵌入内容大小的压缩数据，zstd.ZstdError将 被抚养成人。

如果压缩数据中没有嵌入内容大小， 可以通过指定^{tt154}来尝试解压缩$ 参数.：

dctx = zstd.ZstdDecompressor()
uncompressed = dctx.decompress(data, max_output_size=1048576)

理想情况下，max_output_size将与解压缩的输出相同 大小。

如果max_output_size太小为了保存解压后的数据， zstd.ZstdError将被筹集。

如果max_output_size大于解压缩的数据，则 输出缓冲区的大小将调整为仅使用所需的空间。

请注意，请求的max_output_size的分配将是 每次调用方法时执行。设置为非常大的值可能 会给内存分配器带来很多工作，并可能导致 ^{tt160}如果分配失败，将引发$。

重要

如果解压缩数据的确切大小未知（未显式传入 而不是存储在zstandard框架中），出于性能原因 鼓励使用流式api。

流读取器API

stream_reader(source)可用于获取符合 io.RawIOBase接口，用于将解压缩输出读取为流：

with open(path, 'rb') as fh:
    dctx = zstd.ZstdDecompressor()
    reader = dctx.stream_reader(fh)
    while True:
        chunk = reader.read(16384)
         if not chunk:
             break

         # Do something with decompressed chunk.

流还可以用作上下文管理器：

with open(path, 'rb') as fh:
    dctx = zstd.ZstdDecompressor()
    with dctx.stream_reader(fh) as reader:
        ...

当用作上下文管理器时，流将关闭，并且 当上下文管理器退出时释放资源。未来的行动 这条河会断流的。

stream_reader()的source参数可以是具有 read(size)方法或实现缓冲区协议的任何对象。

如果source是流，则可以指定read()请求的大小 应该通过read_size参数到达该流。它默认为 zstandard.DECOMPRESSION_RECOMMENDED_INPUT_SIZE。：

with open(path, 'rb') as fh:
    dctx = zstd.ZstdDecompressor()
    # Will perform fh.read(8192) when obtaining data for the decompressor.
    with dctx.stream_reader(fh, read_size=8192) as reader:
        ...

stream_reader()返回的流不可写。

由stream_reader()返回的流是部分可查看的。 绝对和相对位置（SEEK_SET和SEEK_CUR）向前 允许当前位置的。当前读取后的偏移量 不允许相对于流结尾的位置和偏移，并且 如果尝试，将引发ValueError。

tell()返回到目前为止读取的解压缩字节数。

并非所有的I/O方法都已实现。值得注意的是缺少对 readline()、readlines()和逐行迭代支持。这是 因为流操作的是二进制数据，而不是文本数据。如果你想的话 将解压缩的输出转换为文本，可以链接io.TextIOWrapper 到流：

with open(path, 'rb') as fh:
    dctx = zstd.ZstdDecompressor()
    stream_reader = dctx.stream_reader(fh)
    text_stream = io.TextIOWrapper(stream_reader, encoding='utf-8')

    for line in text_stream:
        ...

stream_reader()的read_across_frames参数控制 遇到zstdframe结尾时的读取操作行为。 当False（默认值）结束时，读取将在 遇到zstdframe。当True时，读取可能 返回跨越多个zstdframes的数据。

流式输入API

stream_writer(fh)允许您将{em1}$stream数据放入解压缩程序。

返回的实例实现了io.RawIOBase接口。只有方法 涉及写作的东西会有用的。

stream_writer()的参数通常是一个还实现 io.RawIOBase。但是任何带有write(data)方法的对象都可以工作。许多 常见的python类型符合这个接口，包括打开的文件句柄 和io.BytesIO。

行为类似于ZstdCompressor.stream_writer()：压缩数据 通过调用write(data)发送到解压缩程序并解压缩 输出通过调用其^{tt51}写入底层流$ 方法：

dctx = zstd.ZstdDecompressor()
decompressor = dctx.stream_writer(fh)

decompressor.write(compressed_data)
...

调用write()将返回写入输出的字节数 反对。不是所有的输入都会导致写入字节，所以返回值 可能是0的。

像stream_writer()压缩器一样，实例可以用作上下文 经理。然而，上下文管理器没有添加额外的特殊行为，并提供 被利用几乎没有好处。

调用close()将流标记为已关闭和后续的I/O操作 将提高ValueError（根据io.RawIOBase的记录行为）。 close()还将调用基础流上的close()，如果 方法存在。

可以指定到目的地的write()块的大小：

dctx = zstd.ZstdDecompressor()
with dctx.stream_writer(fh, write_size=16384) as decompressor:
    pass

您可以看到解压缩程序使用了多少内存：

dctx = zstd.ZstdDecompressor()
with dctx.stream_writer(fh) as decompressor:
    byte_size = decompressor.memory_size()

stream_writer()接受一个write_return_read布尔参数来控制 write()的返回值。当False（默认值）``，write() 返回write()``en to the underlying stream. When ``True的字节数，write()返回从输入读取的字节数。 True是由 io.RawIOBase接口，并将在将来的版本中成为默认值。

流式输出API

read_to_iter(fh)提供了一种机制，可以将解压缩的数据从 压缩源作为数据块的迭代器。

dctx = zstd.ZstdDecompressor()
for chunk in dctx.read_to_iter(fh):
    # Do something with original data.

read_to_iter()接受具有read(size)方法的对象，该方法将 返回压缩字节或符合缓冲区协议的对象 可以将其数据公开为字节的连续范围。

read_to_iter()返回一个迭代器，其元素是 解压缩的数据。

可以指定从源请求的read()的大小：

dctx = zstd.ZstdDecompressor()
for chunk in dctx.read_to_iter(fh, read_size=16384):
    pass

也可以跳过输入数据中的前导字节：

dctx = zstd.ZstdDecompressor()
for chunk in dctx.read_to_iter(fh, skip_bytes=1):
    pass

提示

如果源数据包含额外的 header数据。传统上，您需要创建一个切片或 memoryview要解压缩的数据。这将创造 头顶上。将偏移量传递到这个api中更有效。

类似于ZstdCompressor.read_to_iter()，迭代器的使用者 控制何时解压缩数据。如果迭代器没有被使用， 减压暂停。

当向read_to_iter()传递符合缓冲区协议的对象时， 这种行为可能类似于简单的解压 使用API。但是，当解压大小未知时，此api可以工作。 此外，如果输入大量的数据，解压器就会成批工作 而不是执行单个操作。

流复制api

copy_stream(ifh, ofh)可用于在 正在执行解压缩。：

dctx = zstd.ZstdDecompressor()
dctx.copy_stream(ifh, ofh)

例如，将一个文件解压缩到另一个文件：

dctx = zstd.ZstdDecompressor()
with open(input_path, 'rb') as ifh, open(output_path, 'wb') as ofh:
    dctx.copy_stream(ifh, ofh)

从流到流的块大小为read()和write()。 可以指定：

dctx = zstd.ZstdDecompressor()
dctx.copy_stream(ifh, ofh, read_size=8192, write_size=16384)

减压器API

decompressobj()返回一个公开^{tt150}的对象$ 方法。压缩的数据块被输入到decompress(data)和 返回未压缩的输出（或空字节）。后续输出 需要连接调用才能重新组合完整的解压缩字节 顺序。

decompressobj()的目的是提供与api兼容的接口 使用zlib.decompressobj和bz2.BZ2Decompressor。这允许呼叫者 在使用相同的api时交换不同的解压缩程序对象。

每个对象都是一次性的：一旦输入帧被解码，decompress() 不能再叫了。

下面是该api的使用方法：

dctx = zstd.ZstdDecompressor()
dobj = dctx.decompressobj()
data = dobj.decompress(compressed_chunk_0)
data = dobj.decompress(compressed_chunk_1)

默认情况下，对decompress()的调用以大小块的形式写入输出数据 DECOMPRESSION_RECOMMENDED_OUTPUT_SIZE。这些块被连接起来 在被传回给来电者之前。可以定义 这些临时块通过将write_size传递给decompressobj()：

dctx = zstd.ZstdDecompressor()
dobj = dctx.decompressobj(write_size=1048576)

注意

因为对decompress()的调用可能需要执行多个 内存（重新）分配，此流解压缩API不是 与其他api一样高效。

为了与标准库api兼容，实例公开了 flush([length=None])方法。这个方法没有操作，没有意义 副作用，可以随时打电话。

批量解压缩API

（实验性的。cffi绑定中尚不支持。）

multi_decompress_to_buffer()执行多个 将帧作为单个操作并返回BufferWithSegmentsCollection 包含所有输入的解压缩数据。

压缩帧可以作为BufferWithSegments传递给函数， 一个BufferWithSegmentsCollection，或包含 符合缓冲协议。为了获得最佳性能，请通过 BufferWithSegmentsCollection或aBufferWithSegments，作为 将对该类型执行最小的输入验证。如果卡利天然气来源 python（与c相反），构造其中一个实例可以添加 开销取消列表验证的性能开销 输入。

dctx = zstd.ZstdDecompressor()
results = dctx.multi_decompress_to_buffer([b'...', b'...'])

每个帧的解压缩大小必须是可发现的。它可以是 嵌入到zstd框架（write_content_size=True参数中 ZstdCompressor）或通过decompressed_sizes参数传入。

decompressed_sizes参数是符合缓冲区的对象 在机器的 定义每个帧的解压缩大小的本机格式。如果这个论点 通过后，它可以避免扫描每个帧的解压缩大小。 在某些情况下，此帧扫描会增加明显的开销。

frames = [...]
sizes = struct.pack('=QQQQ', len0, len1, len2, len3)

dctx = zstd.ZstdDecompressor()
results = dctx.multi_decompress_to_buffer(frames, decompressed_sizes=sizes)

参数threads控制要执行的线程数 减压手术。默认值（0）或值1表示 用一根线。负值使用 机器。

注意

可以通过以下方法将mmap.mmap()实例传递到此函数 用BufferWithSegments实例包装它（它将定义 内存映射区域内的帧偏移）。

这个函数在逻辑上等价于执行dctx.decompress() 在每个输入帧上并返回结果。

此函数用于快速执行多个帧的解压缩 尽可能少的开销。因为减压是 作为单个操作执行，因为解压缩的输出存储在 单个缓冲区、额外内存分配、python对象和python函数 避免打电话。这非常适合打电话的人预先知道 它们需要访问多个帧的数据，例如delta chains是 被利用。

目前，实现总是在请求时生成多个线程， 即使工作量很小。在未来，它会更聪明 当 要做的工作很小。

前缀字典链解压

decompress_content_dict_chain(frames)对 使用链式prefix字典压缩生成的zstd帧。如此 通过压缩离散输入生成帧列表，其中 非初始输入用prefix字典压缩，字典由 上一个输入的内容。

例如，假设您有以下输入：

inputs = [b'input 1', b'input 2', b'input 3']

zstd帧链包括：

1. b'input 1'在独立/离散模式下压缩
2. b'input 2'使用b'input 1'作为前缀压缩字典
3. b'input 3'使用b'input 2'作为前缀字典进行压缩

每个zstd帧必须写入内容大小。

以下python代码可用于生成前缀字典链：

def make_chain(inputs):
    frames = []

    # First frame is compressed in standalone/discrete mode.
    zctx = zstd.ZstdCompressor()
    frames.append(zctx.compress(inputs[0]))

    # Subsequent frames use the previous fulltext as a prefix dictionary
    for i, raw in enumerate(inputs[1:]):
        dict_data = zstd.ZstdCompressionDict(
            inputs[i], dict_type=zstd.DICT_TYPE_RAWCONTENT)
        zctx = zstd.ZstdCompressor(dict_data=dict_data)
        frames.append(zctx.compress(raw))

    return frames

decompress_content_dict_chain()返回上一个的未压缩数据 输入链中的元素。

注意

可以实现前缀字典链解压 在其他api之上。但是，这个功能可能更快- 特别是对于长输入链-因为它避免了实例化的开销 以及在c和python之间传递中间对象。

注意

这些线程是在c层创建的，不是python线程。所以他们 在gil之外工作。因此，CPU可以使多个核心饱和 来自python。

注意

当预计算字典时，压缩参数用于 预计算字典覆盖一些压缩参数 指定为ZstdCompressor.__init__。

培训词典

除非使用prefix字典，否则字典数据由training生成。 现有数据：

dict_data = zstd.train_dictionary(size, samples)

这将获取目标字典大小和字节实例列表，并创建和 返回ZstdCompressionDict。

字典训练机制称为cover。更多的细节是 本文提供了相对lempel-ziv的有效构造 词典（作者：廖、佩特里、莫法特、威尔斯）。

cover算法使用参数k` and ``d。这些是 段大小和dmer大小。返回的词典 此函数创建的实例具有k和d属性 包含这些参数的值。如果a ZstdCompressionDict 由原始字节数据（co只有内容的字典）。 k和d属性将是0。

覆盖算法的段和dmer大小参数可以是 手动指定或train_dictionary()可以尝试多个值 选择最好的一个，其中best表示最小的压缩数据大小。 稍后的模式称为optimization模式。

如果没有k，d，steps，threads，level，notifications， 或者dict_id（基本上是来自底层^{tt289}的任何内容$ 结构）已定义，optimization模式与默认参数一起使用 价值观。

如果定义了steps或threads，则优化模式启用 对这些参数有明确的控制。指定threads=0或 threads=1可用于参与优化模式，如果有其他参数 未定义。

否则，非optimization模式将与指定的参数一起使用。

此函数接受以下参数：

听写大小

要生成的字典的目标大小（字节）。

样本

保存字典训练样本的字节列表。

k

用于覆盖定义段大小的算法的参数。合理的范围 是[162048+]。

d

用于覆盖定义dmer大小的算法的参数。合理的范围是 [6，16]。d必须小于或等于k。

指令ID

生成字典的整数字典ID。默认值为0，它使用 随机值。

步骤

尝试参数时要执行的步骤数k值 变化。

线程

尝试参数变化时要使用的线程数。默认值为0， 意思是用一根线。负值可以指定为 尽可能多地使用检测到的逻辑CPU。

水平

尝试参数变化时的整数目标压缩级别。

通知

控制将信息消息写入stderr。0（在 默认）表示不写任何内容。1写入错误。2写入 进展信息。3写入更多详细信息。并且4写入所有信息。

带段缓冲区

类型BufferWithSegments表示包含n的内存缓冲区 已知长度（段）的离散项。基本上是固定尺寸的 内存地址和一个由2个元组组成的数组(offset, length)64位 定义每个字节偏移量和长度的无符号本机尾数整数 缓冲区内的段。

实例的行为类似于容器。

len()返回实例中的段数。

o[index]或__getitem__获得表示 备份缓冲区中的单个段。返回对象引用的 （不是拷贝）内存。这意味着迭代所有对象不会复制 缓冲区中的数据。

.size属性包含备份的总大小（字节） 缓冲区。

实例符合缓冲区协议。所以对备份字节的引用 可以通过memoryview(o)获得。备份字节的copy也可以 通过.tobytes()获得。

.segments属性公开了的(offset, length)数组 缓冲区内的段。它是一个BufferSegments类型。

缓冲段

类型BufferSegment表示BufferWithSegments中的段。 它本质上是对BufferWithSegments中n个字节的引用。

len()返回段的长度（字节）。

.offset包含父段中此段的字节偏移量BufferWithSegments实例。

对象符合缓冲区协议。.tobytes()可以调用 获取带有备份字节副本的bytes实例。

缓冲段

此类型表示定义段的(offset, length)整数数组 在BufferWithSegments内。

数组成员是使用主机/本机位顺序的64位无符号整数。

实例符合缓冲区协议。

带分段采集的缓冲区

类型BufferWithSegmentsCollection表示虚拟跨越视图 多个BufferWithSegments实例的。

实例由1个或多个BufferWithSegments实例构造。这个 结果对象的行为类似于其成员是 每个BufferWithSegments内的段。

len()返回所有^{tt138}中的段数$ 实例。

o[index]和__getitem__(index)返回位于 这个偏移量就好像所有的BufferWithSegments实例都是一个 实体。

如果对象由2BufferWithSegments个实例组成，则 第一个有2个段，第二个有3个段，然后b[0] 以及第一个对象中的b[1]访问段和b[2]，b[3]， 和b[4]从第二个访问段。