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