From: R David Murray <rdmurray@bitdance.com>
Date: Sat, 18 Aug 2012 00:38:19 +0000 (-0400)
Subject: Merge #15694: Link discussion of file objects to glossary entry.
X-Git-Tag: v3.3.0rc1~88
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=8eac575e817f6874f3dd34b0b6bed5c8b1011131;p=thirdparty%2FPython%2Fcpython.git

Merge #15694: Link discussion of file objects to glossary entry.

This is analogous to the link for `flie objects` in the description of
'open' that exists in the 2.7 docs, and adds a similar link to the
io docs.

Patch by Chris Jerdonek.
---

8eac575e817f6874f3dd34b0b6bed5c8b1011131
diff --cc Doc/library/functions.rst
index de29a1ae22c0,753541f41d32..e063895428bb
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@@ -787,10 -790,13 +787,13 @@@ are always available.  They are listed 
     :meth:`__index__` method that returns an integer.
  
  
+    .. index::
+       single: file object; open() built-in function
+ 
 -.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True)
 +.. function:: open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)
  
-    Open *file* and return a corresponding stream.  If the file cannot be opened,
-    an :exc:`OSError` is raised.
+    Open *file* and return a corresponding :term:`file object`.  If the file
 -   cannot be opened, an :exc:`IOError` is raised.
++   cannot be opened, an :exc:`OSError` is raised.
  
     *file* is either a string or bytes object giving the pathname (absolute or
     relative to the current working directory) of the file to be opened or
@@@ -900,17 -903,8 +903,18 @@@
     closed.  If a filename is given *closefd* has no effect and must be ``True``
     (the default).
  
 +   A custom opener can be used by passing a callable as *opener*. The underlying
 +   file descriptor for the file object is then obtained by calling *opener* with
 +   (*file*, *flags*). *opener* must return an open file descriptor (passing
 +   :mod:`os.open` as *opener* results in functionality similar to passing
 +   ``None``).
 +
 +   .. versionchanged:: 3.3
 +      The *opener* parameter was added.
 +      The ``'x'`` mode was added.
 +
-    The type of file object returned by the :func:`open` function depends on the
+    The type of :term:`file object` returned by the :func:`open` function
+    depends on the
     mode.  When :func:`open` is used to open a file in a text mode (``'w'``,
     ``'r'``, ``'wt'``, ``'rt'``, etc.), it returns a subclass of
     :class:`io.TextIOBase` (specifically :class:`io.TextIOWrapper`).  When used