diff options
Diffstat (limited to 'Doc')
33 files changed, 165 insertions, 166 deletions
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 627ee4ec46..68e5b8ad4b 100644 --- a/Doc/faq/design.rst +++ b/Doc/faq/design.rst @@ -210,8 +210,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/library/aifc.rst b/Doc/library/aifc.rst index bdd3517bed..304437d9a2 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 e24a98b3c1..e4975c8320 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -147,11 +147,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) @@ -214,7 +214,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 e64d51d588..1ba8e958b0 100644 --- a/Doc/library/asyncore.rst +++ b/Doc/library/asyncore.rst @@ -225,9 +225,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 39a466e5d3..e282ea0ef5 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 6f01dd3b89..d9a2bad756 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 6a75b26321..a10a89bbd4 100644 --- a/Doc/library/configparser.rst +++ b/Doc/library/configparser.rst @@ -422,7 +422,7 @@ RawConfigParser Objects .. method:: RawConfigParser.write(fileobject, space_around_delimiters=True) - 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. If ``space_around_delimiters`` is ``True`` (the default), delimiters between keys and values are surrounded diff --git a/Doc/library/csv.rst b/Doc/library/csv.rst index 71523b5c52..8ca17415e6 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 ba38f68514..930905aee0 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 3de5c317e0..32f4ff164b 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 777cf1987c..a4e2e0e57e 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -134,8 +134,8 @@ The following exceptions are the exceptions that are usually 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 31eaf0d870..58998a8abf 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 0a459a60cb..88be11c3c5 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 f9b648164b..4111de4390 100644 --- a/Doc/library/ftplib.rst +++ b/Doc/library/ftplib.rst @@ -245,12 +245,12 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. .. method:: FTP.storbinary(cmd, file, blocksize=8192, callback=None, rest=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. *rest* means the same thing as in - the :meth:`transfercmd` method. + ``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. *rest* means the same thing + as in the :meth:`transfercmd` method. .. versionchanged:: 3.2 *rest* parameter added. @@ -260,8 +260,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version. 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 eba59c86d6..9e1528ba62 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 2cece84f35..edd5587b4a 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 584925480a..f0f7803202 100644 --- a/Doc/library/http.client.rst +++ b/Doc/library/http.client.rst @@ -367,7 +367,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 9c7e358519..53a1550654 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 779a5e872d..128bc90259 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 700d6e0b1a..c3cbd2bc95 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 9373bda655..57a916c99c 100644 --- a/Doc/library/os.rst +++ b/Doc/library/os.rst @@ -526,7 +526,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]]) @@ -562,7 +562,7 @@ 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 file object when required. Note that using the file +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. @@ -679,9 +679,9 @@ as internal buffering of data. 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. @@ -738,9 +738,9 @@ as internal buffering of data. .. 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.write` 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 99e30c62e9..5e5d0a3df2 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -143,8 +143,8 @@ process more convenient: .. function:: dump(obj, file, protocol=None, \*, 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 7ceb66147b..d7c7204074 100644 --- a/Doc/library/quopri.rst +++ b/Doc/library/quopri.rst @@ -21,25 +21,24 @@ sending a graphics file. .. function:: decode(input, output, header=False) 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, header=False) 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`. *header* is a flag which controls if spaces are encoded as - underscores as per :rfc:`1522`. + 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`. *header* is a flag + which controls if spaces are encoded as underscores as per :rfc:`1522`. .. function:: decodestring(s, header=False) diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 5418093ac4..5e848b0339 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -78,11 +78,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/stdtypes.rst b/Doc/library/stdtypes.rst index 3a798627c1..bd8b421210 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2441,9 +2441,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 1904f57e4a..1c8a79c291 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -108,9 +108,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. @@ -409,20 +409,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 ad61377476..0bb6f3aac4 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -853,10 +853,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 b1d736130e..853406c219 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: @@ -355,9 +355,9 @@ be finalized; only the internally used file object will be closed. See the .. 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:: @@ -402,9 +402,9 @@ be finalized; only the internally used file object will be closed. See the .. 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 cde1b72ec2..a13df0dd22 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 591850e2ce..a90a825be4 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 c8eb8998b8..dec415c9aa 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, regular expression pattern objects, and code objects. +frozensets, some :term:`file objects <file object>`, :term:`generator`\s, type +objects, sockets, arrays, deques, regular expression pattern objects, and code +objects. .. versionchanged:: 3.2 Added support for thread.lock, threading.Lock, and code objects. diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst index 231992789c..71614c0be9 100644 --- a/Doc/library/xml.etree.elementtree.rst +++ b/Doc/library/xml.etree.elementtree.rst @@ -92,8 +92,8 @@ Functions .. function:: iterparse(source, events=None, parser=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" + 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. *parser* is an optional parser instance. If not given, the standard :class:`XMLParser` parser is used. Returns an :term:`iterator` providing ``(event, elem)`` pairs. @@ -455,15 +455,15 @@ 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 XMLParser parser is used. Returns the section + name or :term:`file object`. *parser* is an optional parser instance. + If not given, the standard XMLParser parser is used. Returns the section root element. .. method:: write(file, encoding="us-ascii", xml_declaration=None, method="xml") 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 + :term:`file object` opened for writing. *encoding* [1]_ is the output encoding (default is US-ASCII). Use ``encoding="unicode"`` to write a Unicode string. *xml_declaration* controls if an XML declaration should be added to the file. Use False for never, True for always, None diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst index dbb56f6162..84e83b5d7d 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)``. :: |