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

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

PyFileObject¶: Этот подтип PyObject представляет файловый объект Python.

PyTypeObject PyFile_Type¶: Этот экземпляр PyTypeObject представляет тип файла Python. Он доступен программам Python как file и types.FileType.

int PyFile_Check(PyObject *p)¶: Возвращает истину, если аргумент является PyFileObject или подтипом PyFileObject.

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

int PyFile_CheckExact(PyObject *p)¶: Возвращает истину, если аргумент является PyFileObject, но не подтипом 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 из уже открытого указателя на стандартный файл C, fp. Функция close будет вызвана, когда файл должен быть закрыт. В случае неудачи возвращает NULL и закрывает файл с помощью close. close необязателен и может быть установлен в NULL.

FILE* PyFile_AsFile(PyObject *p)¶

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

Если вызывающий код когда-либо будет использовать возвращенный объект FILE*, пока GIL отпущен, он также должен вызвать функции PyFile_IncUseCount() и PyFile_DecUseCount(), описанные ниже, по необходимости.

void PyFile_IncUseCount(PyFileObject *p)¶

Увеличивает внутренний счетчик использования PyFileObject, чтобы указать, что базовый FILE* используется. Это предотвращает вызов Python'ом f_close() для него из другого потока. Вызывающие эту функцию должны вызвать PyFile_DecUseCount(), когда закончат работу с FILE*. В противном случае файловый объект никогда не будет закрыт Python.

При вызове этой функции должен быть захвачен GIL.

Рекомендуется вызывать эту функцию после PyFile_AsFile() и до отпускания GIL:

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().

При вызове этой функции должен быть захвачен GIL (см. пример выше).

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

PyObject* PyFile_GetLine(PyObject *p, int n)¶: Возвращаемое значение: новая ссылка.
Эквивалентно p.readline([n]); эта функция читает одну строку из объекта p. p может быть файловым объектом или любым объектом с методом readline(). Если n равно 0, читается ровно одна строка независимо от её длины. Если n больше 0, из файла будет прочитано не более n байт; может быть возвращена неполная строка. В обоих случаях возвращается пустая строка, если конец файла достигнут сразу. Однако, если n меньше 0, читается одна строка независимо от длины, но при немедленном достижении конца файла возбуждается 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() объекта вместо repr(). Возвращает 0 при успехе или -1 при ошибке; устанавливается соответствующее исключение.

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