io — giriş/çıkış akışları

Bu modül, stream (dosya benzeri) nesnelerinin ek türlerini ve yardımcı işlevleri içerir. Standart read/write/seek akış arayüzünü uygulayan bellek içi metin ve ikili arabelleklerle (StringIO, BytesIO) birlikte open() yerleşik işlevini sunar.

Kavramsal hiyerarşi

CPython’dan farkı

Akış temel sınıflarının kavramsal hiyerarşisi, bu bölümde açıklandığı gibi MicroPython’da basitleştirilmiştir.

Tüm somut sınıfların davranışı için bir temel oluşturan (soyut) temel akış sınıfları, CPython’da birkaç ikiliğe (ikili sınıflandırmalara) uyar. MicroPython’da bunlar bir miktar basitleştirilmiş ve daha yüksek verimlilik elde etmek ve kaynak tasarrufu sağlamak için örtük hale getirilmiştir.

CPython’daki önemli bir ikilik, arabelleksiz ve arabellekli akışlar arasındadır. MicroPython’da şu anda tüm akışlar arabelleksizdir. Bunun nedeni, tüm modern işletim sistemlerinin ve hatta birçok RTOS ile dosya sistemi sürücüsünün, arabelleğe almayı zaten kendi taraflarında gerçekleştirmesidir. Başka bir arabelleğe alma katmanı eklemek ters etki yaratır (“bufferbloat” olarak bilinen bir sorun) ve değerli belleği harcar. Yine de arabelleğe almanın faydalı olabileceği durumların hâlâ bulunduğunu unutmayın; bu nedenle ileride isteğe bağlı arabelleğe alma desteği ekleyebiliriz.

Ancak CPython’da bir başka önemli ikilik “arabellekli olma” ile bağlantılıdır; yani bir akışın kısa okuma/yazma işlemlerine yol açıp açmamasıdır. Kısa okuma, bir kullanıcının bir akıştan örneğin 10 bayt istemesine rağmen daha azını almasıdır; yazma için de benzer durum geçerlidir. CPython’da arabelleksiz akışlar otomatik olarak kısa işleme açıktır, arabellekli akışlar ise bunlara karşı garanti verir. Kısa okuma/yazma olmaması önemli bir özelliktir, çünkü daha özlü ve verimli programlar geliştirmeye olanak tanır; bu da MicroPython için son derece arzu edilen bir şeydir. Dolayısıyla, MicroPython arabellekli akışları desteklemese de, kısa işlem yapmayan akışları yine de sağlar. Kısa işlemlerin olup olmayacağı her bir sınıfın özel ihtiyaçlarına bağlıdır, ancak geliştiricilerin yukarıda belirtilen nedenlerle kısa işlem yapmayan davranışı tercih etmeleri kuvvetle tavsiye edilir. Örneğin, MicroPython soketleri kısa okuma/yazma işlemlerinden kaçınmayı garanti eder. Aslında, şu anda çekirdekte kısa işlem yapan bir akış sınıfı örneği yoktur ve böyle bir sınıf belirli donanımlara özgü olurdu.

Kısa işlem yapmayan davranış, bloklamayan akışlar söz konusu olduğunda zorlaşır; bloklayan ve bloklamayan davranış, MicroPython tarafından tam olarak desteklenen bir başka CPython ikiliğidir. Bloklamayan akışlar, verinin gelmesini veya yazılmasını asla beklemez; mümkün olanı okur/yazar ya da veri eksikliğini (veya veri yazma yeteneğinin eksikliğini) bildirir. Bu durum açıkça “kısa işlem yapmama” ilkesiyle çelişir ve gerçekten de bloklamayan arabellekli (ve dolayısıyla kısa işlem yapmayan) akışlar durumu CPython’da karmaşıktır; bazı yerlerde böyle bir birleşim yasaktır, bazı yerlerde tanımsızdır veya yalnızca belgelenmemiştir, bazı durumlarda ise ayrıntılı istisnalar üretir. MicroPython’da konu çok daha basittir: bloklamayan akışlar verimli asenkron işlemler için önemlidir, bu nedenle bu özellik “kısa işlem yapmama” özelliğinin önüne geçer. Dolayısıyla, bloklayan akışlar mümkün olduğunda kısa okuma/yazmadan kaçınırken (kısa okuma elde etmenin tek durumu dosyanın sonuna ulaşılması veya hata durumudur (ancak hatalar kısa veri döndürmez, istisna fırlatır)), bloklamayan akışlar işlemi bloklamaktan kaçınmak için kısa veri üretebilir.

Son ikilik, ikili ve metin akışları arasındadır. MicroPython elbette bunları destekler, ancak CPython’da metin akışları doğası gereği arabellekliyken MicroPython’da değildir. (Aslında bu, arabelleğe alma desteği ekleyebileceğimiz durumlardan biridir.)

Verimlilik açısından, MicroPython’ın yukarıdaki hiyerarşiye karşılık gelen soyut temel sınıflar sağlamadığını ve saf Python’da bir akış sınıfı uygulamanın veya alt sınıfını oluşturmanın mümkün olmadığını unutmayın.

İşlevler

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

Bir dosya açar. Yerleşik open() işlevi bu işleve takma ad olarak atanmıştır. mode parametresi her zaman desteklenir; diğer argümanlar için destek değişiklik gösterebilir.

Sınıflar

class io.IOBase

Akış (“dosya benzeri”) nesneleri için temel sınıf. Somut alt sınıflar aşağıdaki düşük seviyeli I/O yöntemlerini (readinto, write, ioctl) uygular; çalışma zamanı, bunların üzerine daha üst seviyeli akış protokolünü (read, readline, readlines, close, yineleme) inşa eder, böylece alt sınıf bu yöntemleri tanımlamasa bile her akış örneği onları destekler.

Uygulama yöntemleri (bunları bir alt sınıfta geçersiz kılın):

readinto(buf: bytearray) → int | None

Baytları yazılabilir buf arabelleğine okur. Okunan bayt sayısını, akışın sonunda 0 değerini veya (bloklamayan bir akış için) şu anda hiç veri yoksa None değerini döndürür.

write(buf: bytes) → int | None

buf içindeki baytları yazar. Yazılan bayt sayısını veya (bloklamayan bir akış için) yazma işlemi şu anda gerçekleştirilemiyorsa None değerini döndürür.

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

Alttaki akışı/aygıtı denetler. request, MP_STREAM_* istek kodlarından biridir. Başarı durumunda negatif olmayan bir değer, hata durumunda ise negatif bir errno değeri döndürür.

Akış protokolü yöntemleri (her akış örneğinde mevcuttur):

read(size: int = -1)

En fazla size bayt (veya metin modunda karakter) okur ve döndürür. size atlanırsa veya negatifse, akışın sonuna kadar okur. İkili akışlar için bytes, metin akışları için str döndürür; boş bir sonuç akışın sonunu gösterir.

readline(size: int = -1)

Bir satır okur ve döndürür; varsa sondaki yeni satır karakterini de içerir. size verilirse, en fazla size bayt (veya karakter) okunur. Akışın sonunda boş bir bytes / str döndürür.

readlines() → list

Akışın sonuna kadar okur ve her biri sondaki yeni satır karakterini içeren satırlardan oluşan bir list döndürür.

close() → None

Akışı kapatır ve alttaki tüm kaynakları serbest bırakır. Kapatılmış bir akış üzerinde yapılan işlemler OSError (veya bellek içi akışlar için ValueError) fırlatır.

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

Geçerli akış konumunu whence değerine göre offset bayt olarak değiştirir (0 = akışın başı, 1 = geçerli konum, 2 = akışın sonu). Yeni mutlak konumu döndürür. Aranabilir olmayan bir akışta OSError fırlatır.

tell() → int

Akıştaki geçerli mutlak konumu döndürür. seek(0, 1) ile eşdeğerdir.

flush() → None

Tüm yazma arabelleklerini boşaltarak bekleyen verileri alttaki aygıta veya dosyaya gönderir. Arabelleğe almayan akışlarda bir işlem yapmaz.

Bir akışı doğrudan yinelemek, her yinelemede bir satır verir; bu, boş satır olan akış-sonu işaretçisi döndürülene kadar bir döngüde readline() çağırmakla eşdeğerdir. Bir akış ayrıca bağlam yöneticisi protokolünü de destekler, böylece with open(...) as f: akışı otomatik olarak kapatır.

Not

MicroPython’ın akış modülü ayrıca, istek tamamen karşılanana kadar döngüye girmek yerine tek bir alttaki I/O çağrısı gerçekleştiren “1” son ekli C yardımcılarını (mp_stream_read1_obj, mp_stream_readinto1_obj ve mp_stream_write1_obj) sunar. Bunlar machine.UART gibi sınıflar tarafından kendi read / write işlevlerini uygulamak üzere dahili olarak kullanılır; ancak hiçbir standart akış sınıfı bunları Python’dan çağrılabilir read1 / readinto1 / write1 yöntemleri olarak bağlamaz.

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

Metin modunda giriş/çıkış için bellek içi dosya benzeri nesne (“t” değiştiricisiyle açılan normal bir dosyaya benzer). İlk içerik string parametresiyle belirtilebilir (normal bir dize olmalıdır). Örnekler ayrıca bağlam yöneticisi protokolünü de destekler (bir with ifadesinde kullanılabilir).

read(size: int = -1) → str

En fazla size karakter okur ve döndürür. size atlanırsa veya negatifse, kalan tüm içeriği okur ve döndürür.

readline(size: int = -1) → str

Bir satır okur ve döndürür. size verilirse, en fazla size karakter okunur.

readinto(buf: bytearray) → int

Önceden ayrılmış, yazılabilir buf arabelleğine okur ve okunan bayt sayısını döndürür.

write(s: str) → int

s dizesini yazar ve yazılan karakter sayısını döndürür.

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

Akış konumunu whence değerine göre offset olarak değiştirir (0 = baş, 1 = geçerli, 2 = son) ve yeni mutlak konumu döndürür.

tell() → int

Geçerli akış konumunu döndürür.

flush() → None

Yazma arabelleklerini boşaltır. Bellek içi bir akış için bu bir işlem yapmaz.

close() → None

Akışı kapatır ve alttaki arabelleği serbest bırakır. Kapatılmış bir akış üzerinde yapılan diğer işlemler ValueError fırlatır.

getvalue() → str

Alttaki arabelleğin geçerli içeriğini döndürür.

class io.StringIO(alloc_size: int)

En fazla alloc_size bayt tutacak şekilde önceden ayrılmış boş bir StringIO nesnesi oluşturur, böylece bu kadar baytın yazılması arabelleği yeniden tahsis etmez (bellek yetersizliği durumundan veya bellek parçalanmasından kaçınılır). Bu yapıcı, bir MicroPython uzantısıdır ve yalnızca özel durumlar ile sistem seviyesi kütüphaneler için önerilir, son kullanıcı uygulamaları için değil.

CPython’dan farkı

Bu yapıcı bir MicroPython uzantısıdır.

read(size: int = -1) → str

En fazla size karakter okur ve döndürür. size atlanırsa veya negatifse, kalan tüm içeriği okur ve döndürür.

readline(size: int = -1) → str

Bir satır okur ve döndürür. size verilirse, en fazla size karakter okunur.

readinto(buf: bytearray) → int

Önceden ayrılmış, yazılabilir buf arabelleğine okur ve okunan bayt sayısını döndürür.

write(s: str) → int

s dizesini yazar ve yazılan karakter sayısını döndürür.

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

Akış konumunu whence değerine göre offset olarak değiştirir (0 = baş, 1 = geçerli, 2 = son) ve yeni mutlak konumu döndürür.

tell() → int

Geçerli akış konumunu döndürür.

flush() → None

Yazma arabelleklerini boşaltır. Bellek içi bir akış için bu bir işlem yapmaz.

close() → None

Akışı kapatır ve alttaki arabelleği serbest bırakır. Kapatılmış bir akış üzerinde yapılan diğer işlemler ValueError fırlatır.

getvalue() → str

Alttaki arabelleğin geçerli içeriğini döndürür.

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

İkili modda giriş/çıkış için bellek içi dosya benzeri nesne (“b” değiştiricisiyle açılan normal bir dosyaya benzer). İlk içerik string parametresiyle belirtilebilir (bir bytes nesnesi olmalıdır). Örnekler ayrıca bağlam yöneticisi protokolünü de destekler (bir with ifadesinde kullanılabilir).

read(size: int = -1) → bytes

En fazla size bayt okur ve döndürür. size atlanırsa veya negatifse, kalan tüm içeriği okur ve döndürür.

readline(size: int = -1) → bytes

Bir satır okur ve döndürür. size verilirse, en fazla size bayt okunur.

readinto(buf: bytearray) → int

Önceden ayrılmış, yazılabilir buf arabelleğine okur ve okunan bayt sayısını döndürür.

write(b: bytes) → int

Bytes benzeri nesne b‘yi yazar ve yazılan bayt sayısını döndürür.

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

Akış konumunu whence değerine göre offset olarak değiştirir (0 = baş, 1 = geçerli, 2 = son) ve yeni mutlak konumu döndürür.

tell() → int

Geçerli akış konumunu döndürür.

flush() → None

Yazma arabelleklerini boşaltır. Bellek içi bir akış için bu bir işlem yapmaz.

close() → None

Akışı kapatır ve alttaki arabelleği serbest bırakır. Kapatılmış bir akış üzerinde yapılan diğer işlemler ValueError fırlatır.

getvalue() → bytes

Alttaki arabelleğin geçerli içeriğini döndürür.

class io.BytesIO(alloc_size: int)

En fazla alloc_size bayt tutacak şekilde önceden ayrılmış boş bir BytesIO nesnesi oluşturur, böylece bu kadar baytın yazılması arabelleği yeniden tahsis etmez (bellek yetersizliği durumundan veya bellek parçalanmasından kaçınılır). Bu yapıcı, bir MicroPython uzantısıdır ve yalnızca özel durumlar ile sistem seviyesi kütüphaneler için önerilir, son kullanıcı uygulamaları için değil.

CPython’dan farkı

Bu yapıcı bir MicroPython uzantısıdır.

read(size: int = -1) → bytes

En fazla size bayt okur ve döndürür. size atlanırsa veya negatifse, kalan tüm içeriği okur ve döndürür.

readline(size: int = -1) → bytes

Bir satır okur ve döndürür. size verilirse, en fazla size bayt okunur.

readinto(buf: bytearray) → int

Önceden ayrılmış, yazılabilir buf arabelleğine okur ve okunan bayt sayısını döndürür.

write(b: bytes) → int

Bytes benzeri nesne b‘yi yazar ve yazılan bayt sayısını döndürür.

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

Akış konumunu whence değerine göre offset olarak değiştirir (0 = baş, 1 = geçerli, 2 = son) ve yeni mutlak konumu döndürür.

tell() → int

Geçerli akış konumunu döndürür.

flush() → None

Yazma arabelleklerini boşaltır. Bellek içi bir akış için bu bir işlem yapmaz.

close() → None

Akışı kapatır ve alttaki arabelleği serbest bırakır. Kapatılmış bir akış üzerinde yapılan diğer işlemler ValueError fırlatır.

getvalue() → bytes

Alttaki arabelleğin geçerli içeriğini döndürür.