lzma — LZMA 알고리즘을 사용한 압축

버전 3.3에 추가.

소스 코드: Lib/lzma.py

이 모듈은 LZMA 압축 알고리즘을 사용하여 데이터를 압축 및 압축 해제하기 위한 클래스와 편의 함수를 제공합니다. 또한 xz 유틸리티에서 사용되는 .xz와 레거시 .lzma 파일 형식뿐만 아니라 원시 압축 스트림을 지원하는 파일 인터페이스도 포함되어 있습니다.

이 모듈에서 제공하는 인터페이스는 bz2 모듈의 인터페이스와 매우 유사합니다. 그러나, LZMAFile은 bz2.BZ2File과 달리 스레드 안전하지 않아서, 여러 스레드에서 단일 LZMAFile 인스턴스를 사용해야 하면 록으로 보호해야 합니다.

exception lzma.LZMAError

이 예외는 압축이나 압축 해제 중, 또는 압축기/압축 해제기 상태를 초기화하는 동안 에러가 발생할 때 발생합니다.

압축 파일 읽기와 쓰기

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

바이너리나 텍스트 모드에서 LZMA 압축 파일을 열고, 파일 객체를 반환합니다.

filename 인자는 실제 파일 이름(str, bytes 또는 경로류 객체로 제공됩니다)일 수 있고, 이때는 명명된 파일이 열립니다. 또는 읽거나 쓸 기존 파일 객체일 수 있습니다.

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에서 변경: 경로류 객체를 허용합니다.

class lzma.LZMAFile(filename=None, mode="r", *, format=None, check=-1, preset=None, filters=None)

바이너리 모드로 LZMA 압축 파일을 엽니다.

LZMAFile은 이미 열려있는 파일 객체를 래핑하거나, 명명된 파일에 직접 작용할 수 있습니다. filename 인자는 래핑할 파일 객체나 열 파일의 이름(str, bytes 또는 경로류 객체로)을 지정합니다. 기존 파일 객체를 래핑할 때, 래핑 된 파일은 LZMAFile이 닫힐 때 닫히지 않습니다.

mode 인자는 읽기 위한 "r" (기본값), 덮어쓰기 위한 "w", 배타적 생성을 위한 "x" 또는 덧붙이기를 위한 "a" 일 수 있습니다. 이들은 각각 "rb", "wb", "xb" 및 "ab"로 동등하게 제공될 수 있습니다.

filename이 (실제 파일 이름이 아닌) 파일 객체이면, "w" 모드는 파일을 자르지 않으며, 대신 "a"와 동등합니다.

읽기 위해 파일을 열 때, 입력 파일은 여러 개의 개별 압축 스트림을 연결한 것일 수 있습니다. 이들은 단일 논리 스트림으로 투명하게 디코딩됩니다.

파일을 읽기 위해 열 때, format과 filters 인자는 LZMADecompressor와 같은 의미입니다. 이 경우, check과 preset 인자를 사용하지 않아야 합니다.

파일을 쓰기 위해 열 때, format, check, preset 및 filters 인자는 LZMACompressor와 같은 의미입니다.

LZMAFile은 detach()와 truncate()를 제외하고, io.BufferedIOBase 가 지정하는 모든 멤버를 지원합니다. 이터레이션과 with 문이 지원됩니다.

다음과 같은 메서드도 제공됩니다:

peek(size=-1)

파일 위치를 진행하지 않고 버퍼링 된 데이터를 반환합니다. EOF에 도달하지 않았으면, 최소 1바이트의 데이터가 반환됩니다. 반환되는 정확한 바이트 수는 지정되지 않습니다 (size 인자는 무시됩니다).

참고

peek()를 호출해도 LZMAFile의 파일 위치는 변경되지 않지만, 하부 파일 객체의 위치는 변경될 수 있습니다 (예를 들어 LZMAFile이 filename으로 파일 객체를 전달하여 생성되었을 때).

버전 3.4에서 변경: "x"와 "xb" 모드에 대한 지원이 추가되었습니다.

버전 3.5에서 변경: read() 메서드는 이제 None 인자를 허용합니다.

버전 3.6에서 변경: 경로류 객체를 허용합니다.

메모리에서의 데이터 압축과 압축 해제

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_ALONE과 FORMAT_RAW에 대한 기본값(그리고 유일하게 허용된 값)입니다.

  • CHECK_CRC32: 32비트 순환 중복 검사(Cyclic Redundancy Check).

  • CHECK_CRC64: 64비트 순환 중복 검사(Cyclic Redundancy Check). 이것이 FORMAT_XZ의 기본값입니다.

  • CHECK_SHA256: 256비트 보안 해시 알고리즘(Secure Hash Algorithm).

지정된 검사가 지원되지 않으면, LZMAError가 발생합니다.

압축 설정은 사전 설정 압축 수준(preset 인자 사용), 또는 사용자 정의 필터 체인(filters 인자 사용)으로 지정할 수 있습니다.

preset 인자(제공된 경우)는 0rhk 9 사이의 (경계 포함) 정수여야 하며, 선택적으로 상수 PRESET_EXTREME과 OR 할 수 있습니다. preset*과 *filters가 모두 제공되지 않으면, 기본 동작은 PRESET_DEFAULT(사전 설정 수준 6)를 사용하는 것입니다. 사전 설정이 높을수록 출력은 작아 지지만, 압축 과정은 느려집니다.

참고

CPU를 많이 사용하는 것 외에도, 사전 설정이 높은 압축은 훨씬 더 많은 메모리를 요구합니다 (그리고 압축을 풀기 위해 더 많은 메모리를 요구하는 출력을 생성합니다). 예를 들어 사전 설정 9를 사용하면, LZMACompressor 객체의 오버헤드가 800 MiB에 이를 수 있습니다. 이런 이유로, 일반적으로 기본 사전 설정을 사용하는 것이 가장 좋습니다.

filters 인자(제공된 경우)는 필터 체인 지정자여야 합니다. 자세한 내용은 사용자 정의 필터 체인 지정을 참조하십시오.

compress(data)

data(bytes 객체)를 압축하여, 적어도 입력의 일부에 대한 압축 데이터가 포함된 bytes 객체를 반환합니다. data의 일부는 나중에 compress()와 flush()에 대한 호출에 사용하기 위해 내부적으로 버퍼링 될 수 있습니다. 반환된 데이터는 compress()에 대한 이전 호출의 출력에 이어 붙여야 합니다.

flush()

압축 과정을 마치고, 압축기의 내부 버퍼에 저장된 모든 데이터가 포함된 bytes 객체를 반환합니다.

이 메서드를 호출한 후에는 압축기를 사용할 수 없습니다.

class lzma.LZMADecompressor(format=FORMAT_AUTO, memlimit=None, filters=None)

데이터를 점진적으로 압축 해제하는 데 사용할 수 있는 압축 해제기 객체를 만듭니다.

전체 압축 스트림을 한 번에 압축 해제하는 더 편리한 방법은 decompress()를 참조하십시오.

format 인자는 사용해야 하는 컨테이너 형식을 지정합니다. 기본값은 FORMAT_AUTO이며, .xz와 .lzma 파일을 모두 압축 해제할 수 있습니다. 다른 가능한 값은 FORMAT_XZ, FORMAT_ALONE 및 FORMAT_RAW입니다.

memlimit 인자는 압축 해제기가 사용할 수 있는 메모리양의 한계(바이트)를 지정합니다. 이 인자를 사용할 때, 주어진 메모리 한계 내에서 입력을 압축 해제할 수 없으면 LZMAError로 압축 해제에 실패합니다.

filters 인자는 압축 해제 중인 스트림을 만드는 데 사용된 필터 체인을 지정합니다. format이 FORMAT_RAW이면 이 인자가 필요하지만, 다른 형식에는 사용하지 않아야 합니다. 필터 체인에 대한 자세한 내용은 사용자 정의 필터 체인 지정을 참조하십시오.

참고

이 클래스는 decompress()와 LZMAFile과 달리, 여러 압축 스트림을 포함하는 입력을 투명하게 처리하지 않습니다. LZMADecompressor로 다중 스트림 입력을 압축 해제하려면 각 스트림에 대해 새로운 압축 해제기를 만들어야 합니다.

decompress(data, max_length=-1)

data(바이트열류 객체)를 압축 해제하고, 압축되지 않은 데이터를 바이트열로 반환합니다. data의 일부는 나중에 decompress()를 호출할 때 사용하기 위해 내부적으로 버퍼링 될 수 있습니다. 반환된 데이터는 decompress()에 대한 이전 호출의 출력에 이어 붙여야 합니다.

max_length가 음수가 아니면, 최대 max_length 바이트의 압축 해제된 데이터를 반환합니다. 이 한계에 도달하고 추가 출력을 생성할 수 있으면, needs_input 어트리뷰트가 False로 설정됩니다. 이 경우, 다음 decompress() 호출은 data를 b''로 제공하여 더 많은 출력을 얻을 수 있습니다.

모든 입력 데이터가 압축 해제되어 반환되면 (이것이 max_length 바이트 미만이거나 max_length가 음수이기 때문에), needs_input 어트리뷰트는 True로 설정됩니다.

스트림 끝에 도달한 후 데이터 압축 해제를 시도하면 EOFError가 발생합니다. 스트림 끝 이후에 발견되는 모든 데이터는 무시되고 unused_data 어트리뷰트에 저장됩니다.

버전 3.5에서 변경: max_length 매개 변수를 추가했습니다.

check

입력 스트림이 사용하는 무결성 검사의 ID. 사용되는 무결성 검사를 결정하기 위해 충분한 입력이 디코딩될 때까지 CHECK_UNKNOWN일 수 있습니다.

eof

스트림 끝 마커에 도달하면 True.

unused_data

압축된 스트림이 끝난 후 발견된 데이터.

스트림의 끝에 도달하기 전에, 이것은 b""입니다.

needs_input

decompress() 메서드가 새로운 압축 입력을 요구하기 전에 더 많은 압축 해제된 데이터를 제공 할 수 있으면 False.

버전 3.5에 추가.

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

data(bytes 객체)를 압축하여, 압축된 데이터를 bytes 객체로 반환합니다.

format, check, preset 및 filters 인자에 대한 설명은 위의 LZMACompressor를 참조하십시오.

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

data(bytes 객체)를 압축 해제하여, 압축되지 않은 데이터를 bytes 객체로 반환합니다.

data가 여러 개의 개별 압축 스트림의 연결이면, 이러한 스트림들을 모두 압축 해제하고 결과를 이어붙여 반환합니다.

format, memlimit 및 filters 인자에 대한 설명은 위의 LZMADecompressor를 참조하십시오.

기타

lzma.is_check_supported(check)

주어진 무결성 검사가 이 시스템에서 지원되면 True를 반환합니다.

CHECK_NONE과 CHECK_CRC32는 항상 지원됩니다. 제한된 기능 집합으로 컴파일된 liblzma 버전을 사용하는 경우 CHECK_CRC64와 CHECK_SHA256을 사용하지 못할 수 있습니다.

사용자 정의 필터 체인 지정

필터 체인 지정자는 딕셔너리의 시퀀스로, 각 딕셔너리에는 단일 필터의 ID와 옵션이 포함됩니다. 각 딕셔너리는 키 "id"를 포함해야 하며, 필터 종속 옵션을 지정하기 위해 추가 키를 포함할 수 있습니다. 유효한 필터 ID는 다음과 같습니다:

  • 압축 필터:

    • FILTER_LZMA1 (FORMAT_ALONE과 함께 사용)

    • FILTER_LZMA2 (FORMAT_XZ 및 FORMAT_RAW와 함께 사용)

  • 델타 필터:

    • FILTER_DELTA

  • Branch-Call-Jump (BCJ) 필터:

    • FILTER_X86

    • FILTER_IA64

    • FILTER_ARM

    • FILTER_ARMTHUMB

    • FILTER_POWERPC

    • FILTER_SPARC

필터 체인은 최대 4개의 필터로 구성될 수 있으며, 비워 둘 수 없습니다. 체인의 마지막 필터는 압축 필터여야 하고, 다른 필터는 델타나 BCJ 필터여야 합니다.

압축 필터는 다음 옵션을 지원합니다 (필터를 나타내는 딕셔너리에 추가 항목으로 지정됩니다):

  • preset: 명시적으로 지정되지 않은 옵션의 기본값 소스로 사용할 압축 사전 설정.

  • dict_size: 바이트로 표현한 딕셔너리 크기. 4 KiB와 1.5 GiB 사이여야 합니다 (경계 포함).

  • lc: 리터럴 컨텍스트 비트 수.

  • lp: 리터럴 위치 비트 수. 합계 lc + lp는 최대 4여야 합니다.

  • pb: 위치 비트 수; 최대 4여야 합니다.

  • mode: MODE_FAST나 MODE_NORMAL.

  • nice_len: 매치에서 “좋은 길이”로 간주하는 것. 273 이하여야 합니다.

  • mf: 사용할 매치 파인더 – MF_HC3, MF_HC4, MF_BT2, MF_BT3 또는 MF_BT4.

  • depth: 매치 파인더가 사용하는 최대 검색 깊이. 0(기본값)은 다른 필터 옵션을 기반으로 자동 선택함을 의미합니다.

델타 필터는 바이트 간 차이를 저장하여, 특정 상황에서 압축기에 대해 더 반복적인 입력을 생성합니다. 한 가지 옵션을 지원합니다, dist. 이것은 빼야 할 바이트 간의 거리를 나타냅니다. 기본값은 1입니다. 즉, 인접 바이트 간 차이를 취합니다.

BCJ 필터는 기계 코드에 적용하려는 것입니다. 이들은 압축기가 이용할 수 있는 중복성을 높이기 위해 코드에서 상대 분기, 호출 및 점프를 절대 주소 지정을 사용하도록 변환합니다. 이 필터는 한 가지 옵션을 지원합니다, start_offset. 이것은 입력 데이터의 시작 부분으로 매핑되어야 하는 주소를 지정합니다. 기본값은 0입니다.

예

압축 파일 읽기:

import lzma
with lzma.open("file.xz") as f:
    file_content = f.read()

압축 파일 만들기:

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)

증분 압축:

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

사용자 정의 필터 체인을 사용하여 압축 파일 만들기:

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