zlib — gzip과 호환되는 압축

데이터 압축이 필요한 애플리케이션을 위해, zlib 모듈의 함수들은 zlib 라이브러리를 사용해 압축과 압축 해제를 가능하게 해 줘요. gzip 형식과 호환되는 압축을 제공합니다.

출처: Python 표준 라이브러리

본문

데이터 압축이 필요한 애플리케이션을 위해, 이 모듈의 함수들은 zlib 라이브러리를 이용한 압축과 압축 해제를 가능하게 해 줍니다.

이 모듈은 선택 모듈(optional module)이에요. CPython 배포판에서 빠져 있다면 배포자(즉 Python을 제공한 사람)의 문서를 찾아보세요. 그리고 .gz 파일을 읽고 쓰려면 gzip 모듈을 사용합니다.

zlib 함수는 옵션이 많고 특정한 순서로 써야 하는 경우가 많아요. 이 문서는 모든 조합을 다루려 하지 않습니다. 권위 있는 정보는 zlib 매뉴얼을 참고하세요.

이 모듈의 예외와 함수는 다음과 같습니다.

exception zlib.error

압축 및 압축 해제 오류 시 발생하는 예외입니다.

zlib.adler32(data, value=1, /)

data의 Adler-32 체크섬을 계산합니다. (Adler-32 체크섬은 CRC32와 거의 비슷하게 신뢰할 수 있지만 훨씬 빠르게 계산할 수 있어요.) 결과는 부호 없는 32비트 정수입니다. value가 있으면 체크섬의 시작 값으로 쓰이고, 아니면 기본값 1이 사용돼요. value를 넘기면 여러 입력을 이어 붙인 것에 대한 누적(running) 체크섬을 계산할 수 있습니다. 이 알고리즘은 암호학적으로 강하지 않아서 인증이나 디지털 서명에는 쓰면 안 됩니다. 체크섬용으로 설계된 알고리즘이라 일반 해시 알고리즘으로 쓰기에도 적합하지 않아요.

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

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

data 안의 바이트를 압축해 압축 데이터가 담긴 bytes 객체를 반환합니다. level은 압축 수준을 제어하는 0~9 또는 -1의 정수예요. Z_BEST_SPEED(1), Z_BEST_COMPRESSION(9), Z_NO_COMPRESSION(0), 기본값 Z_DEFAULT_COMPRESSION(-1)에 대한 자세한 내용은 해당 상수를 참고하세요.

wbits 인자는 데이터를 압축할 때 쓰는 히스토리 버퍼(또는 "윈도우 크기")의 크기와 출력에 헤더·트레일러를 포함할지 여부를 제어합니다. 기본값 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 — 히스토리 버퍼(또는 "윈도우 크기")의 크기와 사용할 헤더·트레일러 형식을 제어. 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=0, /)

data의 CRC(Cyclic Redundancy Check) 체크섬을 계산합니다. 결과는 부호 없는 32비트 정수예요. value가 있으면 체크섬의 시작 값으로 쓰이고, 아니면 기본값 0이 사용됩니다. value를 넘기면 여러 입력을 이어 붙인 것에 대한 누적 체크섬을 계산할 수 있어요. 이 알고리즘은 암호학적으로 강하지 않아 인증이나 디지털 서명에는 쓰면 안 되고, 체크섬용으로 설계된 알고리즘이라 일반 해시 알고리즘으로 쓰기에도 적합하지 않습니다.

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

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

data 안의 바이트를 압축 해제해 압축 해제된 데이터가 담긴 bytes 객체를 반환합니다. wbits 매개변수는 data의 형식에 따라 달라지며 아래에서 더 설명해요. bufsize가 주어지면 출력 버퍼의 초기 크기로 쓰입니다. 오류가 발생하면 error 예외를 일으켜요.

wbits 매개변수는 히스토리 버퍼(또는 "윈도우 크기")의 크기와 기대하는 헤더·트레일러 형식을 제어합니다. 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=b'')

한 번에 메모리에 들어가지 않는 데이터 스트림을 압축 해제하기 위한 압축 해제 객체를 반환합니다.

wbits 매개변수는 히스토리 버퍼(또는 "윈도우 크기")의 크기와 기대하는 헤더·트레일러 형식을 제어하며, decompress()에서 설명한 것과 같은 의미예요. zdict 매개변수는 미리 정의된 압축 사전을 지정합니다. 제공한다면 압축 해제할 데이터를 만든 압축기가 사용한 것과 같은 사전이어야 해요.

참고 — zdict가 변경 가능한 객체(bytearray 등)라면 decompressobj() 호출과 압축 해제기의 decompress() 메서드 첫 호출 사이에 내용을 수정하면 안 됩니다.

버전 3.3에서 변경: zdict 매개변수가 추가되었습니다.

압축 객체의 메서드

Compress.compress(data, /) — 데이터를 압축해 data의 적어도 일부에 해당하는 압축 데이터가 담긴 bytes 객체를 반환합니다. 이 데이터는 이전 compress() 호출이 만든 출력에 이어 붙여야 해요. 일부 입력은 나중 처리를 위해 내부 버퍼에 남을 수 있습니다.
Compress.flush(mode=Z_FINISH, /) — 대기 중인 모든 입력을 처리하고 남은 압축 출력이 담긴 bytes 객체를 반환합니다. 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 — 압축 데이터의 끝을 지나 있는 바이트를 담은 bytes 객체. 즉 압축 데이터를 담은 마지막 바이트가 나올 때까지 b""로 남아 있어요. 바이트열 전체가 압축 데이터로 판명되면 빈 bytes 객체인 b""입니다.
Decompress.unconsumed_tail — 마지막 decompress() 호출이 압축 해제 데이터 버퍼의 한계를 초과해 소비하지 못한 데이터를 담은 bytes 객체. 이 데이터는 아직 zlib 메커니즘이 보지 못했으므로, 올바른 출력을 얻으려면 (추가 데이터를 이어 붙여) 이후 decompress() 호출에 다시 넣어야 해요.
Decompress.eof — 압축 데이터 스트림의 끝에 도달했는지를 나타내는 불리언. 올바르게 형성된 압축 스트림과 불완전하거나 잘린 것을 구분할 수 있게 해 줍니다. (버전 3.3에서 추가)
Decompress.decompress(data, /, max_length=0) — 데이터를 압축 해제해 data의 적어도 일부에 해당하는 압축 해제 데이터가 담긴 bytes 객체를 반환합니다. 이전 decompress() 호출이 만든 출력에 이어 붙여야 해요. 일부 입력 데이터는 나중 처리를 위해 내부 버퍼에 보존될 수 있습니다. 선택 매개변수 max_length가 0이 아니면 반환 값이 max_length보다 길어지지 않습니다. 이는 압축 입력 전체를 처리하지 못할 수 있음을 뜻하며, 소비되지 않은 데이터는 unconsumed_tail 속성에 저장돼요. 압축 해제를 계속하려면 이 바이트열을 이후 decompress() 호출에 넘겨야 합니다. max_length가 0이면 전체 입력이 압축 해제되고 unconsumed_tail은 비어 있어요. (버전 3.6에서 변경: max_length를 키워드 인자로 사용 가능)
Decompress.flush(length=DEF_BUF_SIZE, /) — 대기 중인 모든 입력을 처리하고 남은 압축 해제 출력이 담긴 bytes 객체를 반환합니다. flush() 호출 후에는 decompress()를 다시 호출할 수 없고 현실적인 방법은 객체를 삭제하는 것뿐이에요. 선택 매개변수 length는 출력 버퍼의 초기 크기를 설정합니다.
Decompress.copy() — 압축 해제 객체의 복사본을 반환합니다. 데이터 스트림 중간의 압축 해제기 상태를 저장해 나중에 스트림에 대한 임의 탐색을 빠르게 하는 데 쓸 수 있어요. (버전 3.8에서 변경: copy.copy()·copy.deepcopy() 지원 추가)

압축·압축 해제 동작을 구성하는 상수

zlib.DEFLATED — deflate 압축 방법.
zlib.MAX_WBITS — 2의 거듭제곱으로 표현한 최대 윈도우 크기. 예를 들어 MAX_WBITS가 15면 윈도우 크기 32KiB가 됩니다.
zlib.DEF_MEM_LEVEL — 압축 객체의 기본 메모리 수준.
zlib.DEF_BUF_SIZE — 압축 해제 동작의 기본 버퍼 크기.
zlib.Z_NO_COMPRESSION — 압축 수준 0; 압축 없음. (버전 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 — Huffman 코딩만 강제하는 압축 전략.
zlib.Z_RLE — 일치 거리를 1로 제한하는 압축 전략(런-길이 인코딩). Python이 zlib 1.2.0.1 이상으로 컴파일된 경우에만 사용 가능. (버전 3.6에서 추가)
zlib.Z_FIXED — 동적 Huffman 코드 사용을 막는 압축 전략. Python이 zlib 1.2.2.2 이상으로 컴파일된 경우에만 사용 가능. (버전 3.6에서 추가)
zlib.Z_NO_FLUSH — 플러시 모드 0. 특별한 플러시 동작 없음. (버전 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 이상으로 컴파일된 경우에만 사용 가능. (버전 3.6에서 추가)
zlib.Z_TREES — inflate 동작용 플러시 모드 6. 다음 deflate 블록 경계에 도달하면 inflate가 반환하도록 지시. Python이 zlib 1.2.3.4 이상으로 컴파일된 경우에만 사용 가능. (버전 3.6에서 추가)

사용 중인 zlib 라이브러리 버전에 대한 정보는 다음 상수로 얻을 수 있어요.

zlib.ZLIB_VERSION — 모듈을 빌드할 때 사용한 zlib 라이브러리의 버전 문자열. 런타임에 실제 사용하는 zlib 라이브러리(ZLIB_RUNTIME_VERSION으로 확인)와 다를 수 있습니다.
zlib.ZLIB_RUNTIME_VERSION — 인터프리터가 실제로 로드한 zlib 라이브러리의 버전 문자열. (버전 3.3에서 추가)
zlib.ZLIBNG_VERSION — zlib-ng를 사용해 모듈을 빌드했다면 그 zlib-ng 라이브러리의 버전 문자열. 존재할 때 ZLIB_VERSION과 ZLIB_RUNTIME_VERSION 상수는 zlib-ng가 제공하는 zlib API 버전을 반영해요. zlib-ng를 사용하지 않고 빌드했다면 이 상수는 없습니다. (버전 3.14에서 추가)

더 알아보기

gzip 모듈 — gzip 형식 파일 읽기/쓰기.
https://www.zlib.net — zlib 라이브러리 홈페이지.
https://www.zlib.net/manual.html — zlib 매뉴얼. 라이브러리의 여러 함수 의미와 용법을 설명합니다.
gzip (역)압축이 병목이라면, python-isal 패키지가 대부분 호환되는 API로 (역)압축을 빠르게 해 줍니다.