# 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)
  Return value: New reference. Part of the Stable ABI.

  Створіть файловий об’єкт Python із файлового дескриптора вже відкритого файлу fd. Аргументи name, encoding, errors і newline можуть бути `NULL` для використання типових значень; buffering може бути -1, щоб використовувати значення за замовчуванням. name ігнорується та зберігається для зворотної сумісності. Повертає `NULL` у разі помилки. Щоб отримати докладніший опис аргументів, зверніться до документації функції `io.open()`.

  Попередження

  Оскільки потоки Python мають власний рівень буферизації, змішування їх із файловими дескрипторами рівня ОС може спричинити різноманітні проблеми (наприклад, несподіване впорядкування даних).

  Змінено в версії 3.2: Ігнорувати атрибут 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)
  Return value: New reference. Part of the Stable ABI.

  Еквівалентна `p.readline([n])`, ця функція читає один рядок з об’єкта p. p може бути файловим об’єктом або будь-яким об’єктом із методом `readline()`. Якщо n дорівнює `0`, читається рівно один рядок, незалежно від довжини рядка. Якщо n більше ніж `0`, з файлу буде прочитано не більше ніж n байт; можна повернути часткову лінію. В обох випадках повертається порожній рядок, якщо кінець файлу досягнуто негайно. Однак якщо n менше ніж `0`, один рядок читається незалежно від довжини, але `EOFError` викликається, якщо кінець файлу досягнуто негайно.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

  Перевизначає звичайну поведінку `io.open_code()` для передачі його параметра через наданий обробник.

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

  Покажчик userData передається в функцію-перехоплювач. Оскільки функції підключення можуть викликатися з різних середовищ виконання, цей вказівник не повинен посилатися безпосередньо на стан Python.

  Оскільки цей хук навмисно використовується під час імпорту, уникайте імпорту нових модулів під час його виконання, якщо тільки відомо, що вони заморожені або доступні в `sys.modules`.

  Після того, як хук встановлено, його не можна видалити або замінити, а пізніші виклики `PyFile_SetOpenCodeHook()` не вдадуться. У разі помилки функція повертає -1 і встановлює виняток, якщо інтерпретатор був ініціалізований.

  Цю функцію безпечно викликати перед `Py_Initialize()`.

  Викликає подію аудиту `setopencodehook` без аргументів.

  Added in 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.

  Added in version 3.8.

PyObject *PyFile_OpenCode(const char *path)

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

  Added in 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()`.

  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)
  Part of the Stable ABI.

  Записати рядок s до файлового об’єкта p. Повертає `0` у разі успіху або `-1` у разі невдачі; буде встановлено відповідний виняток.

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