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

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

For applications that require data compression, the functions in this
module allow compression and decompression, using the zlib library.

This is an *optional module*. If it is missing from your copy of
CPython, look for documentation from your distributor (that is,
whoever provided Python to you). If you are the distributor, see
Requirements for optional modules.

zlib's functions have many options and often need to be used in a
particular order.  This documentation doesn't attempt to cover all of
the permutations; consult the zlib manual for authoritative
information.

".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=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)

   Compresses the bytes in *data*, returning a bytes object containing
   compressed data. *level* is an integer from "0" to "9" or "-1"
   controlling the level of compression; See "Z_BEST_SPEED" ("1"),
   "Z_BEST_COMPRESSION" ("9"), "Z_NO_COMPRESSION" ("0"), and the
   default, "Z_DEFAULT_COMPRESSION" ("-1") for more information about
   these values.

   The *wbits* argument controls the size of the history buffer (or
   the "window size") used when compressing data, and whether a header
   and trailer is included in the output.  It can take several ranges
   of values, defaulting to "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=Z_DEFAULT_COMPRESSION, method=DEFLATED, wbits=MAX_WBITS, memLevel=DEF_MEM_LEVEL, strategy=Z_DEFAULT_STRATEGY[, zdict])

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

   *level* is the compression level -- an integer from "0" to "9" or
   "-1". See "Z_BEST_SPEED" ("1"), "Z_BEST_COMPRESSION" ("9"),
   "Z_NO_COMPRESSION" ("0"), and the default, "Z_DEFAULT_COMPRESSION"
   ("-1") for more information about these values.

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

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

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

   *strategy* is used to tune the compression algorithm. Possible
   values are "Z_DEFAULT_STRATEGY", "Z_FILTERED", "Z_HUFFMAN_ONLY",
   "Z_RLE" and "Z_FIXED".

   *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])

   All pending input is processed, and a bytes object containing the
   remaining compressed output is returned.  *mode* can be selected
   from the constants "Z_NO_FLUSH", "Z_PARTIAL_FLUSH", "Z_SYNC_FLUSH",
   "Z_FULL_FLUSH", "Z_BLOCK", or "Z_FINISH", defaulting to "Z_FINISH".
   Except "Z_FINISH", all constants allow compressing further
   bytestrings of data, while "Z_FINISH" finishes the compressed
   stream and prevents compressing any more data.  After calling
   "flush()" with *mode* set to "Z_FINISH", the "compress()" method
   cannot be called again; the only realistic action is to delete the
   object.

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()"
지원이 추가되었습니다.

The following constants are available to configure compression and
decompression behavior:

zlib.DEFLATED

   The deflate compression method.

zlib.MAX_WBITS

   The maximum window size, expressed as a power of 2. For example, if
   "MAX_WBITS" is "15" it results in a window size of "32 KiB".

zlib.DEF_MEM_LEVEL

   The default memory level for compression objects.

zlib.DEF_BUF_SIZE

   The default buffer size for decompression operations.

zlib.Z_NO_COMPRESSION

   Compression level "0"; no compression.

   Added in version 3.6.

zlib.Z_BEST_SPEED

   Compression level "1"; fastest and produces the least compression.

zlib.Z_BEST_COMPRESSION

   Compression level "9"; slowest and produces the most compression.

zlib.Z_DEFAULT_COMPRESSION

   Default compression level ("-1"); a compromise between speed and
   compression. Currently equivalent to compression level "6".

zlib.Z_DEFAULT_STRATEGY

   Default compression strategy, for normal data.

zlib.Z_FILTERED

   Compression strategy for data produced by a filter (or predictor).

zlib.Z_HUFFMAN_ONLY

   Compression strategy that forces Huffman coding only.

zlib.Z_RLE

   Compression strategy that limits match distances to one (run-length
   encoding).

   This constant is only available if Python was compiled with zlib
   1.2.0.1 or greater.

   Added in version 3.6.

zlib.Z_FIXED

   Compression strategy that prevents the use of dynamic Huffman
   codes.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Added in version 3.6.

zlib.Z_NO_FLUSH

   Flush mode "0". No special flushing behavior.

   Added in version 3.6.

zlib.Z_PARTIAL_FLUSH

   Flush mode "1". Flush as much output as possible.

zlib.Z_SYNC_FLUSH

   Flush mode "2". All output is flushed and the output is aligned to
   a byte boundary.

zlib.Z_FULL_FLUSH

   Flush mode "3". All output is flushed and the compression state is
   reset.

zlib.Z_FINISH

   Flush mode "4". All pending input is processed, no more input is
   expected.

zlib.Z_BLOCK

   Flush mode "5". A deflate block is completed and emitted.

   This constant is only available if Python was compiled with zlib
   1.2.2.2 or greater.

   Added in version 3.6.

zlib.Z_TREES

   Flush mode "6", for inflate operations. Instructs inflate to return
   when it gets to the next deflate block boundary.

   This constant is only available if Python was compiled with zlib
   1.2.3.4 or greater.

   Added in version 3.6.

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

zlib.ZLIB_VERSION

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

zlib.ZLIB_RUNTIME_VERSION

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

   Added in version 3.3.

zlib.ZLIBNG_VERSION

   The version string of the zlib-ng library that was used for
   building the module if zlib-ng was used. When present, the
   "ZLIB_VERSION" and "ZLIB_RUNTIME_VERSION" constants reflect the
   version of the zlib API provided by zlib-ng.

   If zlib-ng was not used to build the module, this constant will be
   absent.

   Added in version 3.14.

더 보기:

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

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

  https://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.
