File objects

これらの API は、 Python 2 の組み込みのファイルオブジェクトの C API を最低限エミュレートするためのものです。それらは、標準 C ライブラリでサポートされているバッファ付き I/O (FILE*) に頼るために使われます。 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 の場合、行の長さに関係なく正確に 1 行だけ読み出します。 n が 0 より大きければ、 n バイト以上のデータは読み出しません; 従って、行の一部だけが返される場合があります。 どちらの場合でも、読み出し後すぐにファイルの終端に到達した場合には空文字列を 返します。 n が 0 より小さければ、長さに関わらず 1 行だけを 読み出しますが、すぐにファイルの終端に到達した場合には 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)

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 を返して適切な例外をセットします。

Soft-deprecated API

Soft deprecated since version 3.15.

These are APIs that were included in Python's C API by mistake. They are documented solely for completeness; use other PyFile* APIs instead.

PyObject *PyFile_NewStdPrinter(int fd)

Use PyFile_FromFd() with defaults (fd, NULL, "w", -1, NULL, NULL, NULL, 0) instead.

PyTypeObject PyStdPrinter_Type

Type of file-like objects used internally at Python startup when io is not yet available. Use Python open() or PyFile_FromFd() to create file objects instead.