`file.md`

126 строк · 10.5 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.6/c-api/file.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Объекты файлов89Встроенные файловые объекты Python полностью реализованы на основе поддержки `FILE*` из стандартной библиотеки C. Это деталь реализации, которая может измениться в будущих версиях Python.1011**`PyFileObject`**1213Этот подтип1415[`PyObject`](https://python-all.ru/2.6/c-api/structures.html#PyObject)1617представляет файловый объект Python.1819**[PyTypeObject](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) `PyFile_Type`**2021Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.6/c-api/type.html#PyTypeObject) представляет тип файла Python. Он доступен программам Python как `file` и `types.FileType`.2223**int `PyFile_Check`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**2425Возвращает true, если аргумент является [`PyFileObject`](https://python-all.ru/2.6/c-api/file.html#PyFileObject) или подтипом [`PyFileObject`](https://python-all.ru/2.6/c-api/file.html#PyFileObject).2627Изменено в версии 2.2: Теперь допускаются подтипы.2829**int `PyFile_CheckExact`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**3031Возвращает true, если аргумент является [`PyFileObject`](https://python-all.ru/2.6/c-api/file.html#PyFileObject), но не подтипом [`PyFileObject`](https://python-all.ru/2.6/c-api/file.html#PyFileObject).3233Новое в версии 2.2.3435**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyFile_FromString`(char *\*filename*, char *\*mode*)**3637*Возвращаемое значение: новая ссылка.*3839В случае успеха возвращает новый файловый объект, открытый для файла, заданного *filename*, с режимом файла, заданным *mode*, где *mode* имеет ту же семантику, что и стандартная функция C `fopen()`. В случае ошибки возвращает *NULL*.4041**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyFile_FromFile`(FILE *\*fp*, char *\*name*, char *\*mode*, int *(\*close)(FILE\*)*)**4243*Возвращаемое значение: новая ссылка.*4445Создаёт новый [`PyFileObject`](https://python-all.ru/2.6/c-api/file.html#PyFileObject) из уже открытого стандартного указателя C файла *fp*. Функция *close* будет вызвана, когда файл должен быть закрыт. В случае ошибки возвращает *NULL*.4647**FILE\* `PyFile_AsFile`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**4849Возвращает файловый объект, связанный с *p*, в виде `FILE*`.5051Если вызывающий код когда-либо будет использовать возвращаемый объект `FILE*`, когда GIL освобождён, он также должен вызывать функции [`PyFile_IncUseCount()`](https://python-all.ru/2.6/c-api/file.html#PyFile_IncUseCount) и [`PyFile_DecUseCount()`](https://python-all.ru/2.6/c-api/file.html#PyFile_DecUseCount), описанные ниже, по мере необходимости.5253**void `PyFile_IncUseCount`([PyFileObject](https://python-all.ru/2.6/c-api/file.html#PyFileObject) *\*p*)**5455Увеличивает внутренний счётчик использования PyFileObject, чтобы указать, что базовый `FILE*` используется. Это предотвращает вызов Python'ом f\_close() для него из другого потока. Вызывающие это должны вызывать [`PyFile_DecUseCount()`](https://python-all.ru/2.6/c-api/file.html#PyFile_DecUseCount), когда закончат работу с `FILE*`. В противном случае файловый объект никогда не будет закрыт Python'ом.5657GIL должен быть захвачен при вызове этой функции.5859Рекомендуется вызывать это после [`PyFile_AsFile()`](https://python-all.ru/2.6/c-api/file.html#PyFile_AsFile), непосредственно перед освобождением GIL.6061Новое в версии 2.6.6263**void `PyFile_DecUseCount`([PyFileObject](https://python-all.ru/2.6/c-api/file.html#PyFileObject) *\*p*)**6465Уменьшает внутренний член unlocked\_count PyFileObject, чтобы указать, что вызывающий завершил собственное использование `FILE*`. Это может быть вызвано только для отмены предыдущего вызова [`PyFile_IncUseCount()`](https://python-all.ru/2.6/c-api/file.html#PyFile_IncUseCount).6667GIL должен быть захвачен при вызове этой функции.6869Новое в версии 2.6.7071**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyFile_GetLine`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p* *n*)**7273*Возвращаемое значение: новая ссылка.*7475Эта функция эквивалентна `p.readline([n])` и читает одну строку из объекта *p*. *p* может быть файловым объектом или любым объектом, имеющим метод `readline()`. Если *n* равно `0`, читается ровно одна строка, независимо от её длины. Если *n* больше `0`, из файла будет прочитано не более *n* байт; может быть возвращена неполная строка. В обоих случаях возвращается пустая строка, если конец файла достигнут сразу. Однако если *n* меньше `0`, читается одна строка независимо от длины, но если конец файла достигнут сразу, возбуждается [`EOFError`](https://python-all.ru/2.6/library/exceptions.html#exceptions.EOFError).7677**[PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject)\* `PyFile_Name`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**7879*Возвращаемое значение: заимствованная ссылка.*8081Возвращает имя файла, указанного *p*, в виде строкового объекта.8283**void `PyFile_SetBufSize`([PyFileObject](https://python-all.ru/2.6/c-api/file.html#PyFileObject) *\*p*, int *n*)**8485Доступно только в системах с `setvbuf()`. Это следует вызывать только сразу после создания файлового объекта.8687**int `PyFile_SetEncoding`([PyFileObject](https://python-all.ru/2.6/c-api/file.html#PyFileObject) *\*p*, const char *\*enc*)**8889Устанавливает кодировку файла для вывода Unicode в *enc*. Возвращает 1 в случае успеха и 0 в случае ошибки.9091Новое в версии 2.3.9293**int `PyFile_SetEncodingAndErrors`([PyFileObject](https://python-all.ru/2.6/c-api/file.html#PyFileObject) *\*p*, const char *\*enc*, \*errors)**9495Устанавливает кодировку файла для вывода Unicode в *enc* и режим обработки ошибок в *err*. Возвращает 1 в случае успеха и 0 в случае ошибки.9697Новое в версии 2.6.9899**int `PyFile_SoftSpace`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, int *newflag*)**100101Эта функция существует для внутреннего использования интерпретатором. Устанавливает атрибут `softspace` объекта *p* в значение *newflag* и возвращает предыдущее значение. Для корректной работы этой функции *p* не обязан быть файловым объектом; поддерживается любой объект (хотя это имеет смысл только если атрибут `softspace` может быть установлен). Эта функция очищает все ошибки и вернёт `0` в качестве предыдущего значения, если атрибут не существует или возникли ошибки при его получении. Из этой функции невозможно определить наличие ошибок, но это и не должно требоваться.102103**int `PyFile_WriteObject`([PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*obj*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*, int *flags*)**104105Записывает объект *obj* в файловый объект *p*. Единственный поддерживаемый флаг для *flags* – `Py_PRINT_RAW`; если он задан, записывается [`str()`](https://python-all.ru/2.6/library/functions.html#str) объекта вместо [`repr()`](https://python-all.ru/2.6/library/functions.html#repr). Возвращает `0` при успехе или `-1` при ошибке; будет установлено соответствующее исключение.106107**int `PyFile_WriteString`(const char *\*s*, [PyObject](https://python-all.ru/2.6/c-api/structures.html#PyObject) *\*p*)**108109Записывает строку110111*s*112113в файловый объект114115*p*116117. Возвращает118119`0`120121при успехе или122123`-1`124125при ошибке; будет установлено соответствующее исключение.126