summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Doc/faq/design.rst4
-rw-r--r--Doc/faq/library.rst45
-rw-r--r--Doc/glossary.rst17
-rw-r--r--Doc/library/aifc.rst8
-rw-r--r--Doc/library/array.rst12
-rw-r--r--Doc/library/asyncore.rst6
-rw-r--r--Doc/library/base64.rst15
-rw-r--r--Doc/library/bz2.rst4
-rw-r--r--Doc/library/configparser.rst2
-rw-r--r--Doc/library/csv.rst6
-rw-r--r--Doc/library/email.generator.rst6
-rw-r--r--Doc/library/email.parser.rst6
-rw-r--r--Doc/library/exceptions.rst4
-rw-r--r--Doc/library/filesys.rst4
-rw-r--r--Doc/library/formatter.rst8
-rw-r--r--Doc/library/ftplib.rst14
-rw-r--r--Doc/library/gettext.rst6
-rw-r--r--Doc/library/gzip.rst9
-rw-r--r--Doc/library/http.client.rst2
-rw-r--r--Doc/library/imp.rst4
-rw-r--r--Doc/library/mmap.rst15
-rw-r--r--Doc/library/nntplib.rst40
-rw-r--r--Doc/library/os.rst16
-rw-r--r--Doc/library/pickle.rst29
-rw-r--r--Doc/library/quopri.rst24
-rw-r--r--Doc/library/select.rst11
-rw-r--r--Doc/library/socket.rst2
-rw-r--r--Doc/library/stdtypes.rst6
-rw-r--r--Doc/library/subprocess.rst18
-rw-r--r--Doc/library/sys.rst8
-rw-r--r--Doc/library/tarfile.rst18
-rw-r--r--Doc/library/tempfile.rst2
-rw-r--r--Doc/library/termios.rst2
-rw-r--r--Doc/library/weakref.rst5
-rw-r--r--Doc/library/xml.etree.elementtree.rst17
-rw-r--r--Doc/reference/datamodel.rst6
-rw-r--r--Doc/tutorial/inputoutput.rst4
37 files changed, 218 insertions, 187 deletions
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index 87f8742..c20de00 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -209,8 +209,8 @@ have to remember to change two places in your program -- the second occurrence
is hidden at the bottom of the loop.
The best approach is to use iterators, making it possible to loop through
-objects using the ``for`` statement. For example, in the current version of
-Python file objects support the iterator protocol, so you can now write simply::
+objects using the ``for`` statement. For example, :term:`file objects
+<file object>` support the iterator protocol, so you can write simply::
for line in f:
... # do something with line...
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index b409bb6..c59b38f 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -454,7 +454,7 @@ contents, use :func:`shutil.rmtree`.
To rename a file, use ``os.rename(old_path, new_path)``.
-To truncate a file, open it using ``f = open(filename, "r+")``, and use
+To truncate a file, open it using ``f = open(filename, "rb+")``, and use
``f.truncate(offset)``; offset defaults to the current seek position. There's
also ```os.ftruncate(fd, offset)`` for files opened with :func:`os.open`, where
``fd`` is the file descriptor (a small integer).
@@ -483,9 +483,9 @@ in big-endian format from a file::
import struct
- f = open(filename, "rb") # Open in binary mode for portability
- s = f.read(8)
- x, y, z = struct.unpack(">hhl", s)
+ with open(filename, "rb") as f:
+ s = f.read(8)
+ x, y, z = struct.unpack(">hhl", s)
The '>' in the format string forces big-endian data; the letter 'h' reads one
"short integer" (2 bytes), and 'l' reads one "long integer" (4 bytes) from the
@@ -494,6 +494,13 @@ string.
For data that is more regular (e.g. a homogeneous list of ints or thefloats),
you can also use the :mod:`array` module.
+ .. note::
+ To read and write binary data, it is mandatory to open the file in
+ binary mode (here, passing ``"rb"`` to :func:`open`). If you use
+ ``"r"`` instead (the default), the file will be open in text mode
+ and ``f.read()`` will return :class:`str` objects rather than
+ :class:`bytes` objects.
+
I can't seem to use os.read() on a pipe created with os.popen(); why?
---------------------------------------------------------------------
@@ -597,27 +604,29 @@ For Unix, see a Usenet post by Mitch Chapman:
Why doesn't closing sys.stdout (stdin, stderr) really close it?
---------------------------------------------------------------
-Python file objects are a high-level layer of abstraction on top of C streams,
-which in turn are a medium-level layer of abstraction on top of (among other
-things) low-level C file descriptors.
+Python :term:`file objects <file object>` are a high-level layer of
+abstraction on low-level C file descriptors.
-For most file objects you create in Python via the builtin ``file`` constructor,
-``f.close()`` marks the Python file object as being closed from Python's point
-of view, and also arranges to close the underlying C stream. This also happens
-automatically in f's destructor, when f becomes garbage.
+For most file objects you create in Python via the built-in :func:`open`
+function, ``f.close()`` marks the Python file object as being closed from
+Python's point of view, and also arranges to close the underlying C file
+descriptor. This also happens automatically in ``f``'s destructor, when
+``f`` becomes garbage.
But stdin, stdout and stderr are treated specially by Python, because of the
special status also given to them by C. Running ``sys.stdout.close()`` marks
the Python-level file object as being closed, but does *not* close the
-associated C stream.
+associated C file descriptor.
+
+To close the underlying C file descriptor for one of these three, you should
+first be sure that's what you really want to do (e.g., you may confuse
+extension modules trying to do I/O). If it is, use :func:`os.close`::
-To close the underlying C stream for one of these three, you should first be
-sure that's what you really want to do (e.g., you may confuse extension modules
-trying to do I/O). If it is, use os.close::
+ os.close(stdin.fileno())
+ os.close(stdout.fileno())
+ os.close(stderr.fileno())
- os.close(0) # close C's stdin stream
- os.close(1) # close C's stdout stream
- os.close(2) # close C's stderr stream
+Or you can use the numeric constants 0, 1 and 2, respectively.
Network/Internet Programming
diff --git a/Doc/glossary.rst b/Doc/glossary.rst
index 40f0869..5ecf848 100644
--- a/Doc/glossary.rst
+++ b/Doc/glossary.rst
@@ -178,6 +178,23 @@ Glossary
A module written in C or C++, using Python's C API to interact with the core and
with user code.
+ file object
+ An object exposing a file-oriented API (with methods such as
+ :meth:`read()` or :meth:`write()`) to an underlying resource.
+ Depending on the way it was created, a file object can mediate access
+ to a real on-disk file or to another other type of storage or
+ communication device (for example standard input/output, in-memory
+ buffers, sockets, pipes, etc.). File objects are also called
+ :dfn:`file-like objects` or :dfn:`streams`.
+
+ There are actually three categories of file objects: raw binary
+ files, buffered binary files and text files. Their interfaces are
+ defined in the :mod:`io` module. The canonical way to create a
+ file object is by using the :func:`open` function.
+
+ file-like object
+ A synonym for :term:`file object`.
+
finder
An object that tries to find the :term:`loader` for a module. It must
implement a method named :meth:`find_module`. See :pep:`302` for
diff --git a/Doc/library/aifc.rst b/Doc/library/aifc.rst
index bdd3517..304437d 100644
--- a/Doc/library/aifc.rst
+++ b/Doc/library/aifc.rst
@@ -40,10 +40,10 @@ Module :mod:`aifc` defines the following function:
.. function:: open(file, mode=None)
Open an AIFF or AIFF-C file and return an object instance with methods that are
- described below. The argument *file* is either a string naming a file or a file
- object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
- reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
- omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
+ described below. The argument *file* is either a string naming a file or a
+ :term:`file object`. *mode* must be ``'r'`` or ``'rb'`` when the file must be
+ opened for reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing.
+ If omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
used for writing, the file object should be seekable, unless you know ahead of
time how many samples you are going to write in total and use
:meth:`writeframesraw` and :meth:`setnframes`.
diff --git a/Doc/library/array.rst b/Doc/library/array.rst
index 2235f08..3f5f9e6 100644
--- a/Doc/library/array.rst
+++ b/Doc/library/array.rst
@@ -138,11 +138,11 @@ The following data items and methods are also supported:
.. method:: array.fromfile(f, n)
- Read *n* items (as machine values) from the file object *f* and append them to
- the end of the array. If less than *n* items are available, :exc:`EOFError` is
- raised, but the items that were available are still inserted into the array.
- *f* must be a real built-in file object; something else with a :meth:`read`
- method won't do.
+ Read *n* items (as machine values) from the :term:`file object` *f* and append
+ them to the end of the array. If less than *n* items are available,
+ :exc:`EOFError` is raised, but the items that were available are still
+ inserted into the array. *f* must be a real built-in file object; something
+ else with a :meth:`read` method won't do.
.. method:: array.fromlist(list)
@@ -196,7 +196,7 @@ The following data items and methods are also supported:
.. method:: array.tofile(f)
- Write all items (as machine values) to the file object *f*.
+ Write all items (as machine values) to the :term:`file object` *f*.
.. method:: array.tolist()
diff --git a/Doc/library/asyncore.rst b/Doc/library/asyncore.rst
index 60d4d03..8cdfe20 100644
--- a/Doc/library/asyncore.rst
+++ b/Doc/library/asyncore.rst
@@ -224,9 +224,9 @@ any that have been added to the map during asynchronous service) is closed.
.. class:: file_dispatcher()
- A file_dispatcher takes a file descriptor or file object along with an
- optional map argument and wraps it for use with the :cfunc:`poll` or
- :cfunc:`loop` functions. If provided a file object or anything with a
+ A file_dispatcher takes a file descriptor or :term:`file object` along
+ with an optional map argument and wraps it for use with the :cfunc:`poll`
+ or :cfunc:`loop` functions. If provided a file object or anything with a
:cfunc:`fileno` method, that method will be called and passed to the
:class:`file_wrapper` constructor. Availability: UNIX.
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 9ff065a..651f889 100644
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -122,9 +122,9 @@ The legacy interface:
.. function:: decode(input, output)
Decode the contents of the binary *input* file and write the resulting binary
- data to the *output* file. *input* and *output* must either be file objects
- or objects that mimic the file object interface working with bytes
- objects. *input* will be read until ``input.read()`` returns an empty string.
+ data to the *output* file. *input* and *output* must be :term:`file objects
+ <file object>`. *input* will be read until ``input.read()`` returns an empty
+ bytes object.
.. function:: decodebytes(s)
@@ -138,11 +138,10 @@ The legacy interface:
.. function:: encode(input, output)
Encode the contents of the binary *input* file and write the resulting base64
- encoded data to the *output* file. *input* and *output* must either be file
- objects or objects that mimic the file object interface working with bytes
- objects. *input* will be read until ``input.read()`` returns an empty string.
- :func:`encode` returns the encoded data plus a trailing newline character
- (``b'\n'``).
+ encoded data to the *output* file. *input* and *output* must be :term:`file
+ objects <file object>`. *input* will be read until ``input.read()`` returns
+ an empty bytes object. :func:`encode` returns the encoded data plus a trailing
+ newline character (``b'\n'``).
.. function:: encodebytes(s)
diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index 6f01dd3..d9a2bad 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -25,8 +25,8 @@ Here is a summary of the features offered by the bz2 module:
* :class:`BZ2File` class implements universal newline support;
-* :class:`BZ2File` class offers an optimized line iteration using the readahead
- algorithm borrowed from file objects;
+* :class:`BZ2File` class offers an optimized line iteration using a readahead
+ algorithm;
* Sequential (de)compression supported by :class:`BZ2Compressor` and
:class:`BZ2Decompressor` classes;
diff --git a/Doc/library/configparser.rst b/Doc/library/configparser.rst
index 5ddfcd7..1afdf50 100644
--- a/Doc/library/configparser.rst
+++ b/Doc/library/configparser.rst
@@ -298,7 +298,7 @@ RawConfigParser Objects
.. method:: RawConfigParser.write(fileobject)
- Write a representation of the configuration to the specified file object,
+ Write a representation of the configuration to the specified :term:`file object`,
which must be opened in text mode (accepting strings). This representation
can be parsed by a future :meth:`read` call.
diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst
index 510d35a..e75f00a 100644
--- a/Doc/library/csv.rst
+++ b/Doc/library/csv.rst
@@ -50,9 +50,9 @@ The :mod:`csv` module defines the following functions:
Return a reader object which will iterate over lines in the given *csvfile*.
*csvfile* can be any object which supports the :term:`iterator` protocol and returns a
- string each time its :meth:`!next` method is called --- file objects and list
- objects are both suitable. If *csvfile* is a file object, it should be opened
- with ``newline=''``. [#]_ An optional
+ string each time its :meth:`!next` method is called --- :term:`file objects
+ <file object>` and list objects are both suitable. If *csvfile* is a file object,
+ it should be opened with ``newline=''``. [#]_ An optional
*dialect* parameter can be given which is used to define a set of parameters
specific to a particular CSV dialect. It may be an instance of a subclass of
the :class:`Dialect` class or one of the strings returned by the
diff --git a/Doc/library/email.generator.rst b/Doc/library/email.generator.rst
index ba38f68..930905a 100644
--- a/Doc/library/email.generator.rst
+++ b/Doc/library/email.generator.rst
@@ -28,9 +28,9 @@ Here are the public methods of the :class:`Generator` class, imported from the
.. class:: Generator(outfp, mangle_from_=True, maxheaderlen=78)
- The constructor for the :class:`Generator` class takes a file-like object called
- *outfp* for an argument. *outfp* must support the :meth:`write` method and be
- usable as the output file for the :func:`print` function.
+ The constructor for the :class:`Generator` class takes a :term:`file-like object`
+ called *outfp* for an argument. *outfp* must support the :meth:`write` method
+ and be usable as the output file for the :func:`print` function.
Optional *mangle_from_* is a flag that, when ``True``, puts a ``>`` character in
front of any line in the body that starts exactly as ``From``, i.e. ``From``
diff --git a/Doc/library/email.parser.rst b/Doc/library/email.parser.rst
index 3de5c31..32f4ff1 100644
--- a/Doc/library/email.parser.rst
+++ b/Doc/library/email.parser.rst
@@ -154,9 +154,9 @@ in the top-level :mod:`email` package namespace.
.. function:: message_from_file(fp[, _class][, strict])
- Return a message object structure tree from an open file object. This is
- exactly equivalent to ``Parser().parse(fp)``. Optional *_class* and *strict*
- are interpreted as with the :class:`Parser` class constructor.
+ Return a message object structure tree from an open :term:`file object`.
+ This is exactly equivalent to ``Parser().parse(fp)``. Optional *_class*
+ and *strict* are interpreted as with the :class:`Parser` class constructor.
Here's an example of how you might use this at an interactive Python prompt::
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index fb3ae94..ceebf5e 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -142,8 +142,8 @@ The following exceptions are the exceptions that are actually raised.
.. exception:: IOError
Raised when an I/O operation (such as the built-in :func:`print` or
- :func:`open` functions or a method of a file object) fails for an I/O-related
- reason, e.g., "file not found" or "disk full".
+ :func:`open` functions or a method of a :term:`file object`) fails for an
+ I/O-related reason, e.g., "file not found" or "disk full".
This class is derived from :exc:`EnvironmentError`. See the discussion above
for more information on exception instance attributes.
diff --git a/Doc/library/filesys.rst b/Doc/library/filesys.rst
index 31eaf0d..58998a8 100644
--- a/Doc/library/filesys.rst
+++ b/Doc/library/filesys.rst
@@ -27,8 +27,8 @@ in this chapter is:
.. seealso::
Module :mod:`os`
- Operating system interfaces, including functions to work with files at a lower
- level than the built-in file object.
+ Operating system interfaces, including functions to work with files at a
+ lower level than Python :term:`file objects <file object>`.
Module :mod:`io`
Python's built-in I/O library, including both abstract classes and
diff --git a/Doc/library/formatter.rst b/Doc/library/formatter.rst
index 0a459a6..88be11c 100644
--- a/Doc/library/formatter.rst
+++ b/Doc/library/formatter.rst
@@ -339,8 +339,8 @@ this module. Most applications will need to derive new writer classes from the
.. class:: DumbWriter(file=None, maxcol=72)
- Simple writer class which writes output on the file object passed in as *file*
- or, if *file* is omitted, on standard output. The output is simply word-wrapped
- to the number of columns specified by *maxcol*. This class is suitable for
- reflowing a sequence of paragraphs.
+ Simple writer class which writes output on the :term:`file object` passed
+ in as *file* or, if *file* is omitted, on standard output. The output is
+ simply word-wrapped to the number of columns specified by *maxcol*. This
+ class is suitable for reflowing a sequence of paragraphs.
diff --git a/Doc/library/ftplib.rst b/Doc/library/ftplib.rst
index c85e0b3..75a8fb1 100644
--- a/Doc/library/ftplib.rst
+++ b/Doc/library/ftplib.rst
@@ -194,19 +194,19 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
.. method:: FTP.storbinary(cmd, file, blocksize=8192, callback=None)
Store a file in binary transfer mode. *cmd* should be an appropriate
- ``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
- read until EOF using its :meth:`read` method in blocks of size *blocksize* to
- provide the data to be stored. The *blocksize* argument defaults to 8192.
- *callback* is an optional single parameter callable that is called
- on each block of data after it is sent.
+ ``STOR`` command: ``"STOR filename"``. *file* is an open :term:`file object`
+ which is read until EOF using its :meth:`read` method in blocks of size
+ *blocksize* to provide the data to be stored. The *blocksize* argument
+ defaults to 8192. *callback* is an optional single parameter callable that
+ is called on each block of data after it is sent.
.. method:: FTP.storlines(cmd, file, callback=None)
Store a file in ASCII transfer mode. *cmd* should be an appropriate
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
- open file object *file* using its :meth:`readline` method to provide the data to
- be stored. *callback* is an optional single parameter callable
+ open :term:`file object` *file* using its :meth:`readline` method to provide
+ the data to be stored. *callback* is an optional single parameter callable
that is called on each line after it is sent.
diff --git a/Doc/library/gettext.rst b/Doc/library/gettext.rst
index eba59c8..9e1528b 100644
--- a/Doc/library/gettext.rst
+++ b/Doc/library/gettext.rst
@@ -173,8 +173,8 @@ class can also install themselves in the built-in namespace as the function
associated :file:`.mo` file paths. Instances with identical :file:`.mo` file
names are cached. The actual class instantiated is either *class_* if
provided, otherwise :class:`GNUTranslations`. The class's constructor must
- take a single file object argument. If provided, *codeset* will change the
- charset used to encode translated strings in the :meth:`lgettext` and
+ take a single :term:`file object` argument. If provided, *codeset* will change
+ the charset used to encode translated strings in the :meth:`lgettext` and
:meth:`lngettext` methods.
If multiple files are found, later files are used as fallbacks for earlier ones.
@@ -219,7 +219,7 @@ are the methods of :class:`NullTranslations`:
.. class:: NullTranslations(fp=None)
- Takes an optional file object *fp*, which is ignored by the base class.
+ Takes an optional :term:`file object` *fp*, which is ignored by the base class.
Initializes "protected" instance variables *_info* and *_charset* which are set
by derived classes, as well as *_fallback*, which is set through
:meth:`add_fallback`. It then calls ``self._parse(fp)`` if *fp* is not
diff --git a/Doc/library/gzip.rst b/Doc/library/gzip.rst
index 894a423..fdd8590 100644
--- a/Doc/library/gzip.rst
+++ b/Doc/library/gzip.rst
@@ -9,10 +9,9 @@ like the GNU programs :program:`gzip` and :program:`gunzip` would.
The data compression is provided by the :mod:`zlib` module.
-The :mod:`gzip` module provides the :class:`GzipFile` class which is modeled
-after Python's File Object. The :class:`GzipFile` class reads and writes
-:program:`gzip`\ -format files, automatically compressing or decompressing the
-data so that it looks like an ordinary file object.
+The :mod:`gzip` module provides the :class:`GzipFile` class. The :class:`GzipFile`
+class reads and writes :program:`gzip`\ -format files, automatically compressing
+or decompressing the data so that it looks like an ordinary :term:`file object`.
Note that additional file formats which can be decompressed by the
:program:`gzip` and :program:`gunzip` programs, such as those produced by
@@ -27,7 +26,7 @@ The module defines the following items:
.. class:: GzipFile(filename=None, mode=None, compresslevel=9, fileobj=None, mtime=None)
Constructor for the :class:`GzipFile` class, which simulates most of the methods
- of a file object, with the exception of the :meth:`readinto` and
+ of a :term:`file object`, with the exception of the :meth:`readinto` and
:meth:`truncate` methods. At least one of *fileobj* and *filename* must be
given a non-trivial value.
diff --git a/Doc/library/http.client.rst b/Doc/library/http.client.rst
index fe65812..7cdbbcf 100644
--- a/Doc/library/http.client.rst
+++ b/Doc/library/http.client.rst
@@ -359,7 +359,7 @@ HTTPConnection Objects
object. The Content-Length header is set to the length of the
string.
- The *body* may also be an open file object, in which case the
+ The *body* may also be an open :term:`file object`, in which case the
contents of the file is sent; this file object should support
``fileno()`` and ``read()`` methods. The header Content-Length is
automatically set to the length of the file as reported by
diff --git a/Doc/library/imp.rst b/Doc/library/imp.rst
index b6123ae..5c21ee7 100644
--- a/Doc/library/imp.rst
+++ b/Doc/library/imp.rst
@@ -48,8 +48,8 @@ This module provides an interface to the mechanisms used to implement the
If search is successful, the return value is a 3-element tuple ``(file,
pathname, description)``:
- *file* is an open file object positioned at the beginning, *pathname* is the
- pathname of the file found, and *description* is a 3-element tuple as
+ *file* is an open :term:`file object` positioned at the beginning, *pathname*
+ is the pathname of the file found, and *description* is a 3-element tuple as
contained in the list returned by :func:`get_suffixes` describing the kind of
module found.
diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst
index 403e2f5..bb4a515 100644
--- a/Doc/library/mmap.rst
+++ b/Doc/library/mmap.rst
@@ -5,14 +5,13 @@
:synopsis: Interface to memory-mapped files for Unix and Windows.
-Memory-mapped file objects behave like both :class:`bytes` and like file
-objects. Unlike normal :class:`bytes` objects, however, these are mutable.
-You can use mmap objects in most places where :class:`bytes` are expected; for
-example, you can use the :mod:`re` module to search through a memory-mapped file.
-Since they're mutable, you can change a single byte by doing ``obj[index] = 97``,
-or change a subsequence by assigning to a slice: ``obj[i1:i2] = b'...'``.
-You can also read and write data starting at the current file position, and
-:meth:`seek` through the file to different positions.
+Memory-mapped file objects behave like both :class:`bytearray` and like
+:term:`file objects <file object>`. You can use mmap objects in most places
+where :class:`bytearray` are expected; for example, you can use the :mod:`re`
+module to search through a memory-mapped file. You can also change a single
+byte by doing ``obj[index] = 97``, or change a subsequence by assigning to a
+slice: ``obj[i1:i2] = b'...'``. You can also read and write data starting at
+the current file position, and :meth:`seek` through the file to different positions.
A memory-mapped file is created by the :class:`mmap` constructor, which is
different on Unix and on Windows. In either case you must provide a file
diff --git a/Doc/library/nntplib.rst b/Doc/library/nntplib.rst
index 700d6e0..c3cbd2b 100644
--- a/Doc/library/nntplib.rst
+++ b/Doc/library/nntplib.rst
@@ -143,9 +143,9 @@ indicates an error, the method raises one of the above exceptions.
*groups* is a list of group names that are new since the given date and time. If
the *file* parameter is supplied, then the output of the ``NEWGROUPS`` command
is stored in a file. If *file* is a string, then the method will open a file
- object with that name, write to it then close it. If *file* is a file object,
- then it will start calling :meth:`write` on it to store the lines of the command
- output. If *file* is supplied, then the returned *list* is an empty list.
+ object with that name, write to it then close it. If *file* is a :term:`file
+ object`, then it will start calling :meth:`write` on it to store the lines of
+ the command output. If *file* is supplied, then the returned *list* is an empty list.
.. method:: NNTP.newnews(group, date, time, [file])
@@ -155,9 +155,9 @@ indicates an error, the method raises one of the above exceptions.
``(response, articles)`` where *articles* is a list of message ids. If the
*file* parameter is supplied, then the output of the ``NEWNEWS`` command is
stored in a file. If *file* is a string, then the method will open a file
- object with that name, write to it then close it. If *file* is a file object,
- then it will start calling :meth:`write` on it to store the lines of the command
- output. If *file* is supplied, then the returned *list* is an empty list.
+ object with that name, write to it then close it. If *file* is a :term:`file
+ object`, then it will start calling :meth:`write` on it to store the lines of the
+ command output. If *file* is supplied, then the returned *list* is an empty list.
.. method:: NNTP.list([file])
@@ -169,9 +169,9 @@ indicates an error, the method raises one of the above exceptions.
not, and ``'m'`` if the newsgroup is moderated. (Note the ordering: *last*,
*first*.) If the *file* parameter is supplied, then the output of the ``LIST``
command is stored in a file. If *file* is a string, then the method will open
- a file object with that name, write to it then close it. If *file* is a file
- object, then it will start calling :meth:`write` on it to store the lines of the
- command output. If *file* is supplied, then the returned *list* is an empty
+ a file with that name, write to it then close it. If *file* is a :term:`file
+ object`, then it will start calling :meth:`write` on it to store the lines of
+ the command output. If *file* is supplied, then the returned *list* is an empty
list.
@@ -207,8 +207,8 @@ indicates an error, the method raises one of the above exceptions.
Send a ``HELP`` command. Return a pair ``(response, list)`` where *list* is a
list of help strings. If the *file* parameter is supplied, then the output of
the ``HELP`` command is stored in a file. If *file* is a string, then the
- method will open a file object with that name, write to it then close it. If
- *file* is a file object, then it will start calling :meth:`write` on it to store
+ method will open a file with that name, write to it then close it. If *file*
+ is a :term:`file object`, then it will start calling :meth:`write` on it to store
the lines of the command output. If *file* is supplied, then the returned *list*
is an empty list.
@@ -243,8 +243,8 @@ indicates an error, the method raises one of the above exceptions.
Send a ``BODY`` command, where *id* has the same meaning as for :meth:`stat`.
If the *file* parameter is supplied, then the body is stored in a file. If
- *file* is a string, then the method will open a file object with that name,
- write to it then close it. If *file* is a file object, then it will start
+ *file* is a string, then the method will open a file with that name, write
+ to it then close it. If *file* is a :term:`file object`, then it will start
calling :meth:`write` on it to store the lines of the body. Return as for
:meth:`head`. If *file* is supplied, then the returned *list* is an empty list.
@@ -270,9 +270,9 @@ indicates an error, the method raises one of the above exceptions.
text)``, where *id* is an article number (as a string) and *text* is the text of
the requested header for that article. If the *file* parameter is supplied, then
the output of the ``XHDR`` command is stored in a file. If *file* is a string,
- then the method will open a file object with that name, write to it then close
- it. If *file* is a file object, then it will start calling :meth:`write` on it
- to store the lines of the command output. If *file* is supplied, then the
+ then the method will open a file with that name, write to it then close it.
+ If *file* is a :term:`file object`, then it will start calling :meth:`write` on
+ it to store the lines of the command output. If *file* is supplied, then the
returned *list* is an empty list.
@@ -303,8 +303,8 @@ indicates an error, the method raises one of the above exceptions.
Process an ``XGTITLE`` command, returning a pair ``(response, list)``, where
*list* is a list of tuples containing ``(name, title)``. If the *file* parameter
is supplied, then the output of the ``XGTITLE`` command is stored in a file.
- If *file* is a string, then the method will open a file object with that name,
- write to it then close it. If *file* is a file object, then it will start
+ If *file* is a string, then the method will open a file with that name, write
+ to it then close it. If *file* is a :term:`file object`, then it will start
calling :meth:`write` on it to store the lines of the command output. If *file*
is supplied, then the returned *list* is an empty list. This is an optional NNTP
extension, and may not be supported by all servers.
@@ -320,8 +320,8 @@ indicates an error, the method raises one of the above exceptions.
tuple is of the form ``(article number, subject, poster, date, id, references,
size, lines)``. If the *file* parameter is supplied, then the output of the
``XOVER`` command is stored in a file. If *file* is a string, then the method
- will open a file object with that name, write to it then close it. If *file*
- is a file object, then it will start calling :meth:`write` on it to store the
+ will open a file with that name, write to it then close it. If *file* is a
+ :term:`file object`, then it will start calling :meth:`write` on it to store the
lines of the command output. If *file* is supplied, then the returned *list* is
an empty list. This is an optional NNTP extension, and may not be supported by
all servers.
diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 80955af..2fb8cd6 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -401,7 +401,7 @@ process and user.
File Object Creation
--------------------
-These functions create new file objects. (See also :func:`open`.)
+These functions create new :term:`file objects <file object>`. (See also :func:`open`.)
.. function:: fdopen(fd[, mode[, bufsize]])
@@ -436,6 +436,10 @@ process will then be assigned 3, 4, 5, and so forth. The name "file descriptor"
is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
by file descriptors.
+The :meth:`~file.fileno` method can be used to obtain the file descriptor
+associated with a :term:`file object` when required. Note that using the file
+descriptor directly will bypass the file object methods, ignoring aspects such
+as internal buffering of data.
.. function:: close(fd)
@@ -550,9 +554,9 @@ by file descriptors.
Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
- If you're starting with a Python file object *f*, first do ``f.flush()``, and
- then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
- with *f* are written to disk.
+ If you're starting with a buffered Python :term:`file object` *f*, first do
+ ``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
+ buffers associated with *f* are written to disk.
Availability: Unix, and Windows.
@@ -609,9 +613,9 @@ by file descriptors.
.. note::
This function is intended for low-level I/O. For normal usage, use the
- built-in function :func:`open`, which returns a "file object" with
+ built-in function :func:`open`, which returns a :term:`file object` with
:meth:`~file.read` and :meth:`~file.wprite` methods (and many more). To
- wrap a file descriptor in a "file object", use :func:`fdopen`.
+ wrap a file descriptor in a file object, use :func:`fdopen`.
.. function:: openpty()
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 21e4001..8157a52 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -143,8 +143,8 @@ process more convenient:
.. function:: dump(obj, file[, protocol, \*, fix_imports=True])
- Write a pickled representation of *obj* to the open file object *file*. This
- is equivalent to ``Pickler(file, protocol).dump(obj)``.
+ Write a pickled representation of *obj* to the open :term:`file object` *file*.
+ This is equivalent to ``Pickler(file, protocol).dump(obj)``.
The optional *protocol* argument tells the pickler to use the given protocol;
supported protocols are 0, 1, 2, 3. The default protocol is 3; a
@@ -155,8 +155,9 @@ process more convenient:
Python needed to read the pickle produced.
The *file* argument must have a write() method that accepts a single bytes
- argument. It can thus be a file object opened for binary writing, a
- io.BytesIO instance, or any other custom object that meets this interface.
+ argument. It can thus be an on-disk file opened for binary writing, a
+ :class:`io.BytesIO` instance, or any other custom object that meets this
+ interface.
If *fix_imports* is True and *protocol* is less than 3, pickle will try to
map the new Python 3.x names to the old module names used in Python 2.x,
@@ -181,8 +182,8 @@ process more convenient:
.. function:: load(file, [\*, fix_imports=True, encoding="ASCII", errors="strict"])
- Read a pickled object representation from the open file object *file* and
- return the reconstituted object hierarchy specified therein. This is
+ Read a pickled object representation from the open :term:`file object` *file*
+ and return the reconstituted object hierarchy specified therein. This is
equivalent to ``Unpickler(file).load()``.
The protocol version of the pickle is detected automatically, so no protocol
@@ -191,9 +192,9 @@ process more convenient:
The argument *file* must have two methods, a read() method that takes an
integer argument, and a readline() method that requires no arguments. Both
- methods should return bytes. Thus *file* can be a binary file object opened
- for reading, a BytesIO object, or any other custom object that meets this
- interface.
+ methods should return bytes. Thus *file* can be an on-disk file opened
+ for binary reading, a :class:`io.BytesIO` object, or any other custom object
+ that meets this interface.
Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
which are used to control compatiblity support for pickle stream generated
@@ -260,8 +261,8 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and
Python needed to read the pickle produced.
The *file* argument must have a write() method that accepts a single bytes
- argument. It can thus be a file object opened for binary writing, a
- io.BytesIO instance, or any other custom object that meets this interface.
+ argument. It can thus be an on-disk file opened for binary writing, a
+ :class:`io.BytesIO` instance, or any other custom object that meets this interface.
If *fix_imports* is True and *protocol* is less than 3, pickle will try to
map the new Python 3.x names to the old module names used in Python 2.x,
@@ -304,9 +305,9 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and
The argument *file* must have two methods, a read() method that takes an
integer argument, and a readline() method that requires no arguments. Both
- methods should return bytes. Thus *file* can be a binary file object opened
- for reading, a BytesIO object, or any other custom object that meets this
- interface.
+ methods should return bytes. Thus *file* can be an on-disk file object opened
+ for binary reading, a :class:`io.BytesIO` object, or any other custom object
+ that meets this interface.
Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
which are used to control compatiblity support for pickle stream generated
diff --git a/Doc/library/quopri.rst b/Doc/library/quopri.rst
index 8f525ef..a64337e 100644
--- a/Doc/library/quopri.rst
+++ b/Doc/library/quopri.rst
@@ -22,23 +22,23 @@ sending a graphics file.
.. function:: decode(input, output[,header])
Decode the contents of the *input* file and write the resulting decoded binary
- data to the *output* file. *input* and *output* must either be file objects or
- objects that mimic the file object interface. *input* will be read until
- ``input.readline()`` returns an empty string. If the optional argument *header*
- is present and true, underscore will be decoded as space. This is used to decode
- "Q"-encoded headers as described in :rfc:`1522`: "MIME (Multipurpose Internet
- Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text".
+ data to the *output* file. *input* and *output* must be :term:`file objects
+ <file object>`. *input* will be read until ``input.readline()`` returns an
+ empty string. If the optional argument *header* is present and true, underscore
+ will be decoded as space. This is used to decode "Q"-encoded headers as
+ described in :rfc:`1522`: "MIME (Multipurpose Internet Mail Extensions)
+ Part Two: Message Header Extensions for Non-ASCII Text".
.. function:: encode(input, output, quotetabs)
Encode the contents of the *input* file and write the resulting quoted-printable
- data to the *output* file. *input* and *output* must either be file objects or
- objects that mimic the file object interface. *input* will be read until
- ``input.readline()`` returns an empty string. *quotetabs* is a flag which
- controls whether to encode embedded spaces and tabs; when true it encodes such
- embedded whitespace, and when false it leaves them unencoded. Note that spaces
- and tabs appearing at the end of lines are always encoded, as per :rfc:`1521`.
+ data to the *output* file. *input* and *output* must be :term:`file objects
+ <file object>`. *input* will be read until ``input.readline()`` returns an
+ empty string. *quotetabs* is a flag which controls whether to encode embedded
+ spaces and tabs; when true it encodes such embedded whitespace, and when
+ false it leaves them unencoded. Note that spaces and tabs appearing at the
+ end of lines are always encoded, as per :rfc:`1521`.
.. function:: decodestring(s[,header])
diff --git a/Doc/library/select.rst b/Doc/library/select.rst
index f19cbdc..70f7370 100644
--- a/Doc/library/select.rst
+++ b/Doc/library/select.rst
@@ -79,11 +79,12 @@ The module defines the following:
single: socket() (in module socket)
single: popen() (in module os)
- Among the acceptable object types in the sequences are Python file objects (e.g.
- ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket
- objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper`
- class yourself, as long as it has an appropriate :meth:`fileno` method (that
- really returns a file descriptor, not just a random integer).
+ Among the acceptable object types in the sequences are Python :term:`file
+ objects <file object>` (e.g. ``sys.stdin``, or objects returned by
+ :func:`open` or :func:`os.popen`), socket objects returned by
+ :func:`socket.socket`. You may also define a :dfn:`wrapper` class yourself,
+ as long as it has an appropriate :meth:`fileno` method (that really returns
+ a file descriptor, not just a random integer).
.. note::
diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst
index 5314039..511d37b 100644
--- a/Doc/library/socket.rst
+++ b/Doc/library/socket.rst
@@ -592,7 +592,7 @@ correspond to Unix system calls applicable to sockets.
.. index:: single: I/O control; buffering
- Return a :dfn:`file object` associated with the socket. The exact
+ Return a :term:`file object` associated with the socket. The exact
returned type depends on the arguments given to :meth:`makefile`. These
arguments are interpreted the same way as by the built-in :func:`open`
function.
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index 694ff56..0a5b882 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -2210,9 +2210,9 @@ to be provided for a context manager object to define a runtime context:
the identifier in the :keyword:`as` clause of :keyword:`with` statements using
this context manager.
- An example of a context manager that returns itself is a file object. File
- objects return themselves from __enter__() to allow :func:`open` to be used as
- the context expression in a :keyword:`with` statement.
+ An example of a context manager that returns itself is a :term:`file object`.
+ File objects return themselves from __enter__() to allow :func:`open` to be
+ used as the context expression in a :keyword:`with` statement.
An example of a context manager that returns a related object is the one
returned by :func:`decimal.localcontext`. These managers set the active
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
index edba7a7..72ea8c6 100644
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -107,9 +107,9 @@ This module defines one class called :class:`Popen`:
*stdin*, *stdout* and *stderr* specify the executed programs' standard input,
standard output and standard error file handles, respectively. Valid values
are :data:`PIPE`, an existing file descriptor (a positive integer), an
- existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
- to the child should be created. With ``None``, no redirection will occur;
- the child's file handles will be inherited from the parent. Additionally,
+ existing :term:`file object`, and ``None``. :data:`PIPE` indicates that a
+ new pipe to the child should be created. With ``None``, no redirection will
+ occur; the child's file handles will be inherited from the parent. Additionally,
*stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
applications should be captured into the same file handle as for stdout.
@@ -377,20 +377,20 @@ The following attributes are also available:
.. attribute:: Popen.stdin
- If the *stdin* argument was :data:`PIPE`, this attribute is a file object
- that provides input to the child process. Otherwise, it is ``None``.
+ If the *stdin* argument was :data:`PIPE`, this attribute is a :term:`file
+ object` that provides input to the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stdout
- If the *stdout* argument was :data:`PIPE`, this attribute is a file object
- that provides output from the child process. Otherwise, it is ``None``.
+ If the *stdout* argument was :data:`PIPE`, this attribute is a :term:`file
+ object` that provides output from the child process. Otherwise, it is ``None``.
.. attribute:: Popen.stderr
- If the *stderr* argument was :data:`PIPE`, this attribute is a file object
- that provides error output from the child process. Otherwise, it is
+ If the *stderr* argument was :data:`PIPE`, this attribute is a :term:`file
+ object` that provides error output from the child process. Otherwise, it is
``None``.
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
index 4586793..619d4fb 100644
--- a/Doc/library/sys.rst
+++ b/Doc/library/sys.rst
@@ -792,10 +792,10 @@ always available.
stdout
stderr
- File objects corresponding to the interpreter's standard input, output and error
- streams. ``stdin`` is used for all interpreter input except for scripts but
- including calls to :func:`input`. ``stdout`` is used for
- the output of :func:`print` and :term:`expression` statements and for the
+ :term:`File objects <file object>` corresponding to the interpreter's standard
+ input, output and error streams. ``stdin`` is used for all interpreter input
+ except for scripts but including calls to :func:`input`. ``stdout`` is used
+ for the output of :func:`print` and :term:`expression` statements and for the
prompts of :func:`input`. The interpreter's own prompts
and (almost all of) its error messages go to ``stderr``. ``stdout`` and
``stderr`` needn't be built-in file objects: any object is acceptable as long
diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst
index b617796..d5a511e 100644
--- a/Doc/library/tarfile.rst
+++ b/Doc/library/tarfile.rst
@@ -66,8 +66,8 @@ Some facts and figures:
*mode* ``'r'`` to avoid this. If a compression method is not supported,
:exc:`CompressionError` is raised.
- If *fileobj* is specified, it is used as an alternative to a file object opened
- for *name*. It is supposed to be at position 0.
+ If *fileobj* is specified, it is used as an alternative to a :term:`file object`
+ opened in binary mode for *name*. It is supposed to be at position 0.
For special purposes, there is a second format for *mode*:
``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile`
@@ -75,7 +75,7 @@ Some facts and figures:
be done on the file. If given, *fileobj* may be any object that has a
:meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
- in combination with e.g. ``sys.stdin``, a socket file object or a tape
+ in combination with e.g. ``sys.stdin``, a socket :term:`file object` or a tape
device. However, such a :class:`TarFile` object is limited in that it does
not allow to be accessed randomly, see :ref:`tar-examples`. The currently
possible modes:
@@ -344,9 +344,9 @@ object, see :ref:`tarinfo-objects` for details.
.. method:: TarFile.extractfile(member)
Extract a member from the archive as a file object. *member* may be a filename
- or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
- is returned. If *member* is a link, a file-like object is constructed from the
- link's target. If *member* is none of the above, :const:`None` is returned.
+ or a :class:`TarInfo` object. If *member* is a regular file, a :term:`file-like
+ object` is returned. If *member* is a link, a file-like object is constructed from
+ the link's target. If *member* is none of the above, :const:`None` is returned.
.. note::
@@ -380,9 +380,9 @@ object, see :ref:`tarinfo-objects` for details.
.. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
- Create a :class:`TarInfo` object for either the file *name* or the file object
- *fileobj* (using :func:`os.fstat` on its file descriptor). You can modify some
- of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
+ Create a :class:`TarInfo` object for either the file *name* or the :term:`file
+ object` *fileobj* (using :func:`os.fstat` on its file descriptor). You can modify
+ some of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
If given, *arcname* specifies an alternative name for the file in the archive.
diff --git a/Doc/library/tempfile.rst b/Doc/library/tempfile.rst
index cde1b72..a13df0d 100644
--- a/Doc/library/tempfile.rst
+++ b/Doc/library/tempfile.rst
@@ -29,7 +29,7 @@ The module defines the following user-callable functions:
.. function:: TemporaryFile(mode='w+b', buffering=None, encoding=None, newline=None, suffix='', prefix='tmp', dir=None)
- Return a file-like object that can be used as a temporary storage area.
+ Return a :term:`file-like object` that can be used as a temporary storage area.
The file is created using :func:`mkstemp`. It will be destroyed as soon
as it is closed (including an implicit close when the object is garbage
collected). Under Unix, the directory entry for the file is removed
diff --git a/Doc/library/termios.rst b/Doc/library/termios.rst
index 591850e..a90a825 100644
--- a/Doc/library/termios.rst
+++ b/Doc/library/termios.rst
@@ -17,7 +17,7 @@ I/O control (and then only if configured at installation time).
All functions in this module take a file descriptor *fd* as their first
argument. This can be an integer file descriptor, such as returned by
-``sys.stdin.fileno()``, or a file object, such as ``sys.stdin`` itself.
+``sys.stdin.fileno()``, or a :term:`file object`, such as ``sys.stdin`` itself.
This module also defines all the constants needed to work with the functions
provided here; these have the same name as their counterparts in C. Please
diff --git a/Doc/library/weakref.rst b/Doc/library/weakref.rst
index 612e56f..10b69c9 100644
--- a/Doc/library/weakref.rst
+++ b/Doc/library/weakref.rst
@@ -58,8 +58,9 @@ is exposed by the :mod:`weakref` module for the benefit of advanced uses.
Not all objects can be weakly referenced; those objects which can include class
instances, functions written in Python (but not in C), instance methods, sets,
-frozensets, file objects, :term:`generator`\s, type objects, sockets, arrays,
-deques, and regular expression pattern objects.
+frozensets, some :term:`file objects <file object>`, :term:`generator`\s, type
+objects, sockets, arrays, deques and regular expression pattern objects.
+
Several built-in types such as :class:`list` and :class:`dict` do not directly
support weak references but can add support through subclassing::
diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index 0d3f61c..bc04a53 100644
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -89,9 +89,10 @@ Functions
.. function:: iterparse(source, events=None)
Parses an XML section into an element tree incrementally, and reports what's
- going on to the user. *source* is a filename or file object containing XML data.
- *events* is a list of events to report back. If omitted, only "end" events are
- reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs.
+ going on to the user. *source* is a filename or :term:`file object` containing
+ XML data. *events* is a list of events to report back. If omitted, only "end"
+ events are reported. Returns an :term:`iterator` providing ``(event, elem)``
+ pairs.
.. note::
@@ -359,16 +360,16 @@ ElementTree Objects
.. method:: parse(source, parser=None)
- Loads an external XML section into this element tree. *source* is a file
- name or file object. *parser* is an optional parser instance. If not
- given, the standard XMLTreeBuilder parser is used. Returns the section
+ Loads an external XML section into this element tree. *source* is a file
+ name or :term:`file object`. *parser* is an optional parser instance.
+ If not given, the standard XMLTreeBuilder parser is used. Returns the section
root element.
.. method:: write(file, encoding=None)
- Writes the element tree to a file, as XML. *file* is a file name, or a
- file object opened for writing. *encoding* [1]_ is the output encoding
+ Writes the element tree to a file, as XML. *file* is a file name, or a
+ :term:`file object` opened for writing. *encoding* [1]_ is the output encoding
(default is US-ASCII).
This is the XML file that is going to be manipulated::
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 25ab11e..3585ca7 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -781,9 +781,9 @@ I/O objects (also known as file objects)
single: stdout (in module sys)
single: stderr (in module sys)
- A file object represents an open file. Various shortcuts are available
- to create file objects: the :func:`open` built-in function, and also
- :func:`os.popen`, :func:`os.fdopen`, and the :meth:`makefile` method
+ A :term:`file object` represents an open file. Various shortcuts are
+ available to create file objects: the :func:`open` built-in function, and
+ also :func:`os.popen`, :func:`os.fdopen`, and the :meth:`makefile` method
of socket objects (and perhaps by other functions or methods provided
by extension modules).
diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst
index dbb56f6..84e83b5 100644
--- a/Doc/tutorial/inputoutput.rst
+++ b/Doc/tutorial/inputoutput.rst
@@ -232,8 +232,8 @@ Reading and Writing Files
builtin: open
object: file
-:func:`open` returns a file object, and is most commonly used with two
-arguments: ``open(filename, mode)``.
+:func:`open` returns a :term:`file object`, and is most commonly used with
+two arguments: ``open(filename, mode)``.
::