deflate — deflate 압축 및 압축 해제

이 모듈은 DEFLATE 알고리즘(zlib 라이브러리와 gzip 아카이버에서 일반적으로 사용됨)을 사용하여 바이너리 데이터를 압축하고 압축 해제할 수 있게 해줍니다. MicroPython v1.21에서 추가되었습니다.

OpenMV 지원 보드에서의 가용성:

보드	압축 해제	압축
OpenMV Cam N6	예	아니오
OpenMV AE3	예	예
OpenMV Cam RT1062	예	예
OpenMV Cam Pure Thermal	예	아니오
OpenMV Cam M4	예	아니오
OpenMV Cam M7	예	아니오
OpenMV Cam H7	예	아니오
OpenMV Cam H7 Plus	예	아니오
Arduino Giga	예	아니오
Arduino Portenta H7	예	아니오
Arduino Nicla Vision	예	아니오
Arduino Nano 33 BLE Sense	예	아니오
Arduino Nano RP2040 Connect	예	아니오

클래스

class deflate.DeflateIO(stream: Any, format: int = AUTO, wbits: int = 0, close: bool = False, /)

이 클래스는 파일, 소켓, 또는 스트림(io.BytesIO 포함)과 같은 스트림 유사 객체인 stream을 래핑하는 데 사용할 수 있습니다. 이 클래스 자체가 스트림이며 표준 read/readinto/write/close 메서드를 구현합니다.

stream은 블로킹 스트림이어야 합니다. 논블로킹 스트림은 현재 지원되지 않습니다.

format은 아래에 정의된 상수 중 하나로 설정할 수 있으며, 기본값은 AUTO입니다. 압축 해제 시에는 gzip 또는 zlib 스트림을 자동 감지하고, 압축 시에는 raw 스트림을 생성합니다.

wbits 매개변수는 DEFLATE 딕셔너리 윈도우 크기의 밑이 2인 로그값을 설정합니다. 예를 들어 wbits를 10으로 설정하면 윈도우 크기가 1024바이트로 설정됩니다. 유효한 값은 5에서 15까지(윈도우 크기 32에서 32k 바이트에 해당)입니다.

wbits가 0(기본값)으로 설정되면, 압축 시에는 256바이트의 윈도우 크기가 사용됩니다(wbits를 8로 설정한 것과 같음). 압축 해제 시에는 형식에 따라 다릅니다:

• RAW는 256바이트를 사용합니다(wbits를 8로 설정한 것에 해당).

• ZLIB(또는 zlib가 감지된 AUTO)는 zlib 헤더의 값을 사용합니다.

• GZIP(또는 gzip가 감지된 AUTO)는 32킬로바이트를 사용합니다(wbits를 15로 설정한 것에 해당).

윈도우 크기, zlib, gzip 스트림에 대한 자세한 내용은 아래의 윈도우 크기 설명을 참조하세요.

close가 True로 설정되면 deflate.DeflateIO 스트림이 닫힐 때 기저 스트림이 자동으로 닫힙니다. 이는 다른 스트림을 래핑하는 deflate.DeflateIO 스트림을 반환하면서 호출자가 기저 스트림 관리에 대해 알 필요가 없게 하고 싶을 때 유용합니다.

압축이 활성화되어 있으면, 주어진 deflate.DeflateIO 인스턴스는 읽기와 쓰기를 모두 지원합니다. 예를 들어 소켓과 같은 양방향 스트림을 래핑할 수 있으며, 이를 통해 양방향으로 압축/압축 해제가 가능합니다.

상수

네 개의 format 상수는 raw deflate 비트 스트림 주위에 적용되는 프레이밍을 선택합니다.

deflate.AUTO: int

압축 해제 시에는 스트림의 첫 바이트를 검사하여 입력 형식(zlib 또는 gzip)을 자동 감지합니다. 압축 시에는 헤더나 트레일러가 없는 raw deflate 스트림을 생성합니다(RAW와 동일).

deflate.RAW: int

raw deflate 스트림입니다(헤더, 트레일러, 체크섬 없음). 스트림에 메타데이터가 없으므로 압축 해제기는 데이터로부터 윈도우 크기를 복구할 수 없습니다. 따라서 압축 해제 시 wbits를 명시적으로 설정해야 합니다. 그렇지 않으면 기본값인 256바이트 윈도우가 너무 작을 수 있습니다.

deflate.ZLIB: int

RFC 1950에 정의된 zlib로 래핑된 deflate 스트림입니다. 윈도우 크기를 기록하는 2바이트 헤더, deflate 페이로드, 그리고 뒤따르는 Adler-32 체크섬으로 구성됩니다. 간결하고 자기 기술적이어서 임베디드 용도에 적합합니다.

deflate.GZIP: int

RFC 1952에 정의된 gzip로 래핑된 deflate 스트림입니다. 선택적 파일명/타임스탬프 메타데이터를 가진 헤더, deflate 페이로드, 그리고 뒤따르는 CRC-32와 압축 해제된 길이로 구성됩니다. 이것은 gzip 명령줄 도구와 gzip.GzipFile이 생성하는 형식입니다. 헤더에 윈도우 크기가 기록되지 않으므로, wbits가 설정되지 않은 경우 압축 해제기는 32 KiB를 가정해야 합니다.

예제

deflate.DeflateIO의 일반적인 사용 사례는 스토리지에서 압축된 파일을 읽거나 쓰는 것입니다:

import deflate

# Writing a zlib-compressed stream (uses the default window size of 256 bytes).
with open("data.z", "wb") as f:
    with deflate.DeflateIO(f, deflate.ZLIB) as d:
        # Use d.write(...) etc

# Reading a zlib-compressed stream (auto-detect window size).
with open("data.z", "rb") as f:
    with deflate.DeflateIO(f, deflate.ZLIB) as d:
        # Use d.read(), d.readinto(), etc.

deflate.DeflateIO는 스트림이므로, 예를 들어 json.dump() 및 json.load()와 함께(그리고 스트림을 사용할 수 있는 다른 모든 곳에서) 사용할 수 있습니다:

import deflate, json

# Write a dictionary as JSON in gzip format, with a
# small (64 byte) window size.
config = { ... }
with open("config.gz", "wb") as f:
    with deflate.DeflateIO(f, deflate.GZIP, 6) as f:
        json.dump(config, f)

# Read back that dictionary.
with open("config.gz", "rb") as f:
    with deflate.DeflateIO(f, deflate.GZIP, 6) as f:
        config = json.load(f)

소스 데이터가 스트림 형식이 아닌 경우, io.BytesIO를 사용하여 deflate.DeflateIO와 함께 사용하기에 적합한 스트림으로 변환할 수 있습니다:

import deflate, io

# Decompress a bytes/bytearray value.
compressed_data = get_data_z()
with deflate.DeflateIO(io.BytesIO(compressed_data), deflate.ZLIB) as d:
    decompressed_data = d.read()

# Compress a bytes/bytearray value.
uncompressed_data = get_data()
stream = io.BytesIO()
with deflate.DeflateIO(stream, deflate.ZLIB) as d:
    d.write(uncompressed_data)
compressed_data = stream.getvalue()

Deflate 윈도우 크기

윈도우 크기는 (압축 해제)압축기가 스트림에서 얼마나 멀리 뒤로 참조할 수 있는지를 제한합니다. 윈도우 크기를 늘리면 압축률이 향상되지만, 더 많은 메모리가 필요하고 압축기가 느려집니다.

입력 스트림이 특정 윈도우 크기로 압축된 경우, 더 작은 윈도우 크기를 사용하는 DeflateIO는 압축 해제 도중 OSError로 실패합니다. 다만 이는 역참조가 실제로 압축 해제기의 윈도우 크기보다 더 멀리 뒤를 가리키는 경우에만 그렇습니다. 즉, 더 작은 윈도우 크기로도 압축 해제가 가능할 수 있습니다. 예를 들어 원본 압축 해제 데이터가 윈도우 크기보다 짧은 경우라면 당연히 가능합니다.

압축 해제

zlib 형식은 데이터를 압축하는 데 사용된 윈도우 크기를 지정하는 헤더를 포함합니다. 이는 이 스트림을 압축 해제하는 데 필요한 최대 윈도우 크기를 나타냅니다. 이 헤더 값이 지정된 wbits 값보다 작은 경우(또는 wbits가 설정되지 않은 경우), 헤더 값이 사용됩니다.

gzip 형식은 헤더에 윈도우 크기를 포함하지 않으며, 모든 gzip 압축기(예: gzip 유틸리티 또는 CPython의 gzip.GzipFile 구현)가 최대 윈도우 크기인 32kiB를 사용한다고 가정합니다. 이 때문에 wbits 매개변수가 설정되지 않으면 압축 해제기는 32 kiB 윈도우 크기(wbits를 15로 설정한 것에 해당)를 사용합니다. 즉, 임의의 gzip 스트림을 압축 해제할 수 있으려면 최소한 이만큼의 RAM이 사용 가능해야 합니다. 소스 데이터를 제어할 수 있다면, 대신 더 작은 윈도우 크기의 zlib 형식을 사용하는 것을 고려하세요.

raw 형식은 헤더가 없으므로 윈도우 크기에 대한 정보를 포함하지 않습니다. wbits가 설정되지 않으면 기본값인 256바이트 윈도우 크기가 사용되는데, 이는 특정 스트림에 충분히 크지 않을 수 있습니다. 따라서 raw 형식을 사용하는 경우 항상 wbits를 명시적으로 설정하는 것이 좋습니다.

압축

압축 시 MicroPython은 모든 형식에 대해 기본값으로 256바이트의 윈도우 크기를 사용합니다. 이는 최소한의 메모리 사용량과 빠른 압축 시간으로 적절한 수준의 압축을 제공하며, 어떤 압축 해제기에서도 동작하는 출력을 생성합니다.