`file.md`

72 строк · 8.6 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.11/c-api/file.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты файлов89Эти API представляют собой минимальную эмуляцию C API Python 2 для встроенных файловых объектов, который ранее опирался на буферизованный ввод‑вывод (FILE\*) из стандартной библиотеки C. В Python 3 файлы и потоки данных используют новый модуль [`io`](https://python-all.ru/3.11/library/io.html#module-io), который определяет несколько уровней поверх низкоуровневого небуферизованного ввода‑вывода операционной системы. Описанные ниже функции – это удобные C-обёртки над этими новыми API; они предназначены в основном для внутреннего сообщения об ошибках в интерпретаторе. Стороннему коду рекомендуется вместо них использовать API [`io`](https://python-all.ru/3.11/library/io.html#module-io).1011#### `PyObject *PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)`1213*Возвращаемое значение: новая ссылка.*1415*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*1617Создаёт объект файла Python из файлового дескриптора уже открытого файла *fd*. Аргументы *name*, *encoding*, *errors* и *newline* могут быть `NULL` для использования значений по умолчанию; *buffering* может быть *-1* для использования значения по умолчанию. *name* игнорируется и сохранён для обратной совместимости. Возвращает `NULL` в случае неудачи. За более подробным описанием аргументов обратитесь к документации функции [`io.open()`](https://python-all.ru/3.11/library/io.html#io.open).1819> **Предупреждение**20>21> Поскольку потоки Python имеют собственный уровень буферизации, их смешивание с файловыми дескрипторами ОС может вызвать различные проблемы (например, непредсказуемый порядок данных).2223Изменено в версии 3.2: Игнорируется атрибут *name*.2425#### `int PyObject_AsFileDescriptor(PyObject *p)`2627*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*2829Возвращает файловый дескриптор, связанный с *p*, в виде int. Если объект является целым числом, возвращается его значение. Если нет, вызывается метод объекта [`fileno()`](https://python-all.ru/3.11/library/io.html#io.IOBase.fileno) (если он существует); этот метод должен вернуть целое число, которое и возвращается как значение файлового дескриптора. В случае неудачи устанавливает исключение и возвращает `-1`.3031#### `PyObject *PyFile_GetLine(PyObject *p, int n)`3233*Возвращаемое значение: новая ссылка.*3435*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*3637Эквивалентно `p.readline([n])`; эта функция читает одну строку из объекта *p*. *p* может быть файловым объектом или любым объектом с методом [`readline()`](https://python-all.ru/3.11/library/io.html#io.IOBase.readline). Если *n* равно `0`, читается ровно одна строка независимо от её длины. Если *n* больше `0`, из файла будет прочитано не более *n* байт; может быть возвращена неполная строка. В обоих случаях возвращается пустая строка, если конец файла достигнут сразу. Однако, если *n* меньше `0`, читается одна строка независимо от длины, но при немедленном достижении конца файла возбуждается [`EOFError`](https://python-all.ru/3.11/library/exceptions.html#EOFError).3839#### `int PyFile_SetOpenCodeHook(Py_OpenCodeHookFunction handler)`4041Переопределяет обычное поведение [`io.open_code()`](https://python-all.ru/3.11/library/io.html#io.open_code), передавая его параметр через указанный обработчик.4243*handler* – это функция типа:4445#### `typedef PyObject *(*Py_OpenCodeHookFunction)(PyObject*, void*)`4647Эквивалент [PyObject](https://python-all.ru/3.11/c-api/structures.html#c.PyObject) \*(\*)([PyObject](https://python-all.ru/3.11/c-api/structures.html#c.PyObject) \*path, void \*userData), где *path* гарантированно является [`PyUnicodeObject`](https://python-all.ru/3.11/c-api/unicode.html#c.PyUnicodeObject).4849Указатель *userData* передаётся в функцию-обработчик. Поскольку функции-обработчики могут вызываться из разных сред выполнения, этот указатель не должен напрямую ссылаться на состояние Python.5051Поскольку этот перехватчик намеренно используется во время импорта, избегайте импорта новых модулей во время его выполнения, если только они не заморожены или не доступны в `sys.modules`.5253После установки перехватчик нельзя удалить или заменить; последующие вызовы [`PyFile_SetOpenCodeHook()`](https://python-all.ru/3.11/c-api/file.html#c.PyFile_SetOpenCodeHook) будут завершаться ошибкой. В случае неудачи функция возвращает -1 и устанавливает исключение, если интерпретатор уже инициализирован.5455Эту функцию можно безопасно вызывать до [`Py_Initialize()`](https://python-all.ru/3.11/c-api/init.html#c.Py_Initialize).5657Возбуждает [событие аудита](https://python-all.ru/3.11/library/sys.html#auditing) `setopencodehook` без аргументов.5859Новое в версии 3.8.6061#### `int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)`6263*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*6465Записывает объект *obj* в файловый объект *p*. Единственный поддерживаемый флаг для *flags* – это [`Py_PRINT_RAW`](https://python-all.ru/3.11/c-api/object.html#c.Py_PRINT_RAW); если он указан, записывается [`str()`](https://python-all.ru/3.11/library/stdtypes.html#str) объекта вместо [`repr()`](https://python-all.ru/3.11/library/functions.html#repr). Возвращает `0` при успехе или `-1` при ошибке; устанавливается соответствующее исключение.6667#### `int PyFile_WriteString(const char *s, PyObject *p)`6869*Часть [Stable ABI](https://python-all.ru/3.11/c-api/stable.html#stable).*7071Записывает строку *s* в файловый объект *p*. Возвращает `0` при успехе или `-1` при ошибке; будет установлено соответствующее исключение.72