ファイルオブジェクト

これらの 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 を送出します。

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)

Open path with the mode 'rb'. path must be a Python str object. The behavior of this function may be overridden by PyFile_SetOpenCodeHook() to allow for some preprocessing of the text.

This is analogous to io.open_code() in Python.

On success, this function returns a strong reference to a Python file object. On failure, this function returns NULL with an exception set.

Added in version 3.8.

PyObject *PyFile_OpenCode(const char *path)

Similar to PyFile_OpenCodeObject(), but path is a UTF-8 encoded const char*.

Added in version 3.8.

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

次に属します: Stable ABI.

Write object obj to file object p. The only supported flag for flags is Py_PRINT_RAW; if given, the str() of the object is written instead of the repr().

If obj is NULL, write the string "<NULL>".

Return 0 on success or -1 on failure; the appropriate exception will be set.

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

次に属します: Stable ABI.

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