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

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

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(), чтобы передать свой параметр через предоставленный обработчик.

Обработчик* - это функция типа:

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

Эквивалент PyObject *(*)(PyObject *path, void *userData), где путь гарантированно будет PyUnicodeObject.

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

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

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

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

Поднимает auditing event setopencodehook без аргументов.

Added in version 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 в случае неудачи; будет установлено соответствующее исключение.