Reading and writing compressed files¶

lzma.open(filename,mode='rb',*,format=None,check=-1,preset=None,filters=None,encoding=None,errors=None,newline=None)¶

Open an LZMA-compressed file in binary or text mode, returning afileobject.

Thefilename argument can be either an actual file name (given as astr,bytes orpath-like object), inwhich case the named file is opened, or it can be an existing file objectto read from or write to.

Themode argument can be any of"r","rb","w","wb","x","xb","a" or"ab" for binary mode, or"rt","wt","xt", or"at" for text mode. The default is"rb".

When opening a file for reading, theformat andfilters arguments havethe same meanings as forLZMADecompressor. In this case, thecheckandpreset arguments should not be used.

When opening a file for writing, theformat,check,preset andfilters arguments have the same meanings as forLZMACompressor.

For binary mode, this function is equivalent to theLZMAFileconstructor:LZMAFile(filename,mode,...). In this case, theencoding,errors andnewline arguments must not be provided.

For text mode, aLZMAFile object is created, and wrapped in anio.TextIOWrapper instance with the specified encoding, errorhandling behavior, and line ending(s).

在 3.4 版的變更:新增"x"、"xb" 和"xt" 模式的支援。

在 3.6 版的變更:Accepts apath-like object.

classlzma.LZMAFile(filename=None,mode='r',*,format=None,check=-1,preset=None,filters=None)¶

Open an LZMA-compressed file in binary mode.

AnLZMAFile can wrap an already-openfile object, or operatedirectly on a named file. Thefilename argument specifies either the fileobject to wrap, or the name of the file to open (as astr,bytes orpath-like object). When wrapping anexisting file object, the wrapped file will not be closed when theLZMAFile is closed.

Themode argument can be either"r" for reading (default),"w" foroverwriting,"x" for exclusive creation, or"a" for appending. Thesecan equivalently be given as"rb","wb","xb" and"ab"respectively.

Iffilename is a file object (rather than an actual file name), a mode of"w" does not truncate the file, and is instead equivalent to"a".

When opening a file for reading, the input file may be the concatenation ofmultiple separate compressed streams. These are transparently decoded as asingle logical stream.

When opening a file for reading, theformat andfilters arguments havethe same meanings as forLZMADecompressor. In this case, thecheckandpreset arguments should not be used.

When opening a file for writing, theformat,check,preset andfilters arguments have the same meanings as forLZMACompressor.

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)¶

Return buffered data without advancing the file position. At least onebyte of data will be returned, unless EOF has been reached. The exactnumber of bytes returned is unspecified (thesize argument is ignored).

備註

While callingpeek() does not change the file position oftheLZMAFile, it may change the position of the underlyingfile object (e.g. if theLZMAFile was constructed by passing afile object forfilename).

mode¶

'rb' for reading and'wb' for writing.

在 3.13 版被加入.

name¶

The lzma file name. Equivalent to thenameattribute of the underlyingfile object.

在 3.13 版被加入.

在 3.4 版的變更:新增"x" 和"xb" 模式的支援。

在 3.5 版的變更:Theread() method now accepts an argument ofNone.

在 3.6 版的變更:Accepts apath-like object.

Compressing and decompressing data in memory¶

classlzma.LZMACompressor(format=FORMAT_XZ,check=-1,preset=None,filters=None)¶

Create a compressor object, which can be used to compress data incrementally.

For a more convenient way of compressing a single chunk of data, seecompress().

Theformat argument specifies what container format should be used.Possible values are:

• FORMAT_XZ: The.xz container format.

  This is the default format.

• FORMAT_ALONE: The legacy.lzma container format.

  This format is more limited than.xz -- it does not support integritychecks or multiple filters.

• FORMAT_RAW: A raw data stream, not using any container format.

  This format specifier does not support integrity checks, and requires thatyou always specify a custom filter chain (for both compression anddecompression). Additionally, data compressed in this manner cannot bedecompressed usingFORMAT_AUTO (seeLZMADecompressor).

Thecheck argument specifies the type of integrity check to include in thecompressed data. This check is used when decompressing, to ensure that thedata has not been corrupted. Possible values are:

• CHECK_NONE: No integrity check.This is the default (and the only acceptable value) forFORMAT_ALONE andFORMAT_RAW.

• CHECK_CRC32: 32-bit Cyclic Redundancy Check.

• CHECK_CRC64: 64-bit Cyclic Redundancy Check.This is the default forFORMAT_XZ.

• CHECK_SHA256: 256-bit Secure Hash Algorithm.

If the specified check is not supported, anLZMAError is raised.

The compression settings can be specified either as a preset compressionlevel (with thepreset argument), or in detail as a custom filter chain(with thefilters argument).

Thepreset argument (if provided) should be an integer between0 and9 (inclusive), optionally OR-ed with the constantPRESET_EXTREME. If neitherpreset norfilters are given, thedefault behavior is to usePRESET_DEFAULT (preset level6).Higher presets produce smaller output, but make the compression processslower.

備註

In addition to being more CPU-intensive, compression with higher presetsalso requires much more memory (and produces output that needs more memoryto decompress). With preset9 for example, the overhead for anLZMACompressor object can be as high as 800 MiB. For this reason,it is generally best to stick with the default preset.

Thefilters argument (if provided) should be a filter chain specifier.SeeSpecifying custom filter chains for details.

compress(data)¶

Compressdata (abytes object), returning abytesobject containing compressed data for at least part of the input. Some ofdata may be buffered internally, for use in later calls tocompress() andflush(). The returned data should beconcatenated with the output of any previous calls tocompress().

flush()¶

Finish the compression process, returning abytes objectcontaining any data stored in the compressor's internal buffers.

The compressor cannot be used after this method has been called.

classlzma.LZMADecompressor(format=FORMAT_AUTO,memlimit=None,filters=None)¶

Create a decompressor object, which can be used to decompress dataincrementally.

For a more convenient way of decompressing an entire compressed stream atonce, seedecompress().

Theformat argument specifies the container format that should be used. Thedefault isFORMAT_AUTO, which can decompress both.xz and.lzma files. Other possible values areFORMAT_XZ,FORMAT_ALONE, andFORMAT_RAW.

Thememlimit argument specifies a limit (in bytes) on the amount of memorythat the decompressor can use. When this argument is used, decompression willfail with anLZMAError if it is not possible to decompress the inputwithin the given memory limit.

Thefilters argument specifies the filter chain that was used to createthe stream being decompressed. This argument is required ifformat isFORMAT_RAW, but should not be used for other formats.SeeSpecifying custom filter chains for more information about filter chains.

備註

This class does not transparently handle inputs containing multiplecompressed streams, unlikedecompress() andLZMAFile. Todecompress a multi-stream input withLZMADecompressor, you mustcreate a new decompressor for each stream.

decompress(data,max_length=-1)¶

Decompressdata (abytes-like object), returninguncompressed data as bytes. Some ofdata may be bufferedinternally, for use in later calls todecompress(). Thereturned data should be concatenated with the output of anyprevious calls todecompress().

Ifmax_length is nonnegative, returns at mostmax_lengthbytes of decompressed data. If this limit is reached and furtheroutput can be produced, theneeds_input attribute willbe set toFalse. In this case, the next call todecompress() may providedata asb'' to obtainmore of the output.

If all of the input data was decompressed and returned (eitherbecause this was less thanmax_length bytes, or becausemax_length was negative), theneeds_input attributewill be set toTrue.

Attempting to decompress data after the end of stream is reachedraises anEOFError. Any data found after the end of thestream is ignored and saved in theunused_data attribute.

在 3.5 版的變更:新增max_length 參數。

check¶

The ID of the integrity check used by the input stream. This may beCHECK_UNKNOWN until enough of the input has been decoded todetermine what integrity check it uses.

eof¶

True if the end-of-stream marker has been reached.

unused_data¶

Data found after the end of the compressed stream.

Before the end of the stream is reached, this will beb"".

needs_input¶

False if thedecompress() method can provide moredecompressed data before requiring new uncompressed input.

在 3.5 版被加入.

lzma.compress(data,format=FORMAT_XZ,check=-1,preset=None,filters=None)¶

Compressdata (abytes object), returning the compressed data as abytes object.

SeeLZMACompressor above for a description of theformat,check,preset andfilters arguments.

lzma.decompress(data,format=FORMAT_AUTO,memlimit=None,filters=None)¶

Decompressdata (abytes object), returning the uncompressed dataas abytes object.

Ifdata is the concatenation of multiple distinct compressed streams,decompress all of these streams, and return the concatenation of the results.

SeeLZMADecompressor above for a description of theformat,memlimit andfilters arguments.

Miscellaneous¶

lzma.is_check_supported(check)¶

ReturnTrue 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 areusing a version ofliblzma that was compiled with a limitedfeature set.

Specifying custom filter chains¶

A filter chain specifier is a sequence of dictionaries, where each dictionarycontains the ID and options for a single filter. Each dictionary must containthe key"id", and may contain additional keys to specify filter-dependentoptions. Valid filter IDs are as follows:

• Compression filters:

  • FILTER_LZMA1 (for use withFORMAT_ALONE)

  • FILTER_LZMA2 (for use withFORMAT_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 lastfilter in the chain must be a compression filter, and any other filters must bedelta or BCJ filters.

Compression filters support the following options (specified as additionalentries in the dictionary representing the filter):

• preset: A compression preset to use as a source of default values foroptions that are not specified explicitly.

• dict_size: Dictionary size in bytes. This should be between 4 KiB and1.5 GiB (inclusive).

• lc: Number of literal context bits.

• lp: Number of literal position bits. The sumlc+lp must be atmost 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 toselect automatically based on other filter options.

The delta filter stores the differences between bytes, producing more repetitiveinput for the compressor in certain circumstances. It supports one option,dist. This indicates the distance between bytes to be subtracted. Thedefault is 1, i.e. take the differences between adjacent bytes.

The BCJ filters are intended to be applied to machine code. They convertrelative branches, calls and jumps in the code to use absolute addressing, withthe aim of increasing the redundancy that can be exploited by the compressor.These filters support one option,start_offset. This specifies the addressthat should be mapped to the beginning of the input data. The default is 0.

範例¶

Reading in a compressed file:

importlzmawithlzma.open("file.xz")asf:file_content=f.read()

Creating a compressed file:

importlzmadata=b"Insert Data Here"withlzma.open("file.xz","w")asf:f.write(data)

Compressing data in memory:

importlzmadata_in=b"Insert Data Here"data_out=lzma.compress(data_in)

Incremental compression:

importlzmalzc=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:

importlzmawithopen("file.xz","wb")asf:f.write(b"This data will not be compressed\n")withlzma.open(f,"w")aslzf:lzf.write(b"This *will* be compressed\n")f.write(b"Not compressed\n")

Creating a compressed file using a custom filter chain:

importlzmamy_filters=[{"id":lzma.FILTER_DELTA,"dist":5},{"id":lzma.FILTER_LZMA2,"preset":7|lzma.PRESET_EXTREME},]withlzma.open("file.xz","w",filters=my_filters)asf:f.write(b"blah blah blah")