io -- 入出力ストリーム

このモジュールは、該当する :term:`CPython` モジュールのサブセットを実装しています。 詳しくはオリジナルの CPython ドキュメンテーションを参照してください: io.

このモジュールには stream (ファイルのような)オブジェクトの追加のデータ型とヘルパー関数が含まれています。

概念階層

CPython との違い

この章で説明するように、MicroPythonではストリームベースのクラスの概念的な階層が単純化されています。

(抽象)基底 stream クラスは、すべての具象クラスの動作の基礎となるものであり、CPython にある二分法(ペアワイズ分類)に固執しません。MicroPython では、これらは幾分単純化されていて、効率化とリソース節約のために暗黙的に役立ちます。

CPython の重要な二分法は、バッファされていないストリームとバッファされているストリームです。MicroPython では、すべてのストリームは現在バッファリングされていません。これは、すべての現代的な OS、さらには多くの RTOS やファイルシステムドライバーでさえも、すでにバッファリングが行われているからです。別のレイヤーにバッファリングを追加することは、生産性を低下させ("bufferbloat" という問題)、貴重なメモリを消費します。バッファリングが便利な場合もあるので、後でオプションのバッファリングサポートを導入するかもしれません。

しかし、CPython には別の重要な二分法もあり、それは「バッファされているか」と関連しています。ストリームが短い読み込み/書き込みを起こすかどうかです。短い読み取りとは、たとえばストリームから10バイトを要求しても、それより少ないデータを得ることです。短い書き込みについても同様です。CPython ではバッファリングされていないストリームは自動的に短い操作になる影響を受けますが、バッファされたストリームは要求したサイズを保証します。短くない読み込み/書き込みは重要な特性であり、より簡潔で効率的なプログラムを開発できるので、MicroPython にとっても非常に望ましいものです。したがって、MicroPython はバッファされたストリームをサポートしていませんが、短くない操作のストリームも提供します。短い操作の有無は、各クラスのニーズに応じて異なりますが、開発者は上記の理由により短くない操作を好むよう強く推奨します。たとえば、MicroPython のソケットは、短い読み取り/書き込みを避けることが保証されています。実際、現時点では、コアには短い操作のストリームクラスの例はなく、あるとすればポート固有のクラスとなります。そのような必要性はハードウェアの特性によって管理されます。

短くない操作の動作は、非ブロックストリームの場合はトリッキーであり、ブロックと非ブロックの動作は別の CPython での二分法です。この２つの動作は MicroPython で完全にサポートされています。非ブロックストリームは、データの到着または書き込みを待つことは決してありません。可能な限りデータの読み込み/書き込みを行うか、データの欠乏(あるいはデータ書き込み可能)の通知します。明らかに、これは「短くない操作」のポリシーと矛盾しています。実際、非ブロックバッファ(で短くない操作)のストリームは、CPython では面倒です。ものによって、そのような組み合わせは禁止されているか、未定義であり、文書化されていないものもあります。場合によっては冗長な例外が発生します。MicroPython では、非ブロックストリームが効率的な非同期操作にとって重要であるため、この特性は「短くない操作」に優先します。したがって、ストリームをブロックすると、可能な限り短い読み込み/書き込みが回避されます(ファイルの終わりに達した場合、またはエラーが発生した場合は短い読み込みを取得する唯一のケースですが、エラーは短いデータを返さず例外を発生させます)。非ブロックストリームは、動作をブロックしないように短いデータを生成する可能性があります。

残る二分法は、バイナリとテキストのストリームです。MicroPython はもちろんこれをサポートしていますが、CPython のテキストストリームが本質的にバッファされているのに対して MicroPython ではバッファしていません。(実際、これはバッファをサポートする可能正のある唯一のケースです)。

効率を上げるために、MicroPython は上記の階層に対応する抽象基底クラスを提供していないことに注意してください。純粋な Python にあるストリームクラスを実装またはサブクラス化することはできません。

関数

io.open(name, mode='r', **kwargs)

ファイルを開きます。組込みの open() 関数はこの関数の別名になります。すべての(ファイルシステムへのアクセスを提供する)ポートは、 mode パラメータをサポートする必要がありますが、他の引数のサポートはポートによって異なります。

クラス

class io.FileIO(...)

これは open(name, "rb") などでバイナリモードで開くファイルのデータ型です。このクラスを直接インスタンス化しないでください。

class io.TextIOWrapper(...)

これは open(name, "rt") などでテキストモードで開くファイルのデータ型です。このクラスを直接インスタンス化しないでください。

class io.StringIO([string])

class io.BytesIO([string])

入出力のためのメモリ内の疑似ファイルオブジェクト。 StringIO はテキストモードの I/O に使用されます("t" 修飾子で開かれた通常のファイルと同様)。 BytesIO はバイナリモードの I/O に使用されます("b" 修飾子で開かれた通常のファイルと同様)。この疑似ファイルオブジェクトの初期の内容は string パラメータで指定できます(StringIO では通常の文字列、 BytesIO ではバイト列オブジェクトでなければなりません)。このオブジェクトについては、通常のファイルのメソッドのすべて read(), write(), seek(), flush(), close() が使え、加えて以下のメソッドが使えます。

getvalue()

データを保持するバッファの現在の内容を取得します。

class io.StringIO(alloc_size)

class io.BytesIO(alloc_size)

alloc_size で指定したバイト数を保持するために事前に割り当てられた空の StringIO/BytesIO オブジェクトを作成します。つまり、その量のバイトを書き込んでもバッファの再割り当てにはつながりません。したがって、メモリ不足の状況に遭遇したり、メモリの断片化につながることはありません。これらのコンストラクタは MicroPython の拡張であり、エンドユーザーアプリケーションではなく、特別な場合およびシステムレベルのライブラリーでのみ使用することをお勧めします。

CPython との違い

これらのコンストラクタは MicroPython の拡張です。