Changeset 391 for python/trunk/Doc/c-api/file.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/c-api/file.rst (modified) (8 diffs)

python/trunk/Doc/c-api/file.rst

@@ -8 +8 @@
 .. index:: object: file
 
-Python's built-in file objects are implemented entirely on the :ctype:`FILE\*`
+Python's built-in file objects are implemented entirely on the :c:type:`FILE\*`
 support from the C standard library.  This is an implementation detail and may
 change in future releases of Python.
 
 
-.. ctype:: PyFileObject
+.. c:type:: PyFileObject
 
-   This subtype of :ctype:`PyObject` represents a Python file object.
+   This subtype of :c:type:`PyObject` represents a Python file object.
 
 
-.. cvar:: PyTypeObject PyFile_Type
+.. c:var:: PyTypeObject PyFile_Type
 
    .. index:: single: FileType (in module types)
 
-   This instance of :ctype:`PyTypeObject` represents the Python file type.  This is
+   This instance of :c:type:`PyTypeObject` represents the Python file type.  This is
    exposed to Python programs as ``file`` and ``types.FileType``.
 
 
-.. cfunction:: int PyFile_Check(PyObject *p)
+.. c:function:: int PyFile_Check(PyObject *p)
 
-   Return true if its argument is a :ctype:`PyFileObject` or a subtype of
-   :ctype:`PyFileObject`.
+   Return true if its argument is a :c:type:`PyFileObject` or a subtype of
+   :c:type:`PyFileObject`.
 
    .. versionchanged:: 2.2
@@ -35 +35 @@
 
 
-.. cfunction:: int PyFile_CheckExact(PyObject *p)
+.. c:function:: int PyFile_CheckExact(PyObject *p)
 
-   Return true if its argument is a :ctype:`PyFileObject`, but not a subtype of
-   :ctype:`PyFileObject`.
+   Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of
+   :c:type:`PyFileObject`.
 
    .. versionadded:: 2.2
 
 
-.. cfunction:: PyObject* PyFile_FromString(char *filename, char *mode)
+.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode)
 
    .. index:: single: fopen()
@@ -49 +49 @@
    On success, return a new file object that is opened on the file given by
    *filename*, with a file mode given by *mode*, where *mode* has the same
-   semantics as the standard C routine :cfunc:`fopen`.  On failure, return *NULL*.
+   semantics as the standard C routine :c:func:`fopen`.  On failure, return *NULL*.
 
 
-.. cfunction:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
+.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*))
 
-   Create a new :ctype:`PyFileObject` from the already-open standard C file
+   Create a new :c:type:`PyFileObject` from the already-open standard C file
    pointer, *fp*.  The function *close* will be called when the file should be
-   closed.  Return *NULL* on failure.
+   closed.  Return *NULL* and close the file using *close* on failure.
+   *close* is optional and can be set to *NULL*.
 
 
-.. cfunction:: FILE* PyFile_AsFile(PyObject \*p)
+.. c:function:: FILE* PyFile_AsFile(PyObject \*p)
 
-   Return the file object associated with *p* as a :ctype:`FILE\*`.
+   Return the file object associated with *p* as a :c:type:`FILE\*`.
 
-   If the caller will ever use the returned :ctype:`FILE\*` object while
-   the GIL is released it must also call the :cfunc:`PyFile_IncUseCount` and
-   :cfunc:`PyFile_DecUseCount` functions described below as appropriate.
+   If the caller will ever use the returned :c:type:`FILE\*` object while
+   the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and
+   :c:func:`PyFile_DecUseCount` functions described below as appropriate.
 
 
-.. cfunction:: void PyFile_IncUseCount(PyFileObject \*p)
+.. c:function:: void PyFile_IncUseCount(PyFileObject \*p)
 
    Increments the PyFileObject's internal use count to indicate
-   that the underlying :ctype:`FILE\*` is being used.
+   that the underlying :c:type:`FILE\*` is being used.
    This prevents Python from calling f_close() on it from another thread.
-   Callers of this must call :cfunc:`PyFile_DecUseCount` when they are
-   finished with the :ctype:`FILE\*`.  Otherwise the file object will
+   Callers of this must call :c:func:`PyFile_DecUseCount` when they are
+   finished with the :c:type:`FILE\*`.  Otherwise the file object will
    never be closed by Python.
 
-   The GIL must be held while calling this function.
+   The :term:`GIL` must be held while calling this function.
 
-   The suggested use is to call this after :cfunc:`PyFile_AsFile` just before
-   you release the GIL.
+   The suggested use is to call this after :c:func:`PyFile_AsFile` and before
+   you release the GIL::
+
+      FILE *fp = PyFile_AsFile(p);
+      PyFile_IncUseCount(p);
+      /* ... */
+      Py_BEGIN_ALLOW_THREADS
+      do_something(fp);
+      Py_END_ALLOW_THREADS
+      /* ... */
+      PyFile_DecUseCount(p);
 
    .. versionadded:: 2.6
 
 
-.. cfunction:: void PyFile_DecUseCount(PyFileObject \*p)
+.. c:function:: void PyFile_DecUseCount(PyFileObject \*p)
 
    Decrements the PyFileObject's internal unlocked_count member to
-   indicate that the caller is done with its own use of the :ctype:`FILE\*`.
-   This may only be called to undo a prior call to :cfunc:`PyFile_IncUseCount`.
+   indicate that the caller is done with its own use of the :c:type:`FILE\*`.
+   This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`.
 
-   The GIL must be held while calling this function.
+   The :term:`GIL` must be held while calling this function (see the example
+   above).
 
    .. versionadded:: 2.6
 
 
-.. cfunction:: PyObject* PyFile_GetLine(PyObject *p, int n)
+.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
 
    .. index:: single: EOFError (built-in exception)
 
    Equivalent to ``p.readline([n])``, this function reads one line from the
-   object *p*.  *p* may be a file object or any object with a :meth:`readline`
+   object *p*.  *p* may be a file object or any object with a
+   :meth:`~io.IOBase.readline`
    method.  If *n* is ``0``, exactly one line is read, regardless of the length of
    the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
@@ -110 +122 @@
 
 
-.. cfunction:: PyObject* PyFile_Name(PyObject *p)
+.. c:function:: PyObject* PyFile_Name(PyObject *p)
 
    Return the name of the file specified by *p* as a string object.
 
 
-.. cfunction:: void PyFile_SetBufSize(PyFileObject *p, int n)
+.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n)
 
    .. index:: single: setvbuf()
 
-   Available on systems with :cfunc:`setvbuf` only.  This should only be called
+   Available on systems with :c:func:`setvbuf` only.  This should only be called
    immediately after file object creation.
 
 
-.. cfunction:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
+.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc)
 
    Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0
@@ -131 +143 @@
 
 
-.. cfunction:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
+.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors)
 
    Set the file's encoding for Unicode output to *enc*, and its error
@@ -139 +151 @@
 
 
-.. cfunction:: int PyFile_SoftSpace(PyObject *p, int newflag)
+.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag)
 
    .. index:: single: softspace (file attribute)
@@ -153 +165 @@
 
 
-.. cfunction:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
 
    .. index:: single: Py_PRINT_RAW
@@ -163 +175 @@
 
 
-.. cfunction:: int PyFile_WriteString(const char *s, PyObject *p)
+.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
 
    Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on