"zlib" --- **gzip** 과 호환되는 압축
************************************

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

데이터 압축이 필요한 응용 프로그램의 경우, 이 모듈의 함수는 zlib 라이
브러리를 사용하여 압축과 압축 해제를 하도록 합니다. zlib 라이브러리는
https://www.zlib.net 에 자체 홈페이지가 있습니다. 파이썬 모듈과 1.1.3
이전의 zlib 라이브러리 버전 간에는 호환성 문제가 알려져 있습니다;
1.1.3에는 보안 취약점이 있기 때문에, 1.1.4 이상을 사용하는 것이 좋습니
다.

zlib의 함수에는 많은 옵션이 있으며 종종 특정 순서로 사용해야 합니다.
이 설명서는 모든 순열을 다루려고 시도하지는 않습니다; 권위 있는 정보는
zlib 매뉴얼(http://www.zlib.net/manual.html)을 참조하십시오.

".gz" 파일 읽기와 쓰기에 대해서는 "gzip" 모듈을 참조하십시오.

이 모듈에서 사용 가능한 예외와 함수는 다음과 같습니다:

exception zlib.error

   압축과 압축 해제 에러에서 발생하는 예외.

zlib.adler32(data[, value])

   *data*의 Adler-32 체크섬을 계산합니다. (Adler-32 체크섬은 CRC32만큼
   신뢰성 있지만, 훨씬 빠르게 계산할 수 있습니다.) 결과는 부호 없는 32
   비트 정수입니다. *value*가 있으면, 체크섬의 시작 값으로 사용됩니다;
   그렇지 않으면, 기본값 1이 사용됩니다. *value*를 전달하면 여러 입력
   을 이어붙인 것에 대한 잇따른(running) 체크섬을 계산할 수 있습니다.
   알고리즘은 암호학적으로 강력하지 않아서, 인증이나 디지털 서명에 사
   용해서는 안 됩니다. 알고리즘은 체크섬 알고리즘으로 사용하도록 설계
   되었으므로, 일반적인 해시 알고리즘으로 사용하기에 적합하지 않습니다
   .

   버전 3.0에서 변경: 결과는 항상 부호 없는 값입니다.

zlib.compress(data, /, level=-1, wbits=MAX_WBITS)

   *data*에 있는 바이트열을 압축하여, 압축된 데이터를 포함하는 바이트
   열 객체를 반환합니다. *level*은 압축 수준을 제어하는 "0"에서 "9" 또
   는 "-1"인 정수입니다; "1"(Z_BEST_SPEED)은 가장 빠르고 압축률이 가장
   낮습니다, "9"(Z_BEST_COMPRESSION)는 가장 느리고 최대 압축을 생성합
   니다. "0"(Z_NO_COMPRESSION)은 압축하지 않습니다. 기본값은
   "-1"(Z_DEFAULT_COMPRESSION)입니다. Z_DEFAULT_COMPRESSION은 속도와
   압축률 사이의 기본 절충(현재 수준 6과 동등합니다)을 나타냅니다.

   *wbits* 인자는 데이터를 압축할 때 사용되는 히스토리 버퍼의 크기(또
   는 "창 크기(window size)")와, 출력에 헤더와 트레일러가 포함되는지를
   제어합니다. 여러 범위의 값을 취할 수 있으며, 기본값은
   "15"(MAX_WBITS)입니다:

   * +9 에서 +15: 창 크기의 밑이 2인 로그, 그래서 창 크기는 512에서
     32768 사이의 범위입니다. 값이 클수록 메모리 사용량이 증가하면서
     압축률이 높아집니다. 결과 출력에는 zlib 특정 헤더와 트레일러가 포
     함됩니다.

   * −9 에서 −15: *wbits*의 절댓값을 창 크기의 로그로 사용하면서, 헤더
     나 후행 체크섬 없이 원시 출력 스트림을 생성합니다.

   * +25 에서 +31 = 16 + (9 에서 15): 하위 4비트를 창 크기의 로그로 사
     용하면서, 출력에 기본 **gzip** 헤더와 후행 체크섬을 포함합니다.

   에러가 발생하면 "error" 예외를 발생시킵니다.

   버전 3.6에서 변경: *level*은 이제 키워드 매개 변수로 사용될 수 있습
   니다.

   버전 3.11에서 변경: The *wbits* parameter is now available to set
   window bits and compression type.

zlib.compressobj(level=-1, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

   메모리에 한 번에 맞지 않는 데이터 스트림을 압축하는 데 사용되는 압
   축 객체를 반환합니다.

   *level*은 압축 수준입니다 -- "0"에서 "9" 또는 "-1"인 정수입니다.
   "1"(Z_BEST_SPEED) 값은 가장 빠르고 압축률이 가장 낮지만,
   "9"(Z_BEST_COMPRESSION) 값은 가장 느리고 최대 압축을 생성합니다.
   "0"(Z_NO_COMPRESSION)은 압축하지 않습니다. 기본값은
   "-1"(Z_DEFAULT_COMPRESSION)입니다. Z_DEFAULT_COMPRESSION은 속도와
   압축률 사이의 기본 절충(현재 수준 6과 동등합니다)을 나타냅니다.

   *method*는 압축 알고리즘입니다. 현재, 유일하게 지원되는 값은
   "DEFLATED"입니다.

   *wbits* 매개 변수는 히스토리 버퍼의 크기(또는 "창 크기(window
   size)")와, 어떤 헤더와 트레일러 형식을 사용할지를 제어합니다.
   compress()에서 설명된 것과 같은 의미입니다.

   *memLevel* 인자는 내부 압축 상태에 사용되는 메모리양을 제어합니다.
   유효한 값의 범위는 "1"에서 "9"입니다. 값이 클수록 더 많은 메모리를
   사용하지만, 더 빠르고 더 작은 출력을 생성합니다.

   *strategy*는 압축 알고리즘을 조정하는 데 사용됩니다. 가능한 값은
   "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY", "Z_RLE"(zlib
   1.2.0.1) 및 "Z_FIXED"(zlib 1.2.2.2)입니다.

   *zdict*는 사전 정의된 압축 딕셔너리입니다. 이것은 압축될 데이터에서
   자주 나타날 것으로 예상되는 서브 시퀀스를 포함하는 일련의 바이트 시
   퀀스(가령 "bytes" 객체)입니다. 가장 흔할 것으로 예상되는 서브 시퀀
   스는 딕셔너리 끝에 와야 합니다.

   버전 3.3에서 변경: *zdict* 매개 변수와 키워드 인자 지원이 추가되었
   습니다.

zlib.crc32(data[, value])

   *data*의 CRC (Cyclic Redundancy Check) 체크섬을 계산합니다. 결과는
   부호 없는 32비트 정수입니다. *value*가 있으면, 체크섬의 시작 값으로
   사용됩니다; 그렇지 않으면, 기본값 1이 사용됩니다. *value*를 전달하
   면 여러 입력을 이어붙인 것에 대한 잇따른(running) 체크섬을 계산할
   수 있습니다. 알고리즘은 암호학적으로 강력하지 않아서, 인증이나 디지
   털 서명에 사용해서는 안 됩니다. 알고리즘은 체크섬 알고리즘으로 사용
   하도록 설계되었으므로, 일반적인 해시 알고리즘으로 사용하기에 적합하
   지 않습니다.

   버전 3.0에서 변경: 결과는 항상 부호 없는 값입니다.

zlib.decompress(data, /, wbits=MAX_WBITS, bufsize=DEF_BUF_SIZE)

   *data*에 있는 바이트열을 압축 해제하여, 압축되지 않은 데이터를 포함
   하는 바이트열 객체를 반환합니다. *wbits* 매개 변수는 *data*의 형식
   에 따라 다르며, 아래에서 자세히 설명합니다. *bufsize*가 제공되면,
   출력 버퍼의 초기 크기로 사용됩니다. 에러가 발생하면 "error" 예외를
   발생시킵니다.

   *wbits* 인자는 히스토리 버퍼의 크기(또는 "창 크기(window size)")와,
   어떤 헤더와 트레일러 형식을 기대하는지를 제어합니다.
   "compressobj()"의 매개 변수와 유사하지만, 더 많은 범위의 값을 받아
   들입니다:

   * +8 에서 +15: 창 크기의 밑이 2인 로그. 입력은 zlib 헤더와 트레일러
     를 포함해야 합니다.

   * 0: zlib 헤더에서 창 크기를 자동으로 결정합니다. zlib 1.2.3.5부터
     지원됩니다.

   * −8 에서 −15: *wbits*의 절댓값을 창 크기의 로그로 사용합니다. 입력
     은 헤더나 트레일러가 없는 원시 스트림이어야 합니다.

   * +24 에서 +31 = 16 + (8 에서 15): 값의 하위 4비트를 창 크기의 로그
     로 사용합니다. 입력은 gzip 헤더와 트레일러를 포함해야 합니다.

   * +40 에서 +47 = 32 + (8 에서 15): 값의 하위 4비트를 창 크기의 로그
     로 사용하고, zlib나 gzip 형식을 자동으로 받아들입니다.

   스트림을 압축 해제할 때, 창 크기는 스트림을 압축하는 데 원래 사용된
   크기보다 작아서는 안 됩니다; 너무 작은 값을 사용하면 "error" 예외가
   발생할 수 있습니다. 기본 *wbits* 값은 가장 큰 창 크기에 해당하며
   zlib 헤더와 트레일러가 포함될 것을 요구합니다.

   *bufsize*는 압축 해제된 데이터를 담는 데 사용되는 버퍼의 초기 크기
   입니다. 더 많은 공간이 필요하면, 필요에 따라 버퍼 크기가 증가하므로
   , 이 값을 정확하게 얻을 필요는 없습니다; 조정하면 "malloc()"에 대한
   몇 번의 호출만 절약됩니다.

   버전 3.6에서 변경: *wbits*와 *bufsize*는 키워드 인자로 사용할 수 있
   습니다.

zlib.decompressobj(wbits=MAX_WBITS[, zdict])

   메모리에 한 번에 맞지 않는 데이터 스트림을 압축 해제하는 데 사용되
   는 압축 해제 객체를 반환합니다.

   *wbits* 인자는 히스토리 버퍼의 크기(또는 "창 크기(window size)")와,
   어떤 헤더와 트레일러 형식을 기대하는지를 제어합니다. decompress()에
   서 설명된 것과 같은 의미입니다.

   *zdict* 매개 변수는 사전 정의된 압축 딕셔너리를 지정합니다. 제공되
   면,, 압축 해제할 데이터를 생성한 압축기에서 사용한 것과 같은 딕셔너
   리이어야 합니다.

   참고:

     *zdict*가 가변 객체(가령 "bytearray")이면, "decompressobj()"에 대
     한 호출과 압축 해제기의 "decompress()" 메서드에 대한 첫 번째 호출
     사이에 내용을 수정해서는 안 됩니다.

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

압축 객체는 다음 메서드를 지원합니다:

Compress.compress(data)

   *data*를 압축하여, *data*의 데이터 중 적어도 일부에 대한 압축된 데
   이터가 포함된 바이트열 객체를 반환합니다. 이 데이터는 "compress()"
   메서드에 대한 이전 호출에서 생성된 출력에 이어붙여야 합니다. 일부
   입력은 나중에 처리하기 위해 내부 버퍼에 보관될 수 있습니다.

Compress.flush([mode])

   계류 중인 모든 입력이 처리되고, 나머지 압축 출력을 포함하는 바이트
   열 객체가 반환됩니다. *mode*는 상수 "Z_NO_FLUSH",
   "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH", "Z_FULL_FLUSH", "Z_BLOCK"(zlib
   1.2.3.4) 또는 "Z_FINISH"에서 선택할 수 있으며, 기본값은 "Z_FINISH"
   입니다. "Z_FINISH"를 제외한 모든 상수는 추가 바이트열 데이터를 압축
   하도록 허락하는  반면, "Z_FINISH"는 압축된 스트림을 완료하고 추가
   데이터의 압축을 방지합니다. *mode*를 "Z_FINISH"로 설정하고
   "flush()"를 호출한 후, "compress()" 메서드를 다시 호출할 수 없습니
   다; 유일한 현실적인 조치는 객체를 삭제하는 것입니다.

Compress.copy()

   압축 객체의 복사본을 반환합니다. 공통 초기 접두사를 공유하는 데이터
   집합을 효율적으로 압축하는 데 사용할 수 있습니다.

버전 3.8에서 변경: 압축 객체에 "copy.copy()"와 "copy.deepcopy()" 지원
이 추가되었습니다.

압축 해제 객체는 다음과 같은 메서드와 어트리뷰트를 지원합니다:

Decompress.unused_data

   압축된 데이터가 끝난 뒤의 바이트를 포함하는 바이트열 객체. 즉, 압축
   데이터가 들어 있는 마지막 바이트를 사용할 수 있을 때까지 "b"""로 남
   습니다. 전체 바이트열이 압축된 데이터를 포함하는 것으로 판명되면,
   이것은 빈 바이트열 객체인 "b"""입니다.

Decompress.unconsumed_tail

   압축되지 않은 데이터 버퍼의 한계를 초과하기 때문에 마지막
   "decompress()" 호출에 의해 소비되지 않은 모든 데이터를 포함하는 바
   이트열 객체. 이 데이터는 아직 zlib 장치가 볼 수 없었기 때문에 올바
   른 출력을 얻으려면 후속 "decompress()" 메서드 호출에 다시 공급해야
   합니다 (아마도 추가 데이터를 이것에 이어붙여서).

Decompress.eof

   압축된 데이터 스트림의 끝에 도달했는지를 나타내는 불리언.

   올바르게 구성된 압축 스트림과 불완전하거나 잘린 스트림을 구별할 수
   있도록 합니다.

   Added in version 3.3.

Decompress.decompress(data, max_length=0)

   *data*를 압축 해제하여, *string*의 데이터 중 적어도 일부에 해당하는
   압축되지 않은 데이터를 포함하는 바이트열 객체를 반환합니다. 이 데이
   터는 "decompress()" 메서드에 대한 이전 호출에서 생성된 출력에 이어
   붙여야 합니다. 입력 데이터 중 일부는 나중에 처리하기 위해 내부 버퍼
   에 보존될 수 있습니다.

   선택적 매개 변수 *max_length*가 0이 아니면 반환 값은 *max_length*보
   다 길지 않습니다. 이는 모든 압축 입력을 처리할 수 없음을 뜻합니다;
   소비되지 않은 데이터는 "unconsumed_tail" 어트리뷰트에 저장됩니다.
   압축 해제를 계속하려면 이 바이트열을 "decompress()"에 대한 후속 호
   출로 전달해야 합니다. *max_length*가 0이면 전체 입력이 압축 해제되
   고, "unconsumed_tail"은 비어 있습니다.

   버전 3.6에서 변경: *max_length*는 키워드 인자로 사용할 수 있습니다.

Decompress.flush([length])

   계류 중인 모든 입력이 처리되고, 나머지 압축되지 않은 출력을 포함하
   는 바이트열 객체가 반환됩니다. "flush()"를 호출한 후,
   "decompress()" 메서드를 다시 호출할 수 없습니다; 유일한 현실적인 조
   치는 객체를 삭제하는 것입니다.

   선택적 매개 변수 *length*는 출력 버퍼의 초기 크기를 설정합니다.

Decompress.copy()

   압축 해제 객체의 복사본을 반환합니다. 이것은 미래 시점에 스트림으로
   의 임의 탐색(random seek) 속도를 높이기 위해 데이터 스트림의 중간
   지점에서 압축 해제기의 상태를 저장하는 데 사용될 수 있습니다.

버전 3.8에서 변경: 압축 해제 객체에 "copy.copy()"와 "copy.deepcopy()"
지원이 추가되었습니다.

사용 중인 zlib 라이브러리 버전에 대한 정보는 다음 상수를 통해 사용할
수 있습니다:

zlib.ZLIB_VERSION

   모듈을 빌드하는 데 사용된 zlib 라이브러리의 버전 문자열.
   "ZLIB_RUNTIME_VERSION"으로 사용 가능한, 실행 시간에 실제로 사용되는
   zlib 라이브러리와 다를 수 있습니다.

zlib.ZLIB_RUNTIME_VERSION

   인터프리터가 실제로 로드한 zlib 라이브러리의 버전 문자열.

   Added in version 3.3.

더 보기:

  모듈 "gzip"
     **gzip** 형식 파일 읽기와 쓰기

  http://www.zlib.net
     zlib 라이브러리 홈페이지.

  http://www.zlib.net/manual.html
     zlib 매뉴얼은 라이브러리의 많은 함수의 의미와 사용법을 설명합니다
     .

  In case gzip (de)compression is a bottleneck, the python-isal
  package speeds up (de)compression with a mostly compatible API.
