Файловые объекты

Данные API-интерфейсы являются минимальной эмуляцией Python 2 C API для встроенных файловых объектов, которые раньше полагались на поддержку буферизованного ввода-вывода (FILE*) из стандартной библиотеки C. В Python 3 файлы и потоки используют новый модуль io, определяющий несколько уровней над низкоуровневым небуферизованным вводом-выводом операционной системы. Рассмотренные далее функции являются удобными оболочками C для новых API и предназначены в основном для внутренних отчетов об ошибках в интерпретаторе; рекомендуется использовать сторонний код для доступа к API io.

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.
Создает объект файла Python из файлового дескриптора уже открытого файла fd. Аргументы name, encoding, errors и newline могут быть NULL для использования значений по умолчанию; buffering может быть -1, чтобы использовать значение по умолчанию. name игнорируется и сохраняется для обратной совместимости. Возвращает NULL в случае ошибки. Для более полного описания аргументов обратитесь к документации функции io.open().

Предупреждение

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

Изменено в версии 3.2: Игнорировать атрибут name.

int PyObject_AsFileDescriptor(PyObject *p): Возвращает дескриптор файла, связанный с p, как int. Если объект является целым числом, возвращается его значение. В противном случае вызывается метод объекта fileno(), если он существует; метод должен возвращать целое число, которое возвращается как значение дескриптора файла. Устанавливает исключение и возвращает -1 в случае ошибки.

PyObject* PyFile_GetLine(PyObject *p, int n): Return value: New reference.
Эквивалентно p.readline([n]), функция считывает одну строку из объекта p. p может быть файловым объектом или любым объектом с методом readline(). Если n — это 0, считывается ровно одна строка, независимо от длины строки. Если n больше 0, из файла будет прочитано не более n байт; частичная строка может быть возвращена. В обоих случаях возвращается пустая строка, если конец файла достигается немедленно. Однако, если n меньше, чем 0, одна строка читается независимо от длины, но вызывается EOFError, если конец файла достигается немедленно.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Переопределяет нормальное поведение io.open_code() для передачи его параметра через предоставленный обработчик.

Обработчик — это функция типа c:type:PyObject *(*)(PyObject *path, void *userData), где path гарантированно будет PyUnicodeObject.

Указатель userData передается в функцию перехвата. Поскольку функции-перехватчики могут вызываться из разных сред выполнения, данный указатель не должен ссылаться непосредственно на состояние Python.

Поскольку данный перехватчик намеренно используется во время импорта, избегайте импорта новых модулей во время его выполнения, если только известно, что они заморожены или доступны в sys.modules.

После установки ловушки её нельзя удалить или заменить, и последующие вызовы PyFile_SetOpenCodeHook() завершатся ошибкой. В случае ошибки функция возвращает -1 и устанавливает исключение, если интерпретатор был инициализирован.

Эту функцию можно безопасно вызывать до Py_Initialize().

Вызывает событие аудита setopencodehook без аргументов.

Добавлено в версии 3.8.

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags): Записывает объект obj в объект файла p. Единственный поддерживаемый флаг для flags — Py_PRINT_RAW; если задано, вместо repr() записывается str() объекта. Возвращает 0 в случае успеха или -1 в случае неудачи; будет установлено соответствующее исключение.

int PyFile_WriteString(const char *s, PyObject *p): Записывает строку s в объект файла p. Возвращает 0 в случае успеха или -1 в случае неудачи; будет установлено соответствующее исключение.