# `lzma` — Compression using the LZMA algorithm

버전 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` 문이 지원됩니다.

  The following method is also provided:

  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 인자(제공된 경우)는 `0`rhk `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")