# `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.