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

Эти 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.

PyObject *PyFile_OpenCodeObject(PyObject *path)

Открывает path в режиме 'rb'. path должен быть объектом Python str. Поведение этой функции может быть переопределено с помощью PyFile_SetOpenCodeHook(), чтобы разрешить предварительную обработку текста.

В Python эта функция аналогична io.open_code().

В случае успеха эта функция возвращает сильную ссылку на файловый объект Python. В случае ошибки эта функция возвращает NULL с установленным исключением.

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

PyObject *PyFile_OpenCode(const char *path)

Аналогична PyFile_OpenCodeObject(), но path представляет собой строку const char* в кодировке UTF-8.

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

int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)

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

Записывает объект obj в файловый объект p. Для flags поддерживается только флаг Py_PRINT_RAW; если он указан, вместо repr() объекта записывается его str().

Если obj равен NULL, записывается строка "<NULL>".

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

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

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

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