io --- aliran input/output

Modul ini berisi tipe tambahan objek stream (mirip file) dan fungsi pembantu. Modul ini mengekspos builtin open() beserta buffer teks dan biner dalam memori (StringIO, BytesIO) yang mengimplementasikan antarmuka aliran standar read/write/seek.

Hierarki konseptual

Perbedaan dengan CPython

Hierarki konseptual dari kelas dasar aliran disederhanakan dalam MicroPython, seperti dijelaskan pada bagian ini.

Kelas dasar aliran (abstrak) yang menjadi fondasi perilaku semua kelas konkret mengikuti beberapa dikotomi (klasifikasi berpasangan) di CPython. Dalam MicroPython, dikotomi tersebut agak disederhanakan dan dibuat implisit untuk mencapai efisiensi yang lebih tinggi dan menghemat sumber daya.

Dikotomi penting dalam CPython adalah aliran tak-buffer vs aliran buffer. Dalam MicroPython, semua aliran saat ini tidak menggunakan buffer. Hal ini karena semua OS modern, bahkan banyak RTOS dan driver sistem file, sudah melakukan buffering di sisi mereka sendiri. Menambahkan lapisan buffer tambahan justru kontraproduktif (masalah yang dikenal sebagai "bufferbloat") dan menghabiskan memori yang berharga. Perlu dicatat bahwa masih ada kasus di mana buffering mungkin berguna, sehingga kami mungkin memperkenalkan dukungan buffering opsional di lain waktu.

Namun dalam CPython, dikotomi penting lainnya terkait dengan "buffered" adalah apakah suatu aliran dapat mengalami short read/write atau tidak. Short read terjadi ketika pengguna meminta misalnya 10 byte dari aliran tetapi mendapatkan lebih sedikit, begitu pula untuk write. Dalam CPython, aliran tak-buffer secara otomatis rentan terhadap operasi singkat, sementara aliran buffer menjamin tidak ada hal itu. Tidak ada short read/write merupakan sifat penting karena memungkinkan pengembangan program yang lebih ringkas dan efisien -- sesuatu yang sangat diinginkan untuk MicroPython. Maka, meskipun MicroPython tidak mendukung aliran buffer, ia tetap menyediakan aliran tanpa operasi-singkat. Ada atau tidaknya operasi singkat bergantung pada kebutuhan masing-masing kelas, namun pengembang sangat disarankan untuk mendukung perilaku tanpa operasi-singkat dengan alasan yang telah disebutkan. Sebagai contoh, socket MicroPython dijamin menghindari short read/write. Sebenarnya, saat ini tidak ada contoh kelas aliran dengan operasi singkat di inti MicroPython, dan kelas semacam itu akan bersifat spesifik terhadap perangkat keras tertentu.

Perilaku tanpa operasi-singkat menjadi rumit pada aliran non-blocking, di mana perilaku blocking vs non-blocking adalah dikotomi CPython lain yang sepenuhnya didukung oleh MicroPython. Aliran non-blocking tidak pernah menunggu data tiba maupun ditulis -- mereka membaca/menulis sebanyak yang memungkinkan, atau memberi sinyal kekurangan data (atau kemampuan menulis data). Hal ini jelas bertentangan dengan kebijakan "tanpa operasi-singkat", dan memang kombinasi aliran non-blocking yang dibuffer (dan tanpa operasi-singkat) cukup rumit di CPython -- di beberapa tempat kombinasi tersebut dilarang, di tempat lain tidak terdefinisi atau tidak terdokumentasi, dan di beberapa kasus menimbulkan exception yang bertele-tele. Masalah ini jauh lebih sederhana di MicroPython: aliran non-blocking penting untuk operasi asinkron yang efisien, sehingga properti ini lebih diutamakan daripada "tanpa operasi-singkat". Jadi, meskipun aliran blocking akan menghindari short read/write sedapat mungkin (satu-satunya kasus short read adalah ketika akhir file tercapai, atau saat terjadi error (namun error tidak mengembalikan data singkat, melainkan melempar exception)), aliran non-blocking mungkin menghasilkan data singkat untuk menghindari pemblokiran operasi.

Dikotomi terakhir adalah aliran biner vs teks. MicroPython tentu saja mendukung keduanya, tetapi sementara aliran teks di CPython secara inheren menggunakan buffer, di MicroPython tidak demikian. (Ini adalah salah satu kasus yang menjadi alasan kami mungkin memperkenalkan dukungan buffering.)

Perlu dicatat bahwa demi efisiensi, MicroPython tidak menyediakan kelas dasar abstrak yang sesuai dengan hierarki di atas, dan tidak mungkin untuk mengimplementasikan atau membuat subkelas dari kelas aliran dalam Python murni.

Fungsi

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

Buka file. Fungsi builtin open() dialihkan ke fungsi ini. Parameter mode selalu didukung; dukungan untuk argumen lain dapat bervariasi.

Kelas

class io.IOBase

Kelas dasar untuk objek aliran ("mirip file"). Subkelas konkret mengimplementasikan metode I/O tingkat rendah berikut (readinto, write, ioctl); runtime membangun protokol aliran tingkat tinggi (read, readline, readlines, close, iterasi) di atasnya, sehingga setiap instans aliran mendukung metode tersebut bahkan ketika subkelas tidak mendefinisikannya.

Metode implementasi (timpa ini di subkelas):

readinto(buf: bytearray) → int | None

Baca byte ke dalam buffer buf yang dapat ditulis. Kembalikan jumlah byte yang dibaca, 0 di akhir aliran, atau None jika tidak ada data yang tersedia saat ini (untuk aliran non-blocking).

write(buf: bytes) → int | None

Tulis byte dalam buf. Kembalikan jumlah byte yang ditulis, atau None jika penulisan tidak dapat dilakukan saat ini (untuk aliran non-blocking).

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

Kendalikan aliran/perangkat yang mendasari. request adalah salah satu kode permintaan MP_STREAM_*. Kembalikan nilai non-negatif jika berhasil, atau nilai errno negatif jika terjadi error.

Metode protokol aliran (tersedia pada setiap instans aliran):

read(size: int = -1)

Baca dan kembalikan hingga size byte (atau karakter, dalam mode teks). Jika size dihilangkan atau negatif, baca hingga akhir aliran. Mengembalikan bytes untuk aliran biner dan str untuk aliran teks; hasil kosong menandakan akhir aliran.

readline(size: int = -1)

Baca dan kembalikan satu baris, termasuk karakter baris baru di akhir jika ada. Jika size diberikan, maksimal size byte (atau karakter) yang dibaca. Mengembalikan bytes / str kosong di akhir aliran.

readlines() → list

Baca hingga akhir aliran dan kembalikan list berisi baris-baris, masing-masing dengan karakter baris baru di akhirnya.

close() → None

Tutup aliran dan lepaskan semua sumber daya yang mendasarinya. Operasi pada aliran yang telah ditutup akan memunculkan OSError (atau ValueError untuk aliran dalam memori).

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

Ubah posisi aliran saat ini ke offset byte relatif terhadap whence (0 = awal aliran, 1 = posisi saat ini, 2 = akhir aliran). Kembalikan posisi absolut baru. Memunculkan OSError pada aliran yang tidak dapat di-seek.

tell() → int

Kembalikan posisi absolut saat ini dalam aliran. Setara dengan seek(0, 1).

flush() → None

Flush semua buffer tulis, mendorong data yang tertunda ke perangkat atau file yang mendasarinya. Merupakan no-op pada aliran yang tidak melakukan buffering.

Iterasi aliran secara langsung menghasilkan satu baris per iterasi -- setara dengan memanggil readline() dalam loop hingga sentinel akhir aliran berupa baris kosong dikembalikan. Aliran juga mendukung protokol context-manager, sehingga with open(...) as f: menutup aliran secara otomatis.

Catatan

Modul aliran MicroPython juga mengekspos helper C dengan akhiran "1": mp_stream_read1_obj, mp_stream_readinto1_obj, dan mp_stream_write1_obj yang melakukan satu panggilan I/O yang mendasari alih-alih mengulang hingga permintaan terpenuhi sepenuhnya. Helper ini digunakan secara internal oleh kelas seperti machine.UART untuk mengimplementasikan read / write mereka sendiri -- tetapi tidak ada kelas aliran standar yang mengikatnya sebagai metode Python yang dapat dipanggil read1 / readinto1 / write1.

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

Objek mirip file dalam memori untuk input/output mode teks (mirip file normal yang dibuka dengan modifier "t"). Konten awal dapat ditentukan dengan parameter string (yang harus berupa string biasa). Instans juga mendukung protokol context-manager (dapat digunakan dalam pernyataan with).

read(size: int = -1) → str

Baca dan kembalikan hingga size karakter. Jika size dihilangkan atau negatif, baca dan kembalikan semua konten yang tersisa.

readline(size: int = -1) → str

Baca dan kembalikan satu baris. Jika size diberikan, maksimal size karakter yang dibaca.

readinto(buf: bytearray) → int

Baca ke dalam buffer buf yang telah dialokasikan dan dapat ditulis, dan kembalikan jumlah byte yang dibaca.

write(s: str) → int

Tulis string s dan kembalikan jumlah karakter yang ditulis.

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

Ubah posisi aliran ke offset relatif terhadap whence (0 = awal, 1 = saat ini, 2 = akhir) dan kembalikan posisi absolut baru.

tell() → int

Kembalikan posisi aliran saat ini.

flush() → None

Flush buffer tulis. Ini adalah no-op untuk aliran dalam memori.

close() → None

Tutup aliran dan bebaskan buffer yang mendasarinya. Operasi lebih lanjut pada aliran yang telah ditutup akan memunculkan ValueError.

getvalue() → str

Kembalikan konten saat ini dari buffer yang mendasarinya.

class io.StringIO(alloc_size: int)

Buat objek StringIO kosong yang telah dialokasikan sebelumnya untuk menampung hingga alloc_size byte, sehingga penulisan hingga sebanyak itu tidak akan mengalokasikan ulang buffer (menghindari situasi kehabisan memori atau fragmentasi memori). Konstruktor ini adalah ekstensi MicroPython yang hanya direkomendasikan untuk kasus khusus dan pustaka tingkat sistem, bukan untuk aplikasi pengguna akhir.

Perbedaan dengan CPython

Konstruktor ini adalah ekstensi MicroPython.

read(size: int = -1) → str

Baca dan kembalikan hingga size karakter. Jika size dihilangkan atau negatif, baca dan kembalikan semua konten yang tersisa.

readline(size: int = -1) → str

Baca dan kembalikan satu baris. Jika size diberikan, maksimal size karakter yang dibaca.

readinto(buf: bytearray) → int

Baca ke dalam buffer buf yang telah dialokasikan dan dapat ditulis, dan kembalikan jumlah byte yang dibaca.

write(s: str) → int

Tulis string s dan kembalikan jumlah karakter yang ditulis.

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

Ubah posisi aliran ke offset relatif terhadap whence (0 = awal, 1 = saat ini, 2 = akhir) dan kembalikan posisi absolut baru.

tell() → int

Kembalikan posisi aliran saat ini.

flush() → None

Flush buffer tulis. Ini adalah no-op untuk aliran dalam memori.

close() → None

Tutup aliran dan bebaskan buffer yang mendasarinya. Operasi lebih lanjut pada aliran yang telah ditutup akan memunculkan ValueError.

getvalue() → str

Kembalikan konten saat ini dari buffer yang mendasarinya.

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

Objek mirip file dalam memori untuk input/output mode biner (mirip file normal yang dibuka dengan modifier "b"). Konten awal dapat ditentukan dengan parameter string (yang harus berupa objek bytes). Instans juga mendukung protokol context-manager (dapat digunakan dalam pernyataan with).

read(size: int = -1) → bytes

Baca dan kembalikan hingga size byte. Jika size dihilangkan atau negatif, baca dan kembalikan semua konten yang tersisa.

readline(size: int = -1) → bytes

Baca dan kembalikan satu baris. Jika size diberikan, maksimal size byte yang dibaca.

readinto(buf: bytearray) → int

Baca ke dalam buffer buf yang telah dialokasikan dan dapat ditulis, dan kembalikan jumlah byte yang dibaca.

write(b: bytes) → int

Tulis objek bytes-like b dan kembalikan jumlah byte yang ditulis.

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

Ubah posisi aliran ke offset relatif terhadap whence (0 = awal, 1 = saat ini, 2 = akhir) dan kembalikan posisi absolut baru.

tell() → int

Kembalikan posisi aliran saat ini.

flush() → None

Flush buffer tulis. Ini adalah no-op untuk aliran dalam memori.

close() → None

Tutup aliran dan bebaskan buffer yang mendasarinya. Operasi lebih lanjut pada aliran yang telah ditutup akan memunculkan ValueError.

getvalue() → bytes

Kembalikan konten saat ini dari buffer yang mendasarinya.

class io.BytesIO(alloc_size: int)

Buat objek BytesIO kosong yang telah dialokasikan sebelumnya untuk menampung hingga alloc_size byte, sehingga penulisan hingga sebanyak itu tidak akan mengalokasikan ulang buffer (menghindari situasi kehabisan memori atau fragmentasi memori). Konstruktor ini adalah ekstensi MicroPython yang hanya direkomendasikan untuk kasus khusus dan pustaka tingkat sistem, bukan untuk aplikasi pengguna akhir.

Perbedaan dengan CPython

Konstruktor ini adalah ekstensi MicroPython.

read(size: int = -1) → bytes

Baca dan kembalikan hingga size byte. Jika size dihilangkan atau negatif, baca dan kembalikan semua konten yang tersisa.

readline(size: int = -1) → bytes

Baca dan kembalikan satu baris. Jika size diberikan, maksimal size byte yang dibaca.

readinto(buf: bytearray) → int

Baca ke dalam buffer buf yang telah dialokasikan dan dapat ditulis, dan kembalikan jumlah byte yang dibaca.

write(b: bytes) → int

Tulis objek bytes-like b dan kembalikan jumlah byte yang ditulis.

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

Ubah posisi aliran ke offset relatif terhadap whence (0 = awal, 1 = saat ini, 2 = akhir) dan kembalikan posisi absolut baru.

tell() → int

Kembalikan posisi aliran saat ini.

flush() → None

Flush buffer tulis. Ini adalah no-op untuk aliran dalam memori.

close() → None

Tutup aliran dan bebaskan buffer yang mendasarinya. Operasi lebih lanjut pada aliran yang telah ditutup akan memunculkan ValueError.

getvalue() → bytes

Kembalikan konten saat ini dari buffer yang mendasarinya.