ファイルオブジェクト

これらの 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)

Read a line from the C stream stream into the buffer buf, like the C standard library function fgets(), but treating all of \n, \r and \r\n as line endings (see universal newlines). Any \r or \r\n read from the stream is stored in buf as a single \n.

At most n - 1 characters are stored in buf; reading stops after a newline has been stored or when the end of the file is reached. The result is always null-terminated. stream should be opened in binary mode, so that the C library does not perform its own newline translation.

Return buf on success. Return NULL if no characters could be read, because stream is at end of file, a read error occurred, or n is less than 2. Like fgets(), this function does not distinguish between end of file and a read error, and it does not set an exception.

fobj exists only for backward compatibility and must be 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

The string literal "b", used to open files in binary mode. Exposed for backwards compatibility only.

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