File objects

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. Fait partie de l' ABI stable.

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)

Fait partie de l' ABI stable.

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. Fait partie de l' ABI stable.

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.

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)

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)

Fait partie de l' ABI stable.

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)

Fait partie de l' ABI stable.

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

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.