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

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

Возвращаемое значение: новая ссылка.

Создает объект файла Python из дескриптора файла уже открытого файла fd. Аргументы name, encoding, errors и newline могут быть NULL для использования значений по умолчанию; buffering может быть -1 для использования значения по умолчанию. name игнорируется и сохраняется для обратной совместимости. Возвращает NULL при ошибке. Для более подробного описания аргументов, пожалуйста, обратитесь к документации функции io.open().

Предупреждение

Так как потоки Python имеют свой собственный слой буферизации, смешивание их с дескрипторами файлов на уровне ОС может привести к различным проблемам (таким как неожиданный порядок данных).

Изменено в версии 3.2: Игнорирование атрибута name.

int PyObject_AsFileDescriptor(PyObject *p)

Возвращает дескриптор файла, связанный с p, как int. Если объект является целым числом, возвращается его значение. В противном случае, если существует метод fileno() объекта, вызывается этот метод; метод должен возвращать целое число, которое возвращается как значение дескриптора файла. Устанавливает исключение и возвращает -1 при ошибке.

PyObject* PyFile_GetLine(PyObject *p, int n)

Возвращаемое значение: новая ссылка.

Эквивалентно p.readline([n]), эта функция считывает одну строку из объекта p. p может быть объектом файла или любым объектом с методом readline(). Если n является 0, то считывается ровно одна строка, независимо от длины строки. Если n больше 0, то будет считано не более n байтов из файла; может быть возвращена частичная строка. В обоих случаях, при достижении конца файла немедленно, возвращается пустая строка. Однако, если n меньше 0, то считывается одна строка независимо от длины, но EOFError поднимается, если конец файла достигается сразу.

int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)

Переопределяет обычное поведение io.open_code(), передавая его параметр через предоставленный обработчик.

Обработчик — это функция типа 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)

Записывает объект obj в объект файла p. Единственный поддерживаемый флаг для flags — Py_PRINT_RAW; если задан, записывается str() объекта вместо repr(). Возвращает 0 при успехе или -1 при ошибке; будет установлено соответствующее исключение.

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

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