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에서 변경: The result is always unsigned. To generate the same numeric value when using Python 2 or earlier, use adler32(data) & 0xffffffff.

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

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과 동등합니다)을 나타냅니다. 에러가 발생하면 error 예외를 발생시킵니다.

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

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)”)와, 출력에 헤더와 트레일러가 포함되는지를 제어합니다. 여러 범위의 값을 취할 수 있으며, 기본값은 15(MAX_WBITS)입니다:

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

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

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

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에서 변경: The result is always unsigned. To generate the same numeric value when using Python 2 or earlier, use crc32(data) & 0xffffffff.

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

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

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

버전 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 라이브러리의 버전 문자열.

버전 3.3에 추가.

더 보기

모듈 gzip

gzip 형식 파일 읽기와 쓰기

http://www.zlib.net

zlib 라이브러리 홈페이지.

http://www.zlib.net/manual.html

zlib 매뉴얼은 라이브러리의 많은 함수의 의미와 사용법을 설명합니다.