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

Эти API представляют собой минимальную эмуляцию C 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; если он задан, вместо repr() объекта записывается его str(). В случае успеха возвращает 0, в случае ошибки — -1; при этом устанавливается соответствующее исключение.

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

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

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