"lzma" --- Compression using the LZMA algorithm
***********************************************

Added in version 3.3.

**소스 코드:** Lib/lzma.py

======================================================================

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

The interface provided by this module is very similar to that of the
"bz2" module. Note that "LZMAFile" and "bz2.BZ2File" are *not* thread-
safe, so if you need to use a single "LZMAFile" instance from multiple
threads, it is necessary to protect it with a lock.

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" supports all the members specified by
   "io.BufferedIOBase", except for "detach()" and "truncate()".
   Iteration and the "with" statement are supported.

   The following method and attributes are also provided:

   peek(size=-1)

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

      참고:

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

   mode

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

      Added in version 3.13.

   name

      The lzma file name.  Equivalent to the "name" attribute of the
      underlying *file object*.

      Added in version 3.13.

   버전 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"로 설정됩니다.

      Attempting to decompress data after the end of stream is reached
      raises an "EOFError".  Any data found after the end of the
      stream is ignored and saved in the "unused_data" attribute.

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

   check

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

   eof

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

   unused_data

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

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

   needs_input

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

      Added in version 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")
