diff options
37 files changed, 218 insertions, 187 deletions
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst index 87f87422fe..c20de00b98 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 b409bb67fc..c59b38f528 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 40f0869e03..5ecf848b5f 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 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 2235f0894b..3f5f9e6c0a 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 60d4d0336c..8cdfe200bf 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 9ff065ab1b..651f889f5b 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 5ddfcd7502..1afdf502af 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 510d35a400..e75f00ac8d 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 fb3ae94d41..ceebf5e2bb 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 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 c85e0b3e72..75a8fb17db 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 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 894a423a1d..fdd859049c 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 fe6581285a..7cdbbcf970 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 b6123ae628..5c21ee79f2 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 403e2f524e..bb4a515c4a 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 80955afd4a..2fb8cd64a2 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 21e4001139..8157a525fe 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 8f525efdf8..a64337ef7c 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 f19cbdc856..70f73700b4 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 5314039e10..511d37beb6 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 694ff56bfe..0a5b88280e 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 edba7a7f65..72ea8c6104 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 45867937d4..619d4fbf2b 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 b617796021..d5a511eaaf 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 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 612e56f9ba..10b69c98c0 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 0d3f61cb34..bc04a5355e 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 25ab11ee8f..3585ca7a7f 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 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)``. :: |