io — syöttö-/tulostusvirrat

Tämä moduuli sisältää lisää stream-tyyppisiä (tiedoston kaltaisia) objekteja sekä apufunktioita. Se tarjoaa sisäänrakennetun open()-funktion sekä muistinvaraiset teksti- ja binääripuskurit (StringIO, BytesIO), jotka toteuttavat standardin read/write/seek-virtaliittymän.

Käsitteellinen hierarkia

Ero CPythoniin

Virtojen kantaluokkien käsitteellistä hierarkiaa on yksinkertaistettu MicroPythonissa, kuten tässä osiossa kuvataan.

(Abstraktit) virtojen kantaluokat, jotka toimivat perustana kaikkien konkreettisten luokkien käyttäytymiselle, noudattavat CPythonissa muutamaa kahtiajakoa (parittaista luokittelua). MicroPythonissa niitä on jonkin verran yksinkertaistettu ja tehty implisiittisiksi paremman tehokkuuden saavuttamiseksi ja resurssien säästämiseksi.

Tärkeä kahtiajako CPythonissa on puskuroimattomien ja puskuroitujen virtojen välillä. MicroPythonissa kaikki virrat ovat tällä hetkellä puskuroimattomia. Tämä johtuu siitä, että kaikki nykyaikaiset käyttöjärjestelmät ja jopa monet RTOS-järjestelmät ja tiedostojärjestelmäajurit suorittavat jo puskurointia omalla puolellaan. Toisen puskurointikerroksen lisääminen on haitallista (ongelma tunnetaan nimellä ”bufferbloat”) ja vie arvokasta muistia. Huomaa, että puskurointi voi silti olla joissakin tapauksissa hyödyllistä, joten saatamme ottaa käyttöön valinnaisen puskurointituen myöhemmin.

CPythonissa toinen tärkeä kahtiajako liittyy ”puskuroituuteen” - siihen, voiko virrasta seurata lyhyitä luku-/kirjoitusoperaatioita vai ei. Lyhyt lukeminen tarkoittaa sitä, että käyttäjä pyytää virrasta esimerkiksi 10 tavua mutta saa vähemmän, ja vastaavasti kirjoituksissa. CPythonissa puskuroimattomat virrat ovat automaattisesti alttiita lyhyille operaatioille, kun taas puskuroidut takaavat suojan niitä vastaan. Lyhyiden luku-/kirjoitusoperaatioiden puuttuminen on tärkeä ominaisuus, sillä se mahdollistaa tiiviimpien ja tehokkaampien ohjelmien kehittämisen - mikä on erittäin toivottavaa MicroPythonille. Vaikka MicroPython ei siis tue puskuroituja virtoja, se tarjoaa silti lyhyistä operaatioista vapaita virtoja. Se, esiintyykö lyhyitä operaatioita vai ei, riippuu kunkin luokan tarpeista, mutta kehittäjiä suositellaan vahvasti suosimaan lyhyistä operaatioista vapaata käyttäytymistä edellä mainituista syistä. Esimerkiksi MicroPythonin sokettien taataan välttävän lyhyitä luku-/kirjoitusoperaatioita. Itse asiassa tällä hetkellä ytimessä ei ole yhtään esimerkkiä lyhyitä operaatioita käyttävästä virtaluokasta, ja tällainen luokka olisi tiettyyn laitteistoon sidottu.

Lyhyistä operaatioista vapaa käyttäytyminen muuttuu hankalaksi estämättömien virtojen tapauksessa; estävä vastaan estämätön käyttäytyminen on toinen CPythonin kahtiajako, jota MicroPython tukee täysin. Estämättömät virrat eivät koskaan odota datan saapumista tai kirjoittamista - ne lukevat/kirjoittavat sen mitä on mahdollista, tai ilmoittavat datan puutteesta (tai kyvyttömyydestä kirjoittaa dataa). Tämä on selvästi ristiriidassa ”lyhyistä operaatioista vapaan” käytännön kanssa, ja todellakin estämättömien puskuroitujen (ja siten lyhyistä operaatioista vapaiden) virtojen tapaus on CPythonissa mutkikas - joissakin paikoissa tällainen yhdistelmä on kielletty, joissakin se on määrittelemätön tai sitä ei ole dokumentoitu, ja joissakin tapauksissa se nostaa monisanaisia poikkeuksia. Asia on paljon yksinkertaisempi MicroPythonissa: estämättömät virrat ovat tärkeitä tehokkaalle asynkroniselle toiminnalle, joten tämä ominaisuus on etusijalla ”lyhyistä operaatioista vapaaseen” nähden. Vaikka estävät virrat välttävät lyhyitä luku-/kirjoitusoperaatioita aina kun mahdollista (ainoa tapa saada lyhyt lukutulos on tiedoston lopun saavuttaminen tai virhetilanne (mutta virheet eivät palauta lyhyttä dataa vaan nostavat poikkeuksia)), estämättömät virrat voivat tuottaa lyhyttä dataa välttääkseen operaation estymisen.

Viimeinen kahtiajako on binääri- ja tekstivirtojen välillä. MicroPython tukee näitä tietysti, mutta vaikka CPythonissa tekstivirrat ovat luonnostaan puskuroituja, MicroPythonissa ne eivät ole. (Tämä onkin yksi tapauksista, joiden vuoksi saatamme ottaa puskurointituen käyttöön.)

Huomaa, että tehokkuussyistä MicroPython ei tarjoa yllä olevaa hierarkiaa vastaavia abstrakteja kantaluokkia, eikä virtaluokkaa ole mahdollista toteuttaa tai periyttää puhtaalla Pythonilla.

Funktiot

io.open(name: str, mode: str = 'r', **kwargs) → Any

Avaa tiedoston. Sisäänrakennettu open()-funktio on tämän funktion alias. mode-parametria tuetaan aina; muiden argumenttien tuki voi vaihdella.

Luokat

class io.IOBase

Virtaobjektien (”tiedoston kaltaisten”) kantaluokka. Konkreettiset aliluokat toteuttavat alla olevat matalan tason I/O-metodit (readinto, write, ioctl); ajonaikainen ympäristö rakentaa korkeamman tason virtaprotokollan (read, readline, readlines, close, iterointi) niiden päälle, joten jokainen virtainstanssi tukee näitä metodeja vaikka aliluokka ei niitä määrittelisikään.

Toteutusmetodit (ohita nämä aliluokassa):

readinto(buf: bytearray) → int | None

Lukee tavuja kirjoitettavaan puskuriin buf. Palauttaa luettujen tavujen määrän, 0 virran lopussa, tai None jos dataa ei ole juuri nyt saatavilla (estämättömän virran tapauksessa).

write(buf: bytes) → int | None

Kirjoittaa tavut puskurista buf. Palauttaa kirjoitettujen tavujen määrän, tai None jos kirjoitusta ei voida juuri nyt suorittaa (estämättömän virran tapauksessa).

ioctl(request: int, arg: int) → int

Ohjaa taustalla olevaa virtaa/laitetta. request on yksi MP_STREAM_*-pyyntökoodeista. Palauttaa ei-negatiivisen arvon onnistuessaan, tai negatiivisen errno-arvon virhetilanteessa.

Virtaprotokollan metodit (saatavilla jokaisessa virtainstanssissa):

read(size: int = -1)

Lukee ja palauttaa enintään size tavua (tai merkkiä tekstitilassa). Jos size jätetään pois tai on negatiivinen, lukee virran loppuun asti. Palauttaa bytes binäärivirroille ja str tekstivirroille; tyhjä tulos osoittaa virran loppua.

readline(size: int = -1)

Lukee ja palauttaa yhden rivin, mukaan lukien rivinvaihtomerkin jos sellainen on. Jos size annetaan, luetaan enintään size tavua (tai merkkiä). Palauttaa tyhjän bytes / str virran lopussa.

readlines() → list

Lukee virran loppuun asti ja palauttaa rivien list-listan, jossa kullakin rivillä on rivinvaihtomerkki mukana.

close() → None

Sulkee virran ja vapauttaa taustalla olevat resurssit. Suljettuun virtaan kohdistuvat operaatiot nostavat OSError-poikkeuksen (tai ValueError-poikkeuksen muistinvaraisten virtojen tapauksessa).

seek(offset: int, whence: int = 0) → int

Muuttaa virran nykyisen sijainnin offset tavua suhteessa whence-arvoon (0 = virran alku, 1 = nykyinen sijainti, 2 = virran loppu). Palauttaa uuden absoluuttisen sijainnin. Nostaa OSError-poikkeuksen virralle, jota ei voi siirtää.

tell() → int

Palauttaa virran nykyisen absoluuttisen sijainnin. Vastaa kutsua seek(0, 1).

flush() → None

Tyhjentää mahdolliset kirjoituspuskurit työntäen odottavan datan taustalla olevaan laitteeseen tai tiedostoon. Ei tee mitään virroilla, jotka eivät puskuroi.

Virran iterointi suoraan tuottaa yhden rivin iteraatiota kohden – vastaa readline()-metodin kutsumista silmukassa, kunnes tyhjän rivin virran lopun vahti palautetaan. Virta tukee myös kontekstinhallintaprotokollaa, joten with open(...) as f: sulkee virran automaattisesti.

Muista

MicroPythonin virtamoduuli tarjoaa myös ”1”-päätteiset C-apufunktiot mp_stream_read1_obj, mp_stream_readinto1_obj ja mp_stream_write1_obj, jotka suorittavat yhden taustalla olevan I/O-kutsun sen sijaan, että ne silmukoisivat kunnes pyyntö on täysin täytetty. Niitä käyttävät sisäisesti luokat kuten machine.UART toteuttaakseen omat read / write -metodinsa – mutta mikään standardivirtaluokka ei sido niitä Pythonista kutsuttaviksi read1 / readinto1 / write1 -metodeiksi.

class io.StringIO(string: str = '')

Muistinvarainen tiedoston kaltainen objekti tekstitilan syöttöä/tulostusta varten (samankaltainen kuin tavallinen tiedosto, joka avataan ”t”-määreellä). Alkusisältö voidaan määrittää string-parametrilla (jonka tulisi olla tavallinen merkkijono). Instanssit tukevat myös kontekstinhallintaprotokollaa (käytettävissä with-lauseessa).

read(size: int = -1) → str

Lukee ja palauttaa enintään size merkkiä. Jos size jätetään pois tai on negatiivinen, lukee ja palauttaa kaiken jäljellä olevan sisällön.

readline(size: int = -1) → str

Lukee ja palauttaa yhden rivin. Jos size annetaan, luetaan enintään size merkkiä.

readinto(buf: bytearray) → int

Lukee esivaratuun, kirjoitettavaan puskuriin buf ja palauttaa luettujen tavujen määrän.

write(s: str) → int

Kirjoittaa merkkijonon s ja palauttaa kirjoitettujen merkkien määrän.

seek(offset: int, whence: int = 0) → int

Muuttaa virran sijainnin offset suhteessa whence-arvoon (0 = alku, 1 = nykyinen, 2 = loppu) ja palauttaa uuden absoluuttisen sijainnin.

tell() → int

Palauttaa virran nykyisen sijainnin.

flush() → None

Tyhjentää kirjoituspuskurit. Tämä ei tee mitään muistinvaraisella virralla.

close() → None

Sulkee virran ja vapauttaa taustalla olevan puskurin. Suljettuun virtaan kohdistuvat lisäoperaatiot nostavat ValueError-poikkeuksen.

getvalue() → str

Palauttaa taustalla olevan puskurin nykyisen sisällön.

class io.StringIO(alloc_size: int)

Luo tyhjän StringIO-objektin, joka on esivarattu sisältämään enintään alloc_size tavua, joten enintään tuon verran tavuja kirjoitettaessa puskuria ei varata uudelleen (välttäen muistin loppumistilanteen tai muistin pirstoutumisen). Tämä konstruktori on MicroPython-laajennus, jota suositellaan vain erikoistapauksiin ja järjestelmätason kirjastoihin, ei loppukäyttäjän sovelluksiin.

Ero CPythoniin

Tämä konstruktori on MicroPython-laajennus.

read(size: int = -1) → str

Lukee ja palauttaa enintään size merkkiä. Jos size jätetään pois tai on negatiivinen, lukee ja palauttaa kaiken jäljellä olevan sisällön.

readline(size: int = -1) → str

Lukee ja palauttaa yhden rivin. Jos size annetaan, luetaan enintään size merkkiä.

readinto(buf: bytearray) → int

Lukee esivaratuun, kirjoitettavaan puskuriin buf ja palauttaa luettujen tavujen määrän.

write(s: str) → int

Kirjoittaa merkkijonon s ja palauttaa kirjoitettujen merkkien määrän.

seek(offset: int, whence: int = 0) → int

Muuttaa virran sijainnin offset suhteessa whence-arvoon (0 = alku, 1 = nykyinen, 2 = loppu) ja palauttaa uuden absoluuttisen sijainnin.

tell() → int

Palauttaa virran nykyisen sijainnin.

flush() → None

Tyhjentää kirjoituspuskurit. Tämä ei tee mitään muistinvaraisella virralla.

close() → None

Sulkee virran ja vapauttaa taustalla olevan puskurin. Suljettuun virtaan kohdistuvat lisäoperaatiot nostavat ValueError-poikkeuksen.

getvalue() → str

Palauttaa taustalla olevan puskurin nykyisen sisällön.

class io.BytesIO(string: bytes = b'')

Muistinvarainen tiedoston kaltainen objekti binääritilan syöttöä/tulostusta varten (samankaltainen kuin tavallinen tiedosto, joka avataan ”b”-määreellä). Alkusisältö voidaan määrittää string-parametrilla (jonka tulisi olla bytes-objekti). Instanssit tukevat myös kontekstinhallintaprotokollaa (käytettävissä with-lauseessa).

read(size: int = -1) → bytes

Lukee ja palauttaa enintään size tavua. Jos size jätetään pois tai on negatiivinen, lukee ja palauttaa kaiken jäljellä olevan sisällön.

readline(size: int = -1) → bytes

Lukee ja palauttaa yhden rivin. Jos size annetaan, luetaan enintään size tavua.

readinto(buf: bytearray) → int

Lukee esivaratuun, kirjoitettavaan puskuriin buf ja palauttaa luettujen tavujen määrän.

write(b: bytes) → int

Kirjoittaa bytes-tyyppisen objektin b ja palauttaa kirjoitettujen tavujen määrän.

seek(offset: int, whence: int = 0) → int

Muuttaa virran sijainnin offset suhteessa whence-arvoon (0 = alku, 1 = nykyinen, 2 = loppu) ja palauttaa uuden absoluuttisen sijainnin.

tell() → int

Palauttaa virran nykyisen sijainnin.

flush() → None

Tyhjentää kirjoituspuskurit. Tämä ei tee mitään muistinvaraisella virralla.

close() → None

Sulkee virran ja vapauttaa taustalla olevan puskurin. Suljettuun virtaan kohdistuvat lisäoperaatiot nostavat ValueError-poikkeuksen.

getvalue() → bytes

Palauttaa taustalla olevan puskurin nykyisen sisällön.

class io.BytesIO(alloc_size: int)

Luo tyhjän BytesIO-objektin, joka on esivarattu sisältämään enintään alloc_size tavua, joten enintään tuon verran tavuja kirjoitettaessa puskuria ei varata uudelleen (välttäen muistin loppumistilanteen tai muistin pirstoutumisen). Tämä konstruktori on MicroPython-laajennus, jota suositellaan vain erikoistapauksiin ja järjestelmätason kirjastoihin, ei loppukäyttäjän sovelluksiin.

Ero CPythoniin

Tämä konstruktori on MicroPython-laajennus.

read(size: int = -1) → bytes

Lukee ja palauttaa enintään size tavua. Jos size jätetään pois tai on negatiivinen, lukee ja palauttaa kaiken jäljellä olevan sisällön.

readline(size: int = -1) → bytes

Lukee ja palauttaa yhden rivin. Jos size annetaan, luetaan enintään size tavua.

readinto(buf: bytearray) → int

Lukee esivaratuun, kirjoitettavaan puskuriin buf ja palauttaa luettujen tavujen määrän.

write(b: bytes) → int

Kirjoittaa bytes-tyyppisen objektin b ja palauttaa kirjoitettujen tavujen määrän.

seek(offset: int, whence: int = 0) → int

Muuttaa virran sijainnin offset suhteessa whence-arvoon (0 = alku, 1 = nykyinen, 2 = loppu) ja palauttaa uuden absoluuttisen sijainnin.

tell() → int

Palauttaa virran nykyisen sijainnin.

flush() → None

Tyhjentää kirjoituspuskurit. Tämä ei tee mitään muistinvaraisella virralla.

close() → None

Sulkee virran ja vapauttaa taustalla olevan puskurin. Suljettuun virtaan kohdistuvat lisäoperaatiot nostavat ValueError-poikkeuksen.

getvalue() → bytes

Palauttaa taustalla olevan puskurin nykyisen sisällön.