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

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

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

type Py_OpenCodeHookFunction

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