Objets fichiers
***************

These APIs are a minimal emulation of the Python 2 C API for built-in
file objects, which used to rely on the buffered I/O (FILE*) support
from the C standard library.  In Python 3, files and streams use the
new "io" module, which defines several layers over the low-level
unbuffered I/O of the operating system.  The functions described below
are convenience C wrappers over these new APIs, and meant mostly for
internal error reporting in the interpreter; third-party code is
advised to access the "io" APIs instead.

PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
    *Valeur de retour : nouvelle référence.** Part of the Stable ABI.*

   Create a Python file object from the file descriptor of an already
   opened file *fd*.  The arguments *name*, *encoding*, *errors* and
   *newline* can be "NULL" to use the defaults; *buffering* can be
   *-1* to use the default. *name* is ignored and kept for backward
   compatibility. Return "NULL" on failure. For a more comprehensive
   description of the arguments, please refer to the "io.open()"
   function documentation.

   Avertissement:

     Étant donné que les flux de données Python possèdent leur propre
     couche de tampon, les mélanger avec des descripteurs de fichiers
     du niveau du système d'exploitation peut produire des erreurs
     (comme par exemple un ordre des données inattendu).

   Modifié dans la version 3.2: ignore l'attribut *name*

int PyObject_AsFileDescriptor(PyObject *p)
    * Part of the Stable ABI.*

   Return the file descriptor associated with *p* as an int.  If the
   object is an integer, its value is returned.  If not, the object's
   "fileno()" method is called if it exists; the method must return an
   integer, which is returned as the file descriptor value.  Sets an
   exception and returns "-1" on failure.

PyObject *PyFile_GetLine(PyObject *p, int n)
    *Valeur de retour : nouvelle référence.** Part of the Stable ABI.*

   Cette fonction, équivalente à "p.readline([n])", lit une ligne de
   l'objet *p*. *p* peut être un objet fichier ou n'importe quel objet
   qui possède une méthode "readline()". Si *n* vaut "0", une seule
   ligne est lue, indépendamment de la taille de la ligne. Si *n* est
   plus grand que "0", un maximum de *n* octets seront lus en
   provenance du fichier ; une ligne partielle peut être renvoyée.
   Dans les deux cas, une chaîne de caractères vide est renvoyée si la
   fin du fichier est atteinte immédiatement. Cependant, si *n* est
   plus petit que "0", une ligne est lue indépendamment de sa taille,
   mais "EOFError" est levée si la fin du fichier est atteinte
   immédiatement.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

   Overrides the normal behavior of "io.open_code()" to pass its
   parameter through the provided handler.

   The *handler* is a function of type:

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

      Equivalent of PyObject *(*)(PyObject *path, void *userData),
      where *path* is guaranteed to be "PyUnicodeObject".

   The *userData* pointer is passed into the hook function. Since hook
   functions may be called from different runtimes, this pointer
   should not refer directly to Python state.

   As this hook is intentionally used during import, avoid importing
   new modules during its execution unless they are known to be frozen
   or available in "sys.modules".

   Once a hook has been set, it cannot be removed or replaced, and
   later calls to "PyFile_SetOpenCodeHook()" will fail. On failure,
   the function returns -1 and sets an exception if the interpreter
   has been initialized.

   This function is safe to call before "Py_Initialize()".

   Raises an auditing event "setopencodehook" with no arguments.

   Ajouté dans la 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.

   Ajouté dans la version 3.8.

PyObject *PyFile_OpenCode(const char *path)

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

   Ajouté dans la version 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
    * Part of the 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()".  Return "0" on success or "-1" on
   failure; the appropriate exception will be set.

int PyFile_WriteString(const char *s, PyObject *p)
    * Part of the Stable ABI.*

   Écrit la chaîne de caractères *s* dans l'objet fichier *p*.
   Retourne "0" en cas de succès ou "-1" en cas d'échec ; l'exception
   appropriée sera mise en place.
