Объекты файлов

Эти API представляют собой минимальную эмуляцию API Python 2 для встроенных объектов файлов, которые ранее полагались на поддержку буферизованного ввода-вывода (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)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

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

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

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

int PyObject_AsFileDescriptor(PyObject *p)

Часть Стабильной ABI.

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

PyObject *PyFile_GetLine(PyObject *p, int n)

Значение возврата: новая ссылка. Часть Стабильной ABI.

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

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

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

handler — функция типа:

typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)

Эквивалент 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)

Часть Стабильной ABI.

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

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

Часть Стабильной ABI.

Записывает строку s в объект файла p. Возвращает 0 при успехе или -1 при ошибке; будет установлено соответствующее исключение.