`deflate` — deflate-pakkaus ja -purku¶

Tämä moduuli mahdollistaa binääridatan pakkaamisen ja purkamisen DEFLATE-algoritmilla (käytetään yleisesti zlib-kirjastossa ja gzip-arkistoijassa). Lisätty MicroPython-versiossa v1.21.

Saatavuus OpenMV-tuetuilla korteilla:

Kortti	Purku	Pakkaus
OpenMV Cam N6	Kyllä	Ei
OpenMV AE3	Kyllä	Kyllä
OpenMV Cam RT1062	Kyllä	Kyllä
OpenMV Cam Pure Thermal	Kyllä	Ei
OpenMV Cam M4	Kyllä	Ei
OpenMV Cam M7	Kyllä	Ei
OpenMV Cam H7	Kyllä	Ei
OpenMV Cam H7 Plus	Kyllä	Ei
Arduino Giga	Kyllä	Ei
Arduino Portenta H7	Kyllä	Ei
Arduino Nicla Vision	Kyllä	Ei
Arduino Nano 33 BLE Sense	Kyllä	Ei
Arduino Nano RP2040 Connect	Kyllä	Ei

Luokat¶

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

Tällä luokalla voi kääriä stream-virran, joka on mikä tahansa virran kaltainen objekti, kuten tiedosto, soketti tai virta (mukaan lukien io.BytesIO). Se on itsessään virta ja toteuttaa standardimetodit read/readinto/write/close.

Virran stream on oltava estävä virta. Ei-estäviä virtoja ei tällä hetkellä tueta.

Parametri format voidaan asettaa mihin tahansa alla määriteltyyn vakioon, ja sen oletusarvo on AUTO, joka purkamisessa tunnistaa automaattisesti gzip- tai zlib-virrat ja pakkaamisessa tuottaa raakavirran.

Parametri wbits asettaa DEFLATE-sanakirjan ikkunakoon kaksikantaisen logaritmin. Esimerkiksi wbits-arvolla 10 ikkunakoko on 1024 tavua. Kelvolliset arvot ovat 5–15 mukaan lukien (vastaten 32–32k tavun ikkunakokoja).

Jos wbits on asetettu arvoon 0 (oletus), pakkaamisessa käytetään 256 tavun ikkunakokoa (ikään kuin wbits olisi 8). Purkamisessa se riippuu muodosta:

RAW käyttää 256 tavua (vastaten wbits-arvoa 8).
ZLIB (tai AUTO zlibin tunnistuessa) käyttää zlib-otsakkeen arvoa.
GZIP (tai AUTO gzipin tunnistuessa) käyttää 32 kilotavua (vastaten wbits-arvoa 15).

Katso alla olevat ikkunakoon huomautukset saadaksesi lisätietoja ikkunakoosta sekä zlib- ja gzip-virroista.

Jos close on asetettu arvoon True, taustalla oleva virta suljetaan automaattisesti, kun deflate.DeflateIO-virta suljetaan. Tämä on hyödyllistä, jos haluat palauttaa deflate.DeflateIO-virran, joka kääri toisen virran, ilman että kutsujan tarvitsee tietää taustalla olevan virran hallinnasta.

Jos pakkaus on käytössä, tietty deflate.DeflateIO-ilmentymä tukee sekä lukemista että kirjoittamista. Esimerkiksi kaksisuuntaisen virran, kuten soketin, voi kääriä, mikä mahdollistaa pakkauksen/purun molempiin suuntiin.

Vakiot¶

Neljä format-vakiota valitsevat raakaan deflate-bittivirtaan sovellettavan kehystyksen.

deflate.AUTO: int¶: Purkamisessa tunnistaa syötteen muodon automaattisesti tarkastamalla virran ensimmäiset tavut (zlib tai gzip). Pakkaamisessa tuottaa raakan deflate-virran ilman otsaketta tai loppuosaa (vastaa arvoa RAW).

deflate.RAW: int¶: Raaka deflate-virta (ei otsaketta, ei loppuosaa, ei tarkistussummaa). Koska virta ei sisällä metatietoja, purkaja ei voi palauttaa ikkunakokoa datasta, joten wbits on syytä asettaa nimenomaisesti purettaessa – muuten oletuksena oleva 256 tavun ikkuna voi olla liian pieni.

deflate.ZLIB: int¶: Zlib-käärimä deflate-virta, joka on määritelty standardissa RFC 1950: 2 tavun otsake, joka tallentaa ikkunakoon, deflate-hyötykuorma ja loppuun lisätty Adler-32-tarkistussumma. Tiivis ja itsensä kuvaava; sopii hyvin sulautettuun käyttöön.

deflate.GZIP: int¶: Gzip-käärimä deflate-virta, joka on määritelty standardissa RFC 1952: otsake, joka sisältää valinnaisen tiedostonimi-/aikaleimametatiedon, deflate-hyötykuorma sekä loppuun lisätty CRC-32 ja pakkaamattoman datan pituus. Tämä on muoto, jonka gzip-komentorivityökalu ja gzip.GzipFile tuottavat. Otsake ei tallenna ikkunakokoa, joten purkajan on oletettava 32 KiB, ellei wbits ole asetettu.

Esimerkkejä¶

deflate.DeflateIO-luokan tyypillinen käyttötapaus on pakatun tiedoston lukeminen tallennustilasta tai kirjoittaminen siihen:

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.

Koska deflate.DeflateIO on virta, sitä voi käyttää esimerkiksi yhdessä metodien json.dump() ja json.load() kanssa (ja kaikkialla muualla, missä virtoja voi käyttää):

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)

Jos lähdedatasi ei ole virtamuodossa, voit käyttää io.BytesIO-luokkaa muuntaaksesi sen virraksi, joka sopii käytettäväksi deflate.DeflateIO-luokan kanssa:

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-ikkunakoko¶

Ikkunakoko rajoittaa, kuinka kauas virrassa taaksepäin pakkaaja/purkaja voi viitata. Ikkunakoon kasvattaminen parantaa pakkausta, mutta vaatii enemmän muistia ja hidastaa pakkaajaa.

Jos syötevirta pakattiin tietyllä ikkunakoolla, DeflateIO pienemmällä ikkunakoolla epäonnistuu kesken purun poikkeuksella OSError, mutta vain jos jokin takaisinviittaus todella viittaa kauemmas taaksepäin kuin purkajan ikkunakoko. Tämä tarkoittaa, että purku pienemmällä ikkunakoolla saattaa olla mahdollista. Esimerkiksi näin olisi triviaalisti silloin, kun alkuperäinen pakkaamaton data on lyhyempi kuin ikkunakoko.

Purku¶

Zlib-muoto sisältää otsakkeen, joka määrittää datan pakkaamiseen käytetyn ikkunakoon. Tämä ilmaisee tämän virran purkamiseen tarvittavan enimmäisikkunakoon. Jos tämä otsakearvo on pienempi kuin määritetty wbits-arvo (tai jos wbits on asettamatta), käytetään otsakearvoa.

Gzip-muoto ei sisällä ikkunakokoa otsakkeessa ja olettaa, että kaikki gzip-pakkaajat (esim. gzip-apuohjelma tai CPythonin gzip.GzipFile-toteutus) käyttävät enimmäisikkunakokoa 32 kiB. Tästä syystä, jos wbits-parametria ei ole asetettu, purkaja käyttää 32 kiB:n ikkunakokoa (vastaten wbits-arvoa 15). Tämä tarkoittaa, että voidaksesi purkaa mielivaltaisen gzip-virran sinulla on oltava vähintään tämän verran RAM-muistia käytettävissä. Jos hallitset lähdedataa, harkitse sen sijaan zlib-muodon käyttöä pienemmällä ikkunakoolla.

Raakamuodossa ei ole otsaketta, eikä se siksi sisällä mitään tietoa ikkunakoosta. Jos wbits ei ole asetettu, oletusarvoksi tulee 256 tavun ikkunakoko, joka ei välttämättä ole riittävän suuri tietylle virralle. Siksi on suositeltavaa, että asetat wbits-arvon aina nimenomaisesti raakamuotoa käytettäessä.

Pakkaus¶

Pakkaamisessa MicroPython käyttää oletuksena 256 tavun ikkunakokoa kaikille muodoille. Tämä tarjoaa kohtuullisen pakkaustason vähäisellä muistinkäytöllä ja nopealla pakkausajalla sekä tuottaa tulostetta, joka toimii minkä tahansa purkajan kanssa.

deflate — deflate-pakkaus ja -purku¶