ファイルオブジェクト
********************

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