io — bemeneti/kimeneti adatfolyamok

Ez a modul a stream (fájlszerű) objektumok további típusait és segédfüggvényeket tartalmaz. Elérhetővé teszi a beépített open() függvényt, valamint a memóriában tárolt szöveges és bináris puffereket (StringIO, BytesIO), amelyek a szabványos read/write/seek adatfolyam-interfészt valósítják meg.

Fogalmi hierarchia

Eltérés a CPythontól

Az adatfolyam-alaposztályok fogalmi hierarchiája a MicroPythonban egyszerűsített, ahogy azt ez a szakasz ismerteti.

Az (absztrakt) adatfolyam-alaposztályok, amelyek az összes konkrét osztály viselkedésének alapját képezik, a CPythonban néhány dichotómiát (páronkénti osztályozást) követnek. A MicroPythonban ezek némileg egyszerűsítettek és implicitté váltak a nagyobb hatékonyság és az erőforrások megtakarítása érdekében.

A CPythonban fontos dichotómia a pufferelés nélküli és a pufferelt adatfolyamok közötti különbség. A MicroPythonban jelenleg minden adatfolyam pufferelés nélküli. Ennek oka, hogy minden modern operációs rendszer, sőt számos RTOS és fájlrendszer-illesztőprogram is már a maga oldalán végez pufferelést. Egy újabb pufferelési réteg hozzáadása kontraproduktív (ez a „bufferbloat” néven ismert probléma), és értékes memóriát foglal le. Vegye figyelembe, hogy vannak még olyan esetek, amikor a pufferelés hasznos lehet, ezért később bevezethetünk opcionális pufferelési támogatást.

A CPythonban azonban egy másik fontos dichotómia is kapcsolódik a „puffereltséghez” - mégpedig az, hogy egy adatfolyamon előfordulhatnak-e rövid olvasások/írások vagy sem. Rövid olvasásról akkor beszélünk, ha a felhasználó például 10 bájtot kér egy adatfolyamtól, de kevesebbet kap; ugyanez vonatkozik az írásokra is. A CPythonban a pufferelés nélküli adatfolyamok automatikusan ki vannak téve a rövid műveleteknek, míg a pufferelt adatfolyamok garantáltan védve vannak ellenük. A rövid olvasások/írások hiánya fontos tulajdonság, mivel lehetővé teszi tömörebb és hatékonyabb programok fejlesztését - ami a MicroPython esetében kifejezetten kívánatos. Így, bár a MicroPython nem támogatja a pufferelt adatfolyamokat, mégis biztosít rövid műveletek nélküli adatfolyamokat. Hogy lesznek-e rövid műveletek vagy sem, az az egyes osztályok igényeitől függ, de a fejlesztőknek erősen ajánljuk, hogy a fent ismertetett okok miatt a rövid műveletek nélküli viselkedést részesítsék előnyben. Például a MicroPython socketek garantáltan elkerülik a rövid olvasásokat/írásokat. Valójában jelenleg nincs példa rövid műveletes adatfolyam-osztályra a magban, és egy ilyen osztály egy adott hardverre lenne jellemző.

A rövid műveletek nélküli viselkedés bonyolulttá válik a nem blokkoló adatfolyamok esetén, ahol a blokkoló és a nem blokkoló viselkedés egy másik CPython-dichotómia, amelyet a MicroPython teljes mértékben támogat. A nem blokkoló adatfolyamok soha nem várnak az adatok megérkezésére vagy kiírására - annyit olvasnak/írnak, amennyit lehet, vagy jelzik az adatok (illetve az írási képesség) hiányát. Ez nyilvánvalóan ütközik a „rövid műveletek nélküli” szabállyal, és valóban, a nem blokkoló pufferelt (tehát rövid műveletek nélküli) adatfolyamok esete a CPythonban bonyolult - bizonyos helyeken az ilyen kombináció tiltott, máshol nem definiált vagy egyszerűen nem dokumentált, néhány esetben pedig részletes kivételeket vált ki. A MicroPythonban a dolog sokkal egyszerűbb: a nem blokkoló adatfolyamok fontosak a hatékony aszinkron műveletekhez, ezért ez a tulajdonság elsőbbséget élvez a „rövid műveletek nélkülivel” szemben. Így, míg a blokkoló adatfolyamok lehetőség szerint elkerülik a rövid olvasásokat/írásokat (rövid olvasás csak akkor fordulhat elő, ha a fájl végét éri el, vagy hiba esetén (de a hibák nem adnak vissza rövid adatot, hanem kivételeket váltanak ki)), a nem blokkoló adatfolyamok rövid adatot is előállíthatnak a művelet blokkolásának elkerülése érdekében.

Az utolsó dichotómia a bináris és a szöveges adatfolyamok közötti különbség. A MicroPython természetesen támogatja ezeket, de míg a CPythonban a szöveges adatfolyamok eredendően pufferelve vannak, a MicroPythonban nem. (Valóban, ez az egyik olyan eset, amely miatt bevezethetünk pufferelési támogatást.)

Vegye figyelembe, hogy a hatékonyság érdekében a MicroPython nem biztosít a fenti hierarchiának megfelelő absztrakt alaposztályokat, és nem lehetséges tiszta Pythonban adatfolyam-osztályt megvalósítani vagy abból leszármaztatni.

Függvények

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

Fájl megnyitása. A beépített open() függvény ennek a függvénynek az aliasa. A mode paraméter mindig támogatott; a többi argumentum támogatása változhat.

Osztályok

class io.IOBase

Az adatfolyam („fájlszerű”) objektumok alaposztálya. A konkrét alosztályok az alábbi alacsony szintű I/O-metódusokat (readinto, write, ioctl) valósítják meg; a futtatókörnyezet ezekre építi a magasabb szintű adatfolyam-protokollt (read, readline, readlines, close, iteráció), így minden adatfolyam-példány támogatja ezeket a metódusokat akkor is, ha az alosztály nem definiálja őket.

Megvalósítási metódusok (ezeket írja felül egy alosztályban):

readinto(buf: bytearray) → int | None

Bájtok beolvasása az írható buf pufferbe. Visszaadja a beolvasott bájtok számát, az adatfolyam végén 0-t, vagy None-t, ha jelenleg nincs elérhető adat (nem blokkoló adatfolyam esetén).

write(buf: bytes) → int | None

A buf-ban lévő bájtok kiírása. Visszaadja a kiírt bájtok számát, vagy None-t, ha az írás jelenleg nem hajtható végre (nem blokkoló adatfolyam esetén).

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

Az alapul szolgáló adatfolyam/eszköz vezérlése. A request a MP_STREAM_* kérelemkódok egyike. Sikeresség esetén nem negatív értéket, hiba esetén negatív errno értéket ad vissza.

Adatfolyam-protokoll metódusok (minden adatfolyam-példányon elérhetők):

read(size: int = -1)

Legfeljebb size bájt (vagy szöveges módban karakter) beolvasása és visszaadása. Ha a size nincs megadva vagy negatív, az olvasás az adatfolyam végéig tart. Bináris adatfolyamoknál bytes, szöveges adatfolyamoknál str típust ad vissza; az üres eredmény az adatfolyam végét jelzi.

readline(size: int = -1)

Egy sor beolvasása és visszaadása, beleértve a záró újsor karaktert, ha van ilyen. Ha a size meg van adva, legfeljebb size bájt (vagy karakter) kerül beolvasásra. Az adatfolyam végén üres bytes / str értéket ad vissza.

readlines() → list

Olvasás az adatfolyam végéig, és a sorok list típusú listájának visszaadása, mindegyik a záró újsorral együtt.

close() → None

Az adatfolyam lezárása és minden alapul szolgáló erőforrás felszabadítása. A lezárt adatfolyamon végzett műveletek OSError (vagy a memóriában tárolt adatfolyamok esetén ValueError) kivételt váltanak ki.

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

Az aktuális adatfolyam-pozíció megváltoztatása a whence-hez viszonyított offset bájtra (0 = az adatfolyam eleje, 1 = aktuális pozíció, 2 = az adatfolyam vége). Visszaadja az új abszolút pozíciót. Olyan adatfolyamon, amely nem támogatja a pozicionálást, OSError kivételt vált ki.

tell() → int

Az adatfolyamon belüli aktuális abszolút pozíció visszaadása. Egyenértékű a seek(0, 1) hívással.

flush() → None

Minden írási puffer kiürítése, a függőben lévő adatok kiküldése az alapul szolgáló eszközre vagy fájlba. Olyan adatfolyamokon, amelyek nem puffereinek, ez egy üres művelet.

Egy adatfolyam közvetlen iterálása iterációnként egy sort ad vissza – egyenértékű a readline() ciklusban történő hívásával, amíg az üres sorral jelzett adatfolyam-vég jelzés vissza nem érkezik. Az adatfolyam a kontextuskezelő protokollt is támogatja, így a with open(...) as f: automatikusan lezárja az adatfolyamot.

Megjegyzés

A MicroPython adatfolyam-modulja „1” utótaggal ellátott C-segédfüggvényeket is elérhetővé tesz (mp_stream_read1_obj, mp_stream_readinto1_obj és mp_stream_write1_obj), amelyek egyetlen alapul szolgáló I/O-hívást hajtanak végre ahelyett, hogy addig ciklusoznának, amíg a kérés teljesen ki nem szolgálódik. Ezeket belsőleg olyan osztályok használják, mint a machine.UART, hogy megvalósítsák saját read / write műveleteiket – de egyetlen szabványos adatfolyam-osztály sem köti hozzájuk Python-hívható read1 / readinto1 / write1 metódusként.

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

Memóriában tárolt, fájlszerű objektum szöveges módú bemenethez/kimenethez (hasonló egy normál, „t” módosítóval megnyitott fájlhoz). A kezdeti tartalom a string paraméterrel adható meg (amelynek normál karakterláncnak kell lennie). A példányok a kontextuskezelő protokollt is támogatják (használhatók with utasításban).

read(size: int = -1) → str

Legfeljebb size karakter beolvasása és visszaadása. Ha a size nincs megadva vagy negatív, az összes hátralévő tartalom beolvasása és visszaadása.

readline(size: int = -1) → str

Egy sor beolvasása és visszaadása. Ha a size meg van adva, legfeljebb size karakter kerül beolvasásra.

readinto(buf: bytearray) → int

Olvasás az előre lefoglalt, írható buf pufferbe, és a beolvasott bájtok számának visszaadása.

write(s: str) → int

Az s karakterlánc kiírása és a kiírt karakterek számának visszaadása.

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

Az adatfolyam-pozíció megváltoztatása a whence-hez viszonyított offset-re (0 = eleje, 1 = aktuális, 2 = vége), és az új abszolút pozíció visszaadása.

tell() → int

Az aktuális adatfolyam-pozíció visszaadása.

flush() → None

Az írási pufferek kiürítése. Ez memóriában tárolt adatfolyam esetén egy üres művelet.

close() → None

Az adatfolyam lezárása és az alapul szolgáló puffer felszabadítása. A lezárt adatfolyamon végzett további műveletek ValueError kivételt váltanak ki.

getvalue() → str

Az alapul szolgáló puffer aktuális tartalmának visszaadása.

class io.StringIO(alloc_size: int)

Egy üres StringIO objektum létrehozása, amely előre le van foglalva legfeljebb alloc_size bájt tárolására, így legfeljebb ennyi bájt kiírása nem foglalja újra a puffert (elkerülve a memóriahiányt vagy a memóriatöredezettséget). Ez a konstruktor egy MicroPython-bővítmény, amely csak speciális esetekhez és rendszerszintű könyvtárakhoz ajánlott, végfelhasználói alkalmazásokhoz nem.

Eltérés a CPythontól

Ez a konstruktor egy MicroPython-bővítmény.

read(size: int = -1) → str

Legfeljebb size karakter beolvasása és visszaadása. Ha a size nincs megadva vagy negatív, az összes hátralévő tartalom beolvasása és visszaadása.

readline(size: int = -1) → str

Egy sor beolvasása és visszaadása. Ha a size meg van adva, legfeljebb size karakter kerül beolvasásra.

readinto(buf: bytearray) → int

Olvasás az előre lefoglalt, írható buf pufferbe, és a beolvasott bájtok számának visszaadása.

write(s: str) → int

Az s karakterlánc kiírása és a kiírt karakterek számának visszaadása.

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

Az adatfolyam-pozíció megváltoztatása a whence-hez viszonyított offset-re (0 = eleje, 1 = aktuális, 2 = vége), és az új abszolút pozíció visszaadása.

tell() → int

Az aktuális adatfolyam-pozíció visszaadása.

flush() → None

Az írási pufferek kiürítése. Ez memóriában tárolt adatfolyam esetén egy üres művelet.

close() → None

Az adatfolyam lezárása és az alapul szolgáló puffer felszabadítása. A lezárt adatfolyamon végzett további műveletek ValueError kivételt váltanak ki.

getvalue() → str

Az alapul szolgáló puffer aktuális tartalmának visszaadása.

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

Memóriában tárolt, fájlszerű objektum bináris módú bemenethez/kimenethez (hasonló egy normál, „b” módosítóval megnyitott fájlhoz). A kezdeti tartalom a string paraméterrel adható meg (amelynek bytes objektumnak kell lennie). A példányok a kontextuskezelő protokollt is támogatják (használhatók with utasításban).

read(size: int = -1) → bytes

Legfeljebb size bájt beolvasása és visszaadása. Ha a size nincs megadva vagy negatív, az összes hátralévő tartalom beolvasása és visszaadása.

readline(size: int = -1) → bytes

Egy sor beolvasása és visszaadása. Ha a size meg van adva, legfeljebb size bájt kerül beolvasásra.

readinto(buf: bytearray) → int

Olvasás az előre lefoglalt, írható buf pufferbe, és a beolvasott bájtok számának visszaadása.

write(b: bytes) → int

A b bytes-szerű objektum kiírása és a kiírt bájtok számának visszaadása.

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

Az adatfolyam-pozíció megváltoztatása a whence-hez viszonyított offset-re (0 = eleje, 1 = aktuális, 2 = vége), és az új abszolút pozíció visszaadása.

tell() → int

Az aktuális adatfolyam-pozíció visszaadása.

flush() → None

Az írási pufferek kiürítése. Ez memóriában tárolt adatfolyam esetén egy üres művelet.

close() → None

Az adatfolyam lezárása és az alapul szolgáló puffer felszabadítása. A lezárt adatfolyamon végzett további műveletek ValueError kivételt váltanak ki.

getvalue() → bytes

Az alapul szolgáló puffer aktuális tartalmának visszaadása.

class io.BytesIO(alloc_size: int)

Egy üres BytesIO objektum létrehozása, amely előre le van foglalva legfeljebb alloc_size bájt tárolására, így legfeljebb ennyi bájt kiírása nem foglalja újra a puffert (elkerülve a memóriahiányt vagy a memóriatöredezettséget). Ez a konstruktor egy MicroPython-bővítmény, amely csak speciális esetekhez és rendszerszintű könyvtárakhoz ajánlott, végfelhasználói alkalmazásokhoz nem.

Eltérés a CPythontól

Ez a konstruktor egy MicroPython-bővítmény.

read(size: int = -1) → bytes

Legfeljebb size bájt beolvasása és visszaadása. Ha a size nincs megadva vagy negatív, az összes hátralévő tartalom beolvasása és visszaadása.

readline(size: int = -1) → bytes

Egy sor beolvasása és visszaadása. Ha a size meg van adva, legfeljebb size bájt kerül beolvasásra.

readinto(buf: bytearray) → int

Olvasás az előre lefoglalt, írható buf pufferbe, és a beolvasott bájtok számának visszaadása.

write(b: bytes) → int

A b bytes-szerű objektum kiírása és a kiírt bájtok számának visszaadása.

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

Az adatfolyam-pozíció megváltoztatása a whence-hez viszonyított offset-re (0 = eleje, 1 = aktuális, 2 = vége), és az új abszolút pozíció visszaadása.

tell() → int

Az aktuális adatfolyam-pozíció visszaadása.

flush() → None

Az írási pufferek kiürítése. Ez memóriában tárolt adatfolyam esetén egy üres művelet.

close() → None

Az adatfolyam lezárása és az alapul szolgáló puffer felszabadítása. A lezárt adatfolyamon végzett további műveletek ValueError kivételt váltanak ki.

getvalue() → bytes

Az alapul szolgáló puffer aktuális tartalmának visszaadása.