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

Эти 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)¶: Возвращаемое значение: новая ссылка. Часть Stable ABI.
Создаёт объект файла Python из файлового дескриптора уже открытого файла fd. Аргументы name, encoding, errors и newline могут быть NULL для использования значений по умолчанию; buffering может быть -1 для использования значения по умолчанию. name игнорируется и сохранён для обратной совместимости. Возвращает NULL в случае неудачи. За более подробным описанием аргументов обратитесь к документации функции io.open().

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

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

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

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

PyObject *PyFile_GetLine(PyObject *p, int n)¶: Возвращаемое значение: новая ссылка. Часть Stable 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)¶: Часть Stable ABI.
Записывает объект obj в файловый объект p. Единственный поддерживаемый флаг для flags – это Py_PRINT_RAW; если он указан, записывается str() объекта вместо repr(). Возвращает 0 при успехе или -1 при ошибке; устанавливается соответствующее исключение.

int PyFile_WriteString(const char *s, PyObject *p)¶: Часть Stable ABI.
Записывает строку s в файловый объект p. Возвращает 0 при успехе или -1 при ошибке; будет установлено соответствующее исключение.