ファイルオブジェクト

これらの API は、C 標準ライブラリのバッファ付き I/O (FILE*) に依存していた Python 2 の組み込みファイルオブジェクトの C API を、最小限エミュレートするものです。 Python 3 のファイルやストリームは新しい io モジュールを使います。 このモジュールは、OS の低水準なバッファなし I/O の上に複数の層を定義しています。 以下の関数は、これらの新しい API を包む便利な C ラッパーで、主にインタープリタ内部でのエラー報告を目的としています。 サードパーティのコードでは、代わりに io の API を使うことを推奨します。

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)

戻り値: 新しい参照。 次に属します: Stable ABI.

既に開かれているファイル fd のファイルディスクリプタから Python のファイルオブジェクトを作成します。 引数 name 、 encoding 、 errors 、 newline には、デフォルトの値として NULL が使えます。 buffering には -1 を指定してデフォルトの値を使うことができます。 name は無視されるのですが、後方互換性のために残されています。 失敗すると NULL を返します。 より包括的な引数の解説は、 io.open() 関数のドキュメントを参照してください。

警告

Python のストリームは独自のバッファリング層を持つため、OS レベルのファイルディスクリプタと混在させると、データの順序が予想外になるなどの問題が起きる可能性があります。

バージョン 3.2 で変更: name 属性の無視。

int PyObject_AsFileDescriptor(PyObject *p)

次に属します: Stable ABI.

p に関連づけられる ファイルディスクリプタを int として返します。オブジェクトが整数なら、その値を返します。 整数でない場合、オブジェクトに fileno() メソッドがあれば呼び出します; このメソッドの返り値は、ファイル記述子の値として返される整数でなければなりません。失敗すると例外を設定して -1 を返します。

PyObject *PyFile_GetLine(PyObject *p, int n)

戻り値: 新しい参照。 次に属します: Stable ABI.

p.readline([n]) に相当し、オブジェクト p から一行を読み込みます。 p はファイルオブジェクトでも、readline() メソッドを持つ任意のオブジェクトでも構いません。 n が 0 なら、長さにかかわらず一行を読み込みます。 n が 0 より大きければ、ファイルから読み込むのは最大 n バイトで、行の一部だけを返す場合があります。 いずれの場合も、最初からファイルの終端に達していれば空文字列を返します。 一方、n が 0 より小さければ、長さにかかわらず一行を読み込みますが、最初からファイルの終端に達している場合は EOFError を送出します。

char *Py_UniversalNewlineFgets(char *buf, int n, FILE *stream, PyObject *fobj)

C 標準ライブラリ関数 fgets() と同様に、C ストリーム stream から一行をバッファ buf に読み込みますが、\n、\r、\r\n のすべてを行末として扱います (ユニバーサル改行 を参照)。 ストリームから読み込んだ \r や \r\n は、単一の \n として buf に格納します。

buf に格納するのは最大 n - 1 文字です。 改行を格納するかファイルの終端に達すると、読み込みを停止します。 結果は常にヌル終端されます。 C ライブラリが独自に改行を変換しないよう、stream はバイナリモードで開いてください。

成功すると buf を返します。 stream がファイルの終端にある場合、読み込みエラーが起きた場合、n が 2 未満の場合など、一文字も読み込めなければ NULL を返します。 fgets() と同様に、この関数はファイルの終端と読み込みエラーを区別せず、例外も設定しません。

fobj は後方互換性のためだけに残されており、NULL でなければなりません。

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

io.open_code() の通常の振る舞いを上書きして、そのパラメーターを提供されたハンドラで渡します。

ハンドラーは次の型の関数です。

typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)

PyObject *(*)(PyObject *path, void *userData) と等価で、 path は PyUnicodeObject であることが保証されています。

userData ポインタはフック関数に渡されます。 フック関数は別なランタイムから呼び出されるかもしれないので、このポインタは直接 Python の状態を参照すべきではありません。

このフック関数はインポート中に使われることを意図しているため、モジュールが frozen なモジュールであるか sys.modules にある利用可能なモジュールであることが分かっている場合を除いては、フック関数の実行中に新しいモジュールをインポートするのは避けてください。

いったんフックを設定すると、削除も置き換えもできず、その後の PyFile_SetOpenCodeHook() の呼び出しは失敗します。 失敗すると -1 を返し、インタープリタが初期化済みの場合は例外も設定します。

この関数は Py_Initialize() より前に呼び出しても安全です。

引数無しで 監査イベント setopencodehook を送出します。

Added in version 3.8.

PyObject *PyFile_OpenCodeObject(PyObject *path)

path を 'rb' モードで開きます。 path は Python の str オブジェクトでなければなりません。 PyFile_SetOpenCodeHook() でこの関数の動作を変更すると、テキストに前処理を加えられます。

Python の io.open_code() に相当します。

成功すると、Python のファイルオブジェクトへの 強参照 を返します。 失敗すると、例外を設定して NULL を返します。

Added in version 3.8.

PyObject *PyFile_OpenCode(const char *path)

PyFile_OpenCodeObject() と似ていますが、path は UTF-8 でエンコードされた const char* です。

Added in version 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

次に属します: Stable ABI.

オブジェクト obj をファイルオブジェクト p に書き出します。 flags でサポートするフラグは Py_PRINT_RAW だけです。 指定した場合、オブジェクトの repr() ではなく str() の結果を書き出します。

obj が NULL の場合、文字列 "<NULL>" を書き出します。

成功すると 0 を返し、失敗すると適切な例外を設定して -1 を返します。

int PyFile_WriteString(const char *s, PyObject *p)

次に属します: Stable ABI.

文字列 s をファイルオブジェクト p に書き出します。成功した場合には 0 を返し、失敗すると -1 を返して適切な例外をセットします。

ソフト非推奨の API

これらは誤って Python の C API に含めてしまった API です。 網羅性のためだけに記載しており、代わりに他の PyFile* API を使ってください。

PyObject *PyFile_NewStdPrinter(int fd)

代わりに、デフォルト値 (fd, NULL, "w", -1, NULL, NULL, NULL, 0) で PyFile_FromFd() を使ってください。

バージョン 3.15 で ソフト非推奨 <Soft deprecated>.

PyTypeObject PyStdPrinter_Type

Python の起動時に io がまだ利用できない間、内部で使うファイルライクオブジェクトの型です。 ファイルオブジェクトの作成には、代わりに Python の open() または PyFile_FromFd() を使ってください。

バージョン 3.15 で ソフト非推奨 <Soft deprecated>.

PY_STDIOTEXTMODE

ファイルをバイナリモードで開くための文字列リテラル "b" です。 後方互換性のためだけに公開されています。

バージョン 3.15.2 で ソフト非推奨 <Soft deprecated>.