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

데이터 압축이 필요한 애플리케이션의 경우, 이 모듈의 함수들은 zlib 라이브러리 를 사용하여 압축 및 압축 해제를 지원합니다.

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 매뉴얼 을 참조하십시오.

.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 체크섬을 결합할 때 유용합니다. 순차적으로 체크섬을 계산하려면 value 인자로 현재까지의 체크섬을 사용하여 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 인자는 데이터를 압축할 때 사용되는 히스토리 버퍼 크기(또는 “윈도우 크기”)와 출력에 헤더 및 트레일러 포함 여부를 제어합니다. 여러 범위의 값을 가질 수 있으며, 기본값은 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 체크섬을 결합할 때 유용합니다. 순차적으로 체크섬을 계산하려면 value 인자로 현재까지의 체크섬을 사용하여 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])¶: 모든 대기 중인 입력이 처리되고, 남은 압축 출력을 포함하는 바이트(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¶: 압축된 데이터가 끝난 뒤의 바이트를 포함하는 바이트열 객체. 즉, 압축 데이터가 들어 있는 마지막 바이트를 사용할 수 있을 때까지 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¶: Huffman 코딩만 강제하는 압축 전략.

zlib.Z_RLE¶

일치 거리를 하나로 제한하는 압럼 기술(run-length encoding) 기반의 압축 전략.

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

Added in version 3.6.

zlib.Z_FIXED¶

동적 Huffman 코드를 사용하지 않는 압축 전략.

이 상수는 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 블록 경계에 도달했을 때 반환하도록 지시합니다.

이 상수는 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 과 호환되는 압축¶