> **Источник:** https://python-all.ru/2.7/c-api/file.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

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

Встроенные файловые объекты Python полностью реализованы на основе `FILE*` из стандартной библиотеки C. Это деталь реализации, которая может измениться в будущих версиях Python.

**`PyFileObject`**

Этот подтип [`PyObject`](https://python-all.ru/2.7/c-api/structures.html#c.PyObject) представляет файловый объект Python.

**[PyTypeObject](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) `PyFile_Type`**

Этот экземпляр [`PyTypeObject`](https://python-all.ru/2.7/c-api/type.html#c.PyTypeObject) представляет тип файла Python. Он доступен программам Python как `file` и `types.FileType`.

#### `int PyFile_Check(PyObject *p)`

Возвращает истину, если аргумент является [`PyFileObject`](https://python-all.ru/2.7/c-api/file.html#c.PyFileObject) или подтипом [`PyFileObject`](https://python-all.ru/2.7/c-api/file.html#c.PyFileObject).

Изменено в версии 2.2: Разрешено принимать подтипы.

#### `int PyFile_CheckExact(PyObject *p)`

Возвращает истину, если аргумент является [`PyFileObject`](https://python-all.ru/2.7/c-api/file.html#c.PyFileObject), но не подтипом [`PyFileObject`](https://python-all.ru/2.7/c-api/file.html#c.PyFileObject).

Новое в версии 2.2.

#### `PyObject* PyFile_FromString(char *filename, char *mode)`

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

В случае успеха возвращает новый файловый объект, открытый для файла, заданного *filename*, с режимом доступа, заданным *mode*, где *mode* имеет ту же семантику, что и стандартная функция C `fopen()`. В случае неудачи возвращает *NULL*.

#### `PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))`

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

Создает новый [`PyFileObject`](https://python-all.ru/2.7/c-api/file.html#c.PyFileObject) из уже открытого указателя на стандартный файл C, *fp*. Функция *close* будет вызвана, когда файл должен быть закрыт. В случае неудачи возвращает *NULL* и закрывает файл с помощью *close*. *close* необязателен и может быть установлен в *NULL*.

#### `FILE* PyFile_AsFile(PyObject *p)`

Возвращает файловый объект, связанный с *p*, в виде `FILE*`.

Если вызывающий код когда-либо будет использовать возвращенный объект `FILE*`, пока [GIL](https://python-all.ru/2.7/glossary.html#term-gil) отпущен, он также должен вызвать функции [`PyFile_IncUseCount()`](https://python-all.ru/2.7/c-api/file.html#c.PyFile_IncUseCount) и [`PyFile_DecUseCount()`](https://python-all.ru/2.7/c-api/file.html#c.PyFile_DecUseCount), описанные ниже, по необходимости.

#### `void PyFile_IncUseCount(PyFileObject *p)`

Увеличивает внутренний счетчик использования PyFileObject, чтобы указать, что базовый `FILE*` используется. Это предотвращает вызов Python'ом f\_close() для него из другого потока. Вызывающие эту функцию должны вызвать [`PyFile_DecUseCount()`](https://python-all.ru/2.7/c-api/file.html#c.PyFile_DecUseCount), когда закончат работу с `FILE*`. В противном случае файловый объект никогда не будет закрыт Python.

При вызове этой функции должен быть захвачен [GIL](https://python-all.ru/2.7/glossary.html#term-gil).

Рекомендуется вызывать эту функцию после [`PyFile_AsFile()`](https://python-all.ru/2.7/c-api/file.html#c.PyFile_AsFile) и до отпускания GIL:

```c
FILE *fp = PyFile_AsFile(p);
PyFile_IncUseCount(p);
/* ... */
Py_BEGIN_ALLOW_THREADS
do_something(fp);
Py_END_ALLOW_THREADS
/* ... */
PyFile_DecUseCount(p);
```

Новое в версии 2.6.

#### `void PyFile_DecUseCount(PyFileObject *p)`

Уменьшает внутренний член unlocked\_count у PyFileObject, чтобы указать, что вызывающий код закончил свое использование `FILE*`. Эту функцию можно вызывать только для отмены предыдущего вызова [`PyFile_IncUseCount()`](https://python-all.ru/2.7/c-api/file.html#c.PyFile_IncUseCount).

При вызове этой функции должен быть захвачен [GIL](https://python-all.ru/2.7/glossary.html#term-gil) (см. пример выше).

Новое в версии 2.6.

#### `PyObject* PyFile_GetLine(PyObject *p, int n)`

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

Эквивалентно `p.readline([n])`; эта функция читает одну строку из объекта *p*. *p* может быть файловым объектом или любым объектом с методом [`readline()`](https://python-all.ru/2.7/library/io.html#io.IOBase.readline). Если *n* равно `0`, читается ровно одна строка независимо от её длины. Если *n* больше `0`, из файла будет прочитано не более *n* байт; может быть возвращена неполная строка. В обоих случаях возвращается пустая строка, если конец файла достигнут сразу. Однако, если *n* меньше `0`, читается одна строка независимо от длины, но при немедленном достижении конца файла возбуждается [`EOFError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.EOFError).

#### `PyObject* PyFile_Name(PyObject *p)`

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

Возвращает имя файла, указанного *p*, в виде строкового объекта.

#### `void PyFile_SetBufSize(PyFileObject *p, int n)`

Доступно только в системах с `setvbuf()`. Эту функцию следует вызывать только сразу после создания файлового объекта.

#### `int PyFile_SetEncoding(PyFileObject *p, const char *enc)`

Устанавливает кодировку файла для вывода Unicode в *enc*. Возвращает `1` в случае успеха и `0` в случае неудачи.

Новое в версии 2.3.

#### `int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)`

Устанавливает кодировку файла для вывода Unicode в *enc*, а его режим обработки ошибок в *err*. Возвращает `1` в случае успеха и `0` в случае неудачи.

Новое в версии 2.6.

#### `int PyFile_SoftSpace(PyObject *p, int newflag)`

Эта функция существует для внутреннего использования интерпретатором. Устанавливает атрибут `softspace` объекта *p* в *newflag* и возвращает предыдущее значение. *p* не обязательно должен быть файловым объектом для корректной работы этой функции; поддерживается любой объект (хотя это интересно только в том случае, если атрибут `softspace` может быть установлен). Эта функция очищает любые ошибки и вернет `0` в качестве предыдущего значения, если атрибут не существует или при его получении возникли ошибки. Невозможно обнаружить ошибки этой функции, но делать это не должно требоваться.

#### `int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)`

Записывает объект *obj* в файловый объект *p*. Единственный поддерживаемый флаг для *flags* – это `Py_PRINT_RAW`; если он указан, записывается [`str()`](https://python-all.ru/2.7/library/functions.html#str) объекта вместо [`repr()`](https://python-all.ru/2.7/library/functions.html#repr). Возвращает `0` при успехе или `-1` при ошибке; устанавливается соответствующее исключение.

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

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