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...
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).
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
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?
---------------------------------------------------------------------
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
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
.. 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`.
.. 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)
.. 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()
.. 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.
.. 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)
.. 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)
* :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;
.. 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.
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
.. 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``
.. 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::
.. 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.
.. 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
.. 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.
.. 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.
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.
.. 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
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
.. 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.
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
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.
: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
*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])
``(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])
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.
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.
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.
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.
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.
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.
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]])
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)
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.
.. 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()
.. 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
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,
.. 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
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
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,
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
.. 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])
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::
.. 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.
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
*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.
.. 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``.
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
*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`
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:
.. 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::
.. 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.
.. 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
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
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::
.. 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::
.. 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::
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).
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)``.
::
projects / python / commitdiff