python_doc_md/Advanced/c-api/file.md

File Objects {#fileobjects}

::: index pair: object; file :::

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*{.interpreted-text role="c:expr"}) support from the C standard library. In Python 3, files and streams use the new io{.interpreted-text role="mod"} 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{.interpreted-text role="mod"} APIs instead.

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{.interpreted-text role="func"} function documentation.

:::: warning ::: title Warning :::

Since Python streams have their own buffering layer, mixing them with OS-level file descriptors can produce various issues (such as unexpected ordering of data). ::::

::: versionchanged 3.2 Ignore name attribute. :::

Return the file descriptor associated with p as an int{.interpreted-text role="c:expr"}. If the object is an integer, its value is returned. If not, the object's ~io.IOBase.fileno{.interpreted-text role="meth"} 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.

::: index single: EOFError (built-in exception) :::

Equivalent to p.readline([n]), this function reads one line from the object p. p may be a file object or any object with a ~io.IOBase.readline{.interpreted-text role="meth"} method. If n is 0, exactly one line is read, regardless of the length of the line. If n is greater than 0, no more than n bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If n is less than 0, however, one line is read regardless of length, but EOFError{.interpreted-text role="exc"} is raised if the end of the file is reached immediately.

Overrides the normal behavior of io.open_code{.interpreted-text role="func"} to pass its parameter through the provided handler.

The handler is a function of type:

Equivalent of PyObject *(\*)(PyObject *path, void *userData){.interpreted-text role="c:expr"}, where path is guaranteed to be PyUnicodeObject{.interpreted-text role="c:type"}.

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{.interpreted-text role="c:func"} 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{.interpreted-text role="c:func"}.

::: audit-event setopencodehook "" c.PyFile_SetOpenCodeHook :::

::: versionadded 3.8 :::

Open path with the mode 'rb'. path must be a Python str{.interpreted-text role="class"} object. The behavior of this function may be overridden by PyFile_SetOpenCodeHook{.interpreted-text role="c:func"} to allow for some preprocessing of the text.

This is analogous to io.open_code{.interpreted-text role="func"} in Python.

On success, this function returns a strong reference{.interpreted-text role="term"} to a Python file object. On failure, this function returns NULL with an exception set.

::: versionadded 3.8 :::

Similar to PyFile_OpenCodeObject{.interpreted-text role="c:func"}, but path is a UTF-8 encoded const char*{.interpreted-text role="c:expr"}.

::: versionadded 3.8 :::

::: index single: Py_PRINT_RAW (C macro) :::

Write object obj to file object p. The only supported flag for flags is Py_PRINT_RAW{.interpreted-text role="c:macro"}; if given, the str{.interpreted-text role="func"} of the object is written instead of the repr{.interpreted-text role="func"}. Return 0 on success or -1 on failure; the appropriate exception will be set.

Write string s to file object p. Return 0 on success or -1 on failure; the appropriate exception will be set.

Deprecated API

These are soft deprecated{.interpreted-text role="term"} APIs that were included in Python's C API by mistake. They are documented solely for completeness; use other PyFile* APIs instead.

Use PyFile_FromFd{.interpreted-text role="c:func"} with defaults (fd, NULL, "w", -1, NULL, NULL, NULL, 0) instead.

Type of file-like objects used internally at Python startup when io{.interpreted-text role="py:mod"} is not yet available. Use Python open{.interpreted-text role="py:func"} or PyFile_FromFd{.interpreted-text role="c:func"} to create file objects instead.