8 .. index:: object: file
10 Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
11 support from the C standard library. This is an implementation detail and may
12 change in future releases of Python.
15 .. ctype:: PyFileObject
17 This subtype of :ctype:`PyObject` represents a Python file object.
20 .. cvar:: PyTypeObject PyFile_Type
22 .. index:: single: FileType (in module types)
24 This instance of :ctype:`PyTypeObject` represents the Python file type. This is
25 exposed to Python programs as ``file`` and ``types.FileType``.
28 .. cfunction:: int PyFile_Check(PyObject *p)
30 Return true if its argument is a :ctype:`PyFileObject` or a subtype of
31 :ctype:`PyFileObject`.
33 .. versionchanged:: 2.2
34 Allowed subtypes to be accepted.
37 .. cfunction:: int PyFile_CheckExact(PyObject *p)
39 Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
40 :ctype:`PyFileObject`.
45 .. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
47 .. index:: single: fopen()
49 On success, return a new file object that is opened on the file given by
50 *filename*, with a file mode given by *mode*, where *mode* has the same
51 semantics as the standard C routine :cfunc:`fopen`. On failure, return *NULL*.
54 .. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
56 Create a new :ctype:`PyFileObject` from the already-open standard C file
57 pointer, *fp*. The function *close* will be called when the file should be
58 closed. Return *NULL* on failure.
61 .. cfunction:: FILE* PyFile_AsFile(PyObject *p)
63 Return the file object associated with *p* as a :ctype:`FILE\*`.
66 .. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
68 .. index:: single: EOFError (built-in exception)
70 Equivalent to ``p.readline([n])``, this function reads one line from the
71 object *p*. *p* may be a file object or any object with a :meth:`readline`
72 method. If *n* is ``0``, exactly one line is read, regardless of the length of
73 the line. If *n* is greater than ``0``, no more than *n* bytes will be read
74 from the file; a partial line can be returned. In both cases, an empty string
75 is returned if the end of the file is reached immediately. If *n* is less than
76 ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
77 raised if the end of the file is reached immediately.
80 .. cfunction:: PyObject* PyFile_Name(PyObject *p)
82 Return the name of the file specified by *p* as a string object.
85 .. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
87 .. index:: single: setvbuf()
89 Available on systems with :cfunc:`setvbuf` only. This should only be called
90 immediately after file object creation.
93 .. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
95 Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
101 .. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
103 .. index:: single: softspace (file attribute)
105 This function exists for internal use by the interpreter. Set the
106 :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
107 *p* does not have to be a file object for this function to work properly; any
108 object is supported (thought its only interesting if the :attr:`softspace`
109 attribute can be set). This function clears any errors, and will return ``0``
110 as the previous value if the attribute either does not exist or if there were
111 errors in retrieving it. There is no way to detect errors from this function,
112 but doing so should not be needed.
115 .. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
117 .. index:: single: Py_PRINT_RAW
119 Write object *obj* to file object *p*. The only supported flag for *flags* is
120 :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
121 instead of the :func:`repr`. Return ``0`` on success or ``-1`` on failure; the
122 appropriate exception will be set.
125 .. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
127 Write string *s* to file object *p*. Return ``0`` on success or ``-1`` on
128 failure; the appropriate exception will be set.