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)
    *Return value: New reference.*

   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)

   Renvoie un descripteur de fichier associé avec *p* comme un "int".
   Si l'objet est un entier, sa valeur est renvoyée. Sinon, la méthode
   "fileno()" de l'objet est appelée si elle existe; la méthode doit
   renvoyer un entier, qui est renvoyé en tant que valeur du
   descripteur. Affecte une exception et renvoie "-1" lors d'un échec.

PyObject* PyFile_GetLine(PyObject *p, int n)
    *Return value: New reference.*

   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 "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.

   Nouveau dans la version 3.8.

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

   Écrit l'objet *obj* dans l'objet fichier *p*. La seule option gérée
   pour *flags* est "Py_PRINT_RAW" ; si défini, l'attribut "str()" de
   l'objet est écrit à la place de l'attribut "repr()". Retourne "0"
   en cas de succès ou "-1" en cas échec ; l'exception appropriée sera
   levée.

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

   É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.
