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

Эти 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; при этом устанавливается соответствующее исключение.