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

lzma 모듈은 LZMA 압축 알고리즘으로 데이터를 압축하고 해제하는 클래스와 편의 함수를 제공해요. xz 유틸리티가 사용하는 .xz와 옛 .lzma 파일 형식, 그리고 raw 압축 스트림을 지원하는 파일 인터페이스도 포함돼요.

이 모듈이 제공하는 인터페이스는 bz2 모듈과 매우 비슷해요. LZMAFile과 bz2.BZ2File은 스레드 안전하지 않으므로, 단일 LZMAFile 인스턴스를 여러 스레드에서 사용해야 한다면 잠금으로 보호하는 게 필요해요.

이것은 선택적 모듈이에요. 여러분의 CPython 사본에 없다면 배포자(즉 Python을 제공한 사람)의 문서를 찾아보세요. 여러분이 배포자라면 선택적 모듈 요구사항을 참고하세요.

버전 3.3에 추가됨.

출처: Python 표준 라이브러리

본문

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 또는 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 객체 허용.

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

LZMA 압축 파일을 이진 모드로 열어요.

LZMAFile은 이미 열린 파일 객체를 감쌀 수도 있고, 이름이 지정된 파일에서 직접 작동할 수도 있어요. filename 인자는 감쌀 파일 객체 또는 열 파일의 이름(str, bytes 또는 path-like 객체)을 지정해요. 기존 파일 객체를 감쌀 때, LZMAFile이 닫혀도 감싸인 파일은 닫히지 않아요.

mode 인자는 읽기용 "r"(기본값), 덮어쓰기 "w", 배타적 생성 "x", 추가 "a" 중 하나일 수 있어요. 이들은 각각 "rb", "wb", "xb", "ab"로 동등하게 줄 수 있어요.

filename이 파일 객체(실제 파일 이름이 아니라)라면 "w" 모드는 파일을 자르지 않고 대신 "a"와 동등해요.

읽기용으로 파일을 열 때 입력 파일은 여러 개의 분리된 압축 스트림의 이어붙임일 수 있어요. 이들은 단일 논리 스트림으로 투명하게 디코딩돼요.

LZMAFile은 detach()와 truncate()를 제외한 io.BufferedIOBase가 지정하는 모든 멤버를 지원해요. 반복과 with 문도 지원돼요.

다음 메서드와 속성도 제공돼요:

peek(size=-1) — 파일 위치를 전진시키지 않고 버퍼링된 데이터를 돌려줘요. EOF에 도달하지 않았다면 적어도 한 바이트의 데이터가 돌려져요. 반환되는 정확한 바이트 수는 지정되지 않아요(size 인자는 무시됨). 참고: peek() 호출은 LZMAFile의 파일 위치를 바꾸지 않지만, 밑바탕 파일 객체의 위치는 바꿀 수 있어요(예: filename에 파일 객체를 전달해 LZMAFile을 만들었을 때).
mode — 읽기용 'rb', 쓰기용 'wb'. 버전 3.13에 추가됨.
name — lzma 파일 이름. 밑바탕 파일 객체의 name 속성과 동등. 버전 3.13에 추가됨.

버전 3.4에서 변경: "x", "xb" 모드 지원 추가. 버전 3.5에서 변경: read() 메서드가 None 인자를 받음. 버전 3.6에서 변경: path-like 객체 허용.

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

class lzma.LZMACompressor(format=FORMAT_XZ, check=-1, preset=None, filters=None)

데이터를 점진적으로 압축하는 데 쓸 수 있는 압축기 객체를 만들어요. 단일 데이터 청크를 압축하는 더 편리한 방법은 compress()를 참고하세요.

format 인자는 어떤 컨테이너 형식을 사용할지 지정해요. 가능한 값은 FORMAT_XZ(기본값), FORMAT_ALONE, FORMAT_RAW예요.

check 인자는 압축 데이터에 포함할 무결성 검사 타입을 지정해요. 이 검사는 데이터를 해제할 때 손상되지 않았는지 보장하는 데 사용돼요. 가능한 값은 CHECK_NONE, CHECK_CRC32, CHECK_CRC64(FORMAT_XZ의 기본값), CHECK_SHA256이에요. 지정된 검사가 지원되지 않으면 LZMAError가 일어나요.

압축 설정은 preset 인자로 사전 설정 압축 수준으로 지정하거나, filters 인자로 커스텀 필터 체인으로 상세히 지정할 수 있어요.

preset 인자(제공되면)는 (포함해서) 0과 9 사이의 정수이고, 선택적으로 상수 PRESET_EXTREME와 OR될 수 있어요. preset도 filters도 주어지지 않으면 기본 동작은 PRESET_DEFAULT(preset 수준 6)를 사용하는 거예요. 더 높은 preset은 더 작은 출력을 만들지만 압축 과정을 느리게 해요.

참고: 더 높은 preset으로 압축하는 것은 CPU 집약적일 뿐 아니라 훨씬 더 많은 메모리가 필요해요(그리고 해제에 더 많은 메모리가 필요한 출력을 만들어요). 예를 들어 preset 9에서 LZMACompressor 객체의 오버헤드는 800 MiB까지 될 수 있어요. 이런 이유로 일반적으로 기본 preset을 고수하는 게 가장 좋아요.

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(bytes-like 객체)를 해제하고 해제되지 않은 데이터를 bytes로 돌려줘요. 일부 data는 내부적으로 버퍼링되어 나중에 decompress() 호출에 사용될 수 있어요. 반환된 데이터는 이전 decompress() 호출의 출력과 이어붙여야 해요. max_length가 음이 아니면 최대 max_length 바이트의 해제 데이터를 돌려줘요. 이 제한에 도달하고 더 많은 출력을 만들 수 있으면 needs_input 속성이 False로 설정돼요. 이 경우 다음 decompress() 호출은 더 많은 출력을 얻기 위해 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는 항상 지원돼요. CHECK_CRC64와 CHECK_SHA256은 제한된 기능 집합으로 컴파일된 liblzma 버전을 사용한다면 사용할 수 없을 수 있어요.

커스텀 필터 체인 지정

필터 체인 지정자는 딕셔너리의 시퀀스인데, 각 딕셔너리는 단일 필터의 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: 명시적으로 지정되지 않은 옵션의 기본값 소스로 사용할 압축 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이에요.

상수

위의 클래스와 함수의 format, check, preset, filters 인자로 사용하기 위해 다음 모듈 수준 상수가 제공돼요.

컨테이너 형식:

lzma.FORMAT_XZ — .xz 컨테이너 형식.
lzma.FORMAT_ALONE — 옛 .lzma 컨테이너 형식. 이 형식은 .xz보다 더 제한적이에요 — 무결성 검사나 여러 필터를 지원하지 않아요.
lzma.FORMAT_RAW — 어떤 컨테이너 형식도 사용하지 않는 원시 데이터 스트림. 이 형식 지정자는 무결성 검사를 지원하지 않고, 항상 커스텀 필터 체인을 지정해야 해요(압축과 해제 모두). 게다가 이런 방식으로 압축된 데이터는 FORMAT_AUTO로 해제할 수 없어요.
lzma.FORMAT_AUTO — 해제에만 사용. 컨테이너 형식이 자동으로 감지되어 .xz와 .lzma 파일을 모두 해제할 수 있어요.

무결성 검사:

lzma.CHECK_NONE — 무결성 검사 없음. FORMAT_ALONE과 FORMAT_RAW의 기본(그리고 유일하게 허용되는 값)이에요.
lzma.CHECK_CRC32 — 32비트 순환 중복 검사(Cyclic Redundancy Check).
lzma.CHECK_CRC64 — 64비트 순환 중복 검사. FORMAT_XZ의 기본값이에요.
lzma.CHECK_SHA256 — 256비트 보안 해시 알고리즘(Secure Hash Algorithm).
lzma.CHECK_UNKNOWN — 스트림이 사용하는 무결성 검사를 아직 결정할 수 없음. 충분한 입력이 디코딩될 때까지 LZMADecompressor.check 속성의 값일 수 있어요.
lzma.CHECK_ID_MAX — 지원되는 가장 큰 무결성 검사 ID.

압축 preset:

lzma.PRESET_DEFAULT — 기본 압축 preset, preset 수준 6과 동등.
lzma.PRESET_EXTREME — preset 수준(0~9)과 비트 OR될 수 있는 플래그로, 그 preset의 더 느리지만 더 철저한 변형을 선택.

필터 ID와 옵션:

lzma.FILTER_LZMA1, lzma.FILTER_LZMA2 — LZMA1과 LZMA2 압축 필터. FILTER_LZMA1은 FORMAT_ALONE과, FILTER_LZMA2는 FORMAT_XZ와 FORMAT_RAW와 사용.
lzma.FILTER_DELTA — 델타 필터.
lzma.MODE_FAST, lzma.MODE_NORMAL — 필터 지정자의 mode 옵션으로 사용할 수 있는 압축 모드(커스텀 필터 체인 지정 참고).
lzma.MF_HC3, lzma.MF_HC4, lzma.MF_BT2, lzma.MF_BT3, lzma.MF_BT4 — 필터 지정자의 mf 옵션으로 사용할 수 있는 매치 파인더(커스텀 필터 체인 지정 참고).

예제

압축 파일 읽기:

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

더 알아보기

bz2 — bzip2 압축 지원.
zipfile — ZIP 아카이브 작업.
gzip — gzip 압축 지원.