/Doc/c-api/file.rst

  1.. highlightlang:: c
  2
  3.. _fileobjects:
  4
  5File Objects
  6------------
  7
  8.. index:: object: file
  9
 10Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
 11support from the C standard library.  This is an implementation detail and may
 12change in future releases of Python.
 13
 14
 15.. ctype:: PyFileObject
 16
 17   This subtype of :ctype:`PyObject` represents a Python file object.
 18
 19
 20.. cvar:: PyTypeObject PyFile_Type
 21
 22   .. index:: single: FileType (in module types)
 23
 24   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
 25   exposed to Python programs as ``file`` and ``types.FileType``.
 26
 27
 28.. cfunction:: int PyFile_Check(PyObject *p)
 29
 30   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
 31   :ctype:`PyFileObject`.
 32
 33   .. versionchanged:: 2.2
 34      Allowed subtypes to be accepted.
 35
 36
 37.. cfunction:: int PyFile_CheckExact(PyObject *p)
 38
 39   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
 40   :ctype:`PyFileObject`.
 41
 42   .. versionadded:: 2.2
 43
 44
 45.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
 46
 47   .. index:: single: fopen()
 48
 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*.
 52
 53
 54.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
 55
 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.
 59
 60
 61.. cfunction:: FILE* PyFile_AsFile(PyObject \*p)
 62
 63   Return the file object associated with *p* as a :ctype:`FILE\*`.
 64
 65   If the caller will ever use the returned :ctype:`FILE\*` object while
 66   the GIL is released it must also call the :cfunc:`PyFile_IncUseCount` and
 67   :cfunc:`PyFile_DecUseCount` functions described below as appropriate.
 68
 69
 70.. cfunction:: void PyFile_IncUseCount(PyFileObject \*p)
 71
 72   Increments the PyFileObject's internal use count to indicate
 73   that the underlying :ctype:`FILE\*` is being used.
 74   This prevents Python from calling f_close() on it from another thread.
 75   Callers of this must call :cfunc:`PyFile_DecUseCount` when they are
 76   finished with the :ctype:`FILE\*`.  Otherwise the file object will
 77   never be closed by Python.
 78
 79   The GIL must be held while calling this function.
 80
 81   The suggested use is to call this after :cfunc:`PyFile_AsFile` just before
 82   you release the GIL.
 83
 84   .. versionadded:: 2.6
 85
 86
 87.. cfunction:: void PyFile_DecUseCount(PyFileObject \*p)
 88
 89   Decrements the PyFileObject's internal unlocked_count member to
 90   indicate that the caller is done with its own use of the :ctype:`FILE\*`.
 91   This may only be called to undo a prior call to :cfunc:`PyFile_IncUseCount`.
 92
 93   The GIL must be held while calling this function.
 94
 95   .. versionadded:: 2.6
 96
 97
 98.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
 99
100   .. index:: single: EOFError (built-in exception)
101
102   Equivalent to ``p.readline([n])``, this function reads one line from the
103   object *p*.  *p* may be a file object or any object with a :meth:`readline`
104   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
105   the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
106   from the file; a partial line can be returned.  In both cases, an empty string
107   is returned if the end of the file is reached immediately.  If *n* is less than
108   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
109   raised if the end of the file is reached immediately.
110
111
112.. cfunction:: PyObject* PyFile_Name(PyObject *p)
113
114   Return the name of the file specified by *p* as a string object.
115
116
117.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
118
119   .. index:: single: setvbuf()
120
121   Available on systems with :cfunc:`setvbuf` only.  This should only be called
122   immediately after file object creation.
123
124
125.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
126
127   Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
128   on failure.
129
130   .. versionadded:: 2.3
131
132
133.. cfunction:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
134
135   Set the file's encoding for Unicode output to *enc*, and its error
136   mode to *err*. Return 1 on success and 0 on failure.
137
138   .. versionadded:: 2.6
139
140
141.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
142
143   .. index:: single: softspace (file attribute)
144
145   This function exists for internal use by the interpreter.  Set the
146   :attr:`softspace` attribute of *p* to *newflag* and return the previous value.
147   *p* does not have to be a file object for this function to work properly; any
148   object is supported (thought its only interesting if the :attr:`softspace`
149   attribute can be set).  This function clears any errors, and will return ``0``
150   as the previous value if the attribute either does not exist or if there were
151   errors in retrieving it.  There is no way to detect errors from this function,
152   but doing so should not be needed.
153
154
155.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
156
157   .. index:: single: Py_PRINT_RAW
158
159   Write object *obj* to file object *p*.  The only supported flag for *flags* is
160   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
161   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
162   appropriate exception will be set.
163
164
165.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
166
167   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
168   failure; the appropriate exception will be set.