`zlib` — gzip 과 호환되는 압축¶

데이터 압축이 필요한 애플리케이션의 경우, 이 모듈의 함수들은 `zlib 라이브러리 <https://www.zlib.net>`를 사용하여 압축 및 압축 해제를 허용합니다.

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 선택적 모듈 요구사항.

zlib의 함수에는 많은 옵션이 있으며 종종 특정 순서로 사용해야 합니다. 이 문서는 모든 순열을 다루려 하지 않으므로, 권위 있는 정보를 위해 `zlib manual <https://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.adler32_combine(adler1, adler2, len2, /)¶

두 개의 Adler-32 체크섬을 하나로 결합합니다.

시퀀스 A 의 Adler-32 체크섬 adler1 과 길이 len2 인 시퀀스 B 의 Adler-32 체크섬 adler2 가 주어지면, A 와 B 를 연결한 것의 Adler-32 체크섬을 반환합니다.

이 함수는 일반적으로 동시에 계산된 Adler-32 체크섬을 결합하는 데 유용합니다. 체크섬을 순차적으로 계산하려면, running 체크섬을 value 인수로 사용하여 :func:`adler32`를 사용하십시오.

Added in version 3.15.

zlib.compress(data, /, level=Z_DEFAULT_COMPRESSION, wbits=MAX_WBITS)¶

data 에 있는 바이트열을 압축하여 압축된 데이터를 포함하는 바이트열 객체를 반환합니다. level 은 압축 수준을 제어하는 0 부터 9 또는 -1 까지의 정수입니다. 이 값들에 대한 자세한 내용은 Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0), 그리고 기본값인 Z_DEFAULT_COMPRESSION (-1)를 참조하십시오.

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에서 변경: wbits 매개 변수를 사용하여 창 비트와 압축 유형을 설정할 수 있습니다.

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

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

level 은 압축 수준입니다 – 0 부터 9 또는 -1 까지의 정수입니다. 이 값들에 대한 자세한 내용은 Z_BEST_SPEED (1), Z_BEST_COMPRESSION (9), Z_NO_COMPRESSION (0), 그리고 기본값인 Z_DEFAULT_COMPRESSION (-1)를 참조하십시오.

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

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

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

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

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

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

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

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

zlib.crc32_combine(crc1, crc2, len2, /)¶

두 개의 CRC-32 체크섬을 하나로 결합합니다.

시퀀스 A 의 CRC-32 체크섬 crc1 과 길이 len2 인 시퀀스 B 의 CRC-32 체크섬 crc2 가 주어지면, A 와 B 를 연결한 것의 CRC-32 체크섬을 반환합니다.

이 함수는 일반적으로 동시에 계산된 CRC-32 체크섬을 결합하는 데 유용합니다. 체크섬을 순차적으로 계산하려면, running 체크섬을 value 인수로 사용하여 :func:`crc32`를 사용하십시오.

Added in version 3.15.

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 또는 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 은 비어 있습니다. 예를 들어, 전체 내용은 다음과 같이 읽을 수 있습니다:

process_output(d.decompress(data, max_length))
while chunk := d.decompress(d.unconsumed_tail, max_length):
    process_output(chunk)

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

Decompress.flush([length])¶

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

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

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

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

압축 및 압축 해제 동작을 구성하는 데 사용할 수 있는 다음 상수들이 있습니다:

zlib.DEFLATED¶: deflate 압축 방식입니다.

zlib.MAX_WBITS¶: 2의 거듭제곱으로 표현되는 최대 창 크기입니다. 예를 들어, MAX_WBITS 가 15 인 경우 창 크기는 32 KiB 가 됩니다.

zlib.DEF_MEM_LEVEL¶: 압축 객체의 기본 메모리 수준입니다.

zlib.DEF_BUF_SIZE¶: 압축 해제 작업에 대한 기본 버퍼 크기입니다.

zlib.Z_NO_COMPRESSION¶: 압축 수준 0; 압축 없음입니다.

Added in version 3.6.

zlib.Z_BEST_SPEED¶: 압축 수준 1; 가장 빠르고 압축률이 가장 낮습니다.

zlib.Z_BEST_COMPRESSION¶: 압축 수준 9; 가장 느리고 압축률이 가장 높습니다.

zlib.Z_DEFAULT_COMPRESSION¶: 기본 압축 수준(-1)입니다. 속도와 압축률 사이의 절충점입니다. 현재 압축 수준 6 과 동등합니다.

zlib.Z_DEFAULT_STRATEGY¶: 일반 데이터를 위한 기본 압축 전략입니다.

zlib.Z_FILTERED¶: 필터(또는 예측기)에 의해 생성된 데이터에 대한 압축 전략입니다.

zlib.Z_HUFFMAN_ONLY¶: 휘프만 코딩만 강제하는 압축 전략입니다.

zlib.Z_RLE¶

매치 거리를 하나로 제한하는 압축 전략입니다 (런-길이 인코딩).

이 상수는 Python이 zlib 1.2.0.1 이상으로 컴파일된 경우에만 사용할 수 있습니다.

Added in version 3.6.

zlib.Z_FIXED¶

동적 휘프만 코드를 사용하지 못하게 막는 압축 전략입니다.

이 상수는 Python이 zlib 1.2.2.2 이상으로 컴파일된 경우에만 사용할 수 있습니다.

Added in version 3.6.

zlib.Z_NO_FLUSH¶: 플러시 모드 0. 특별한 플러싱 동작이 없습니다.

Added in version 3.6.

zlib.Z_PARTIAL_FLUSH¶: 플러시 모드 1. 가능한 한 많은 출력을 플러시합니다.

zlib.Z_SYNC_FLUSH¶: 플러시 모드 2. 모든 출력이 플러시되며 출력은 바이트 경계에 정렬됩니다.

zlib.Z_FULL_FLUSH¶: 플러시 모드 3. 모든 출력이 플러시되며 압축 상태가 초기화됩니다.

zlib.Z_FINISH¶: 플러시 모드 4. 보류 중인 모든 입력이 처리되며 더 이상 입력이 기대되지 않습니다.

zlib.Z_BLOCK¶

플러시 모드 5. deflate 블록이 완료되어 방출됩니다.

이 상수는 Python이 zlib 1.2.2.2 이상으로 컴파일된 경우에만 사용할 수 있습니다.

Added in version 3.6.

zlib.Z_TREES¶

플러시 모드 6 은 inflate 작업용입니다. 다음 deflate 블록 경계에 도달하면 돌아오도록 inflate에 지시합니다.

이 상수는 Python이 zlib 1.2.3.4 이상으로 컴파일된 경우에만 사용할 수 있습니다.

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¶

zlib-ng가 모듈 빌드에 사용된 버전 문자열입니다. zlib-ng를 사용한 경우에만 해당됩니다. 제공될 경우, ZLIB_VERSION 및 ZLIB_RUNTIME_VERSION 상수는 zlib-ng가 제공하는 zlib API의 버전을 반영합니다.

zlib-ng를 사용하여 모듈을 빌드하지 않았다면 이 상수는 존재하지 않습니다.

Added in version 3.14.

모듈 gzip: gzip 형식 파일 읽기와 쓰기
https://www.zlib.net: zlib 라이브러리 홈페이지.
https://www.zlib.net/manual.html: zlib 매뉴얼은 라이브러리의 많은 함수의 의미와 사용법을 설명합니다.

gzip(압축/해제)이 병목 현상을 일으키는 경우, python-isal 패키지는 대체로 호환되는 API로 압축(해제)을 가속화합니다.

zlib — gzip 과 호환되는 압축¶

분실물 보관소

`zlib` — gzip 과 호환되는 압축¶