mirror of https://github.com/python/cpython
Add cross-references to the glossary entry for file objects.
This commit is contained in:
Antoine Pitrou
parent
6a11a98b7c
commit
11cb961b38
|
|
@ -210,8 +210,8 @@ have to remember to change two places in your program -- the second occurrence
|
|||
is hidden at the bottom of the loop.
|
||||
|
||||
The best approach is to use iterators, making it possible to loop through
|
||||
objects using the ``for`` statement. For example, in the current version of
|
||||
Python file objects support the iterator protocol, so you can now write simply::
|
||||
objects using the ``for`` statement. For example, :term:`file objects
|
||||
<file object>` support the iterator protocol, so you can write simply::
|
||||
|
||||
for line in f:
|
||||
... # do something with line...
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -147,11 +147,11 @@ The following data items and methods are also supported:
|
|||
|
||||
.. method:: array.fromfile(f, n)
|
||||
|
||||
Read *n* items (as machine values) from the file object *f* and append them to
|
||||
the end of the array. If less than *n* items are available, :exc:`EOFError` is
|
||||
raised, but the items that were available are still inserted into the array.
|
||||
*f* must be a real built-in file object; something else with a :meth:`read`
|
||||
method won't do.
|
||||
Read *n* items (as machine values) from the :term:`file object` *f* and append
|
||||
them to the end of the array. If less than *n* items are available,
|
||||
:exc:`EOFError` is raised, but the items that were available are still
|
||||
inserted into the array. *f* must be a real built-in file object; something
|
||||
else with a :meth:`read` method won't do.
|
||||
|
||||
|
||||
.. method:: array.fromlist(list)
|
||||
|
|
@ -214,7 +214,7 @@ The following data items and methods are also supported:
|
|||
|
||||
.. method:: array.tofile(f)
|
||||
|
||||
Write all items (as machine values) to the file object *f*.
|
||||
Write all items (as machine values) to the :term:`file object` *f*.
|
||||
|
||||
|
||||
.. method:: array.tolist()
|
||||
|
|
|
|||
|
|
@ -225,9 +225,9 @@ any that have been added to the map during asynchronous service) is closed.
|
|||
|
||||
.. class:: file_dispatcher()
|
||||
|
||||
A file_dispatcher takes a file descriptor or file object along with an
|
||||
optional map argument and wraps it for use with the :cfunc:`poll` or
|
||||
:cfunc:`loop` functions. If provided a file object or anything with a
|
||||
A file_dispatcher takes a file descriptor or :term:`file object` along
|
||||
with an optional map argument and wraps it for use with the :cfunc:`poll`
|
||||
or :cfunc:`loop` functions. If provided a file object or anything with a
|
||||
:cfunc:`fileno` method, that method will be called and passed to the
|
||||
:class:`file_wrapper` constructor. Availability: UNIX.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -422,7 +422,7 @@ RawConfigParser Objects
|
|||
|
||||
.. method:: RawConfigParser.write(fileobject, space_around_delimiters=True)
|
||||
|
||||
Write a representation of the configuration to the specified file object,
|
||||
Write a representation of the configuration to the specified :term:`file object`,
|
||||
which must be opened in text mode (accepting strings). This representation
|
||||
can be parsed by a future :meth:`read` call. If ``space_around_delimiters``
|
||||
is ``True`` (the default), delimiters between keys and values are surrounded
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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``
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
||||
|
|
|
|||
|
|
@ -134,8 +134,8 @@ The following exceptions are the exceptions that are usually raised.
|
|||
.. exception:: IOError
|
||||
|
||||
Raised when an I/O operation (such as the built-in :func:`print` or
|
||||
:func:`open` functions or a method of a file object) fails for an I/O-related
|
||||
reason, e.g., "file not found" or "disk full".
|
||||
:func:`open` functions or a method of a :term:`file object`) fails for an
|
||||
I/O-related reason, e.g., "file not found" or "disk full".
|
||||
|
||||
This class is derived from :exc:`EnvironmentError`. See the discussion above
|
||||
for more information on exception instance attributes.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -245,12 +245,12 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
.. method:: FTP.storbinary(cmd, file, blocksize=8192, callback=None, rest=None)
|
||||
|
||||
Store a file in binary transfer mode. *cmd* should be an appropriate
|
||||
``STOR`` command: ``"STOR filename"``. *file* is an open file object which is
|
||||
read until EOF using its :meth:`read` method in blocks of size *blocksize* to
|
||||
provide the data to be stored. The *blocksize* argument defaults to 8192.
|
||||
*callback* is an optional single parameter callable that is called
|
||||
on each block of data after it is sent. *rest* means the same thing as in
|
||||
the :meth:`transfercmd` method.
|
||||
``STOR`` command: ``"STOR filename"``. *file* is an open :term:`file object`
|
||||
which is read until EOF using its :meth:`read` method in blocks of size
|
||||
*blocksize* to provide the data to be stored. The *blocksize* argument
|
||||
defaults to 8192. *callback* is an optional single parameter callable that
|
||||
is called on each block of data after it is sent. *rest* means the same thing
|
||||
as in the :meth:`transfercmd` method.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
*rest* parameter added.
|
||||
|
|
@ -260,8 +260,8 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
|
|||
|
||||
Store a file in ASCII transfer mode. *cmd* should be an appropriate
|
||||
``STOR`` command (see :meth:`storbinary`). Lines are read until EOF from the
|
||||
open file object *file* using its :meth:`readline` method to provide the data to
|
||||
be stored. *callback* is an optional single parameter callable
|
||||
open :term:`file object` *file* using its :meth:`readline` method to provide
|
||||
the data to be stored. *callback* is an optional single parameter callable
|
||||
that is called on each line after it is sent.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -367,7 +367,7 @@ HTTPConnection Objects
|
|||
object. The Content-Length header is set to the length of the
|
||||
string.
|
||||
|
||||
The *body* may also be an open file object, in which case the
|
||||
The *body* may also be an open :term:`file object`, in which case the
|
||||
contents of the file is sent; this file object should support
|
||||
``fileno()`` and ``read()`` methods. The header Content-Length is
|
||||
automatically set to the length of the file as reported by
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -526,7 +526,7 @@ process and user.
|
|||
File Object Creation
|
||||
--------------------
|
||||
|
||||
These functions create new file objects. (See also :func:`open`.)
|
||||
These functions create new :term:`file objects <file object>`. (See also :func:`open`.)
|
||||
|
||||
|
||||
.. function:: fdopen(fd[, mode[, bufsize]])
|
||||
|
|
@ -562,7 +562,7 @@ is slightly deceptive; on Unix platforms, sockets and pipes are also referenced
|
|||
by file descriptors.
|
||||
|
||||
The :meth:`~file.fileno` method can be used to obtain the file descriptor
|
||||
associated with a file object when required. Note that using the file
|
||||
associated with a :term:`file object` when required. Note that using the file
|
||||
descriptor directly will bypass the file object methods, ignoring aspects such
|
||||
as internal buffering of data.
|
||||
|
||||
|
|
@ -679,9 +679,9 @@ as internal buffering of data.
|
|||
Force write of file with filedescriptor *fd* to disk. On Unix, this calls the
|
||||
native :cfunc:`fsync` function; on Windows, the MS :cfunc:`_commit` function.
|
||||
|
||||
If you're starting with a Python file object *f*, first do ``f.flush()``, and
|
||||
then do ``os.fsync(f.fileno())``, to ensure that all internal buffers associated
|
||||
with *f* are written to disk.
|
||||
If you're starting with a buffered Python :term:`file object` *f*, first do
|
||||
``f.flush()``, and then do ``os.fsync(f.fileno())``, to ensure that all internal
|
||||
buffers associated with *f* are written to disk.
|
||||
|
||||
Availability: Unix, and Windows.
|
||||
|
||||
|
|
@ -738,9 +738,9 @@ as internal buffering of data.
|
|||
.. note::
|
||||
|
||||
This function is intended for low-level I/O. For normal usage, use the
|
||||
built-in function :func:`open`, which returns a "file object" with
|
||||
built-in function :func:`open`, which returns a :term:`file object` with
|
||||
:meth:`~file.read` and :meth:`~file.write` methods (and many more). To
|
||||
wrap a file descriptor in a "file object", use :func:`fdopen`.
|
||||
wrap a file descriptor in a file object, use :func:`fdopen`.
|
||||
|
||||
|
||||
.. function:: openpty()
|
||||
|
|
|
|||
|
|
@ -143,8 +143,8 @@ process more convenient:
|
|||
|
||||
.. function:: dump(obj, file, protocol=None, \*, fix_imports=True)
|
||||
|
||||
Write a pickled representation of *obj* to the open file object *file*. This
|
||||
is equivalent to ``Pickler(file, protocol).dump(obj)``.
|
||||
Write a pickled representation of *obj* to the open :term:`file object` *file*.
|
||||
This is equivalent to ``Pickler(file, protocol).dump(obj)``.
|
||||
|
||||
The optional *protocol* argument tells the pickler to use the given protocol;
|
||||
supported protocols are 0, 1, 2, 3. The default protocol is 3; a
|
||||
|
|
@ -155,8 +155,9 @@ process more convenient:
|
|||
Python needed to read the pickle produced.
|
||||
|
||||
The *file* argument must have a write() method that accepts a single bytes
|
||||
argument. It can thus be a file object opened for binary writing, a
|
||||
io.BytesIO instance, or any other custom object that meets this interface.
|
||||
argument. It can thus be an on-disk file opened for binary writing, a
|
||||
:class:`io.BytesIO` instance, or any other custom object that meets this
|
||||
interface.
|
||||
|
||||
If *fix_imports* is True and *protocol* is less than 3, pickle will try to
|
||||
map the new Python 3.x names to the old module names used in Python 2.x,
|
||||
|
|
@ -181,8 +182,8 @@ process more convenient:
|
|||
|
||||
.. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict")
|
||||
|
||||
Read a pickled object representation from the open file object *file* and
|
||||
return the reconstituted object hierarchy specified therein. This is
|
||||
Read a pickled object representation from the open :term:`file object` *file*
|
||||
and return the reconstituted object hierarchy specified therein. This is
|
||||
equivalent to ``Unpickler(file).load()``.
|
||||
|
||||
The protocol version of the pickle is detected automatically, so no protocol
|
||||
|
|
@ -191,9 +192,9 @@ process more convenient:
|
|||
|
||||
The argument *file* must have two methods, a read() method that takes an
|
||||
integer argument, and a readline() method that requires no arguments. Both
|
||||
methods should return bytes. Thus *file* can be a binary file object opened
|
||||
for reading, a BytesIO object, or any other custom object that meets this
|
||||
interface.
|
||||
methods should return bytes. Thus *file* can be an on-disk file opened
|
||||
for binary reading, a :class:`io.BytesIO` object, or any other custom object
|
||||
that meets this interface.
|
||||
|
||||
Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
|
||||
which are used to control compatiblity support for pickle stream generated
|
||||
|
|
@ -260,8 +261,8 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and
|
|||
Python needed to read the pickle produced.
|
||||
|
||||
The *file* argument must have a write() method that accepts a single bytes
|
||||
argument. It can thus be a file object opened for binary writing, a
|
||||
io.BytesIO instance, or any other custom object that meets this interface.
|
||||
argument. It can thus be an on-disk file opened for binary writing, a
|
||||
:class:`io.BytesIO` instance, or any other custom object that meets this interface.
|
||||
|
||||
If *fix_imports* is True and *protocol* is less than 3, pickle will try to
|
||||
map the new Python 3.x names to the old module names used in Python 2.x,
|
||||
|
|
@ -304,9 +305,9 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and
|
|||
|
||||
The argument *file* must have two methods, a read() method that takes an
|
||||
integer argument, and a readline() method that requires no arguments. Both
|
||||
methods should return bytes. Thus *file* can be a binary file object opened
|
||||
for reading, a BytesIO object, or any other custom object that meets this
|
||||
interface.
|
||||
methods should return bytes. Thus *file* can be an on-disk file object opened
|
||||
for binary reading, a :class:`io.BytesIO` object, or any other custom object
|
||||
that meets this interface.
|
||||
|
||||
Optional keyword arguments are *fix_imports*, *encoding* and *errors*,
|
||||
which are used to control compatiblity support for pickle stream generated
|
||||
|
|
|
|||
|
|
@ -21,25 +21,24 @@ sending a graphics file.
|
|||
.. function:: decode(input, output, header=False)
|
||||
|
||||
Decode the contents of the *input* file and write the resulting decoded binary
|
||||
data to the *output* file. *input* and *output* must either be file objects or
|
||||
objects that mimic the file object interface. *input* will be read until
|
||||
``input.readline()`` returns an empty string. If the optional argument *header*
|
||||
is present and true, underscore will be decoded as space. This is used to decode
|
||||
"Q"-encoded headers as described in :rfc:`1522`: "MIME (Multipurpose Internet
|
||||
Mail Extensions) Part Two: Message Header Extensions for Non-ASCII Text".
|
||||
data to the *output* file. *input* and *output* must be :term:`file objects
|
||||
<file object>`. *input* will be read until ``input.readline()`` returns an
|
||||
empty string. If the optional argument *header* is present and true, underscore
|
||||
will be decoded as space. This is used to decode "Q"-encoded headers as
|
||||
described in :rfc:`1522`: "MIME (Multipurpose Internet Mail Extensions)
|
||||
Part Two: Message Header Extensions for Non-ASCII Text".
|
||||
|
||||
|
||||
.. function:: encode(input, output, quotetabs, header=False)
|
||||
|
||||
Encode the contents of the *input* file and write the resulting quoted-printable
|
||||
data to the *output* file. *input* and *output* must either be file objects or
|
||||
objects that mimic the file object interface. *input* will be read until
|
||||
``input.readline()`` returns an empty string. *quotetabs* is a flag which
|
||||
controls whether to encode embedded spaces and tabs; when true it encodes such
|
||||
embedded whitespace, and when false it leaves them unencoded. Note that spaces
|
||||
and tabs appearing at the end of lines are always encoded, as per
|
||||
:rfc:`1521`. *header* is a flag which controls if spaces are encoded as
|
||||
underscores as per :rfc:`1522`.
|
||||
data to the *output* file. *input* and *output* must be :term:`file objects
|
||||
<file object>`. *input* will be read until ``input.readline()`` returns an
|
||||
empty string. *quotetabs* is a flag which controls whether to encode embedded
|
||||
spaces and tabs; when true it encodes such embedded whitespace, and when
|
||||
false it leaves them unencoded. Note that spaces and tabs appearing at the
|
||||
end of lines are always encoded, as per :rfc:`1521`. *header* is a flag
|
||||
which controls if spaces are encoded as underscores as per :rfc:`1522`.
|
||||
|
||||
|
||||
.. function:: decodestring(s, header=False)
|
||||
|
|
|
|||
|
|
@ -78,11 +78,12 @@ The module defines the following:
|
|||
single: socket() (in module socket)
|
||||
single: popen() (in module os)
|
||||
|
||||
Among the acceptable object types in the sequences are Python file objects (e.g.
|
||||
``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket
|
||||
objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper`
|
||||
class yourself, as long as it has an appropriate :meth:`fileno` method (that
|
||||
really returns a file descriptor, not just a random integer).
|
||||
Among the acceptable object types in the sequences are Python :term:`file
|
||||
objects <file object>` (e.g. ``sys.stdin``, or objects returned by
|
||||
:func:`open` or :func:`os.popen`), socket objects returned by
|
||||
:func:`socket.socket`. You may also define a :dfn:`wrapper` class yourself,
|
||||
as long as it has an appropriate :meth:`fileno` method (that really returns
|
||||
a file descriptor, not just a random integer).
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
|
|||
|
|
@ -2441,9 +2441,9 @@ to be provided for a context manager object to define a runtime context:
|
|||
the identifier in the :keyword:`as` clause of :keyword:`with` statements using
|
||||
this context manager.
|
||||
|
||||
An example of a context manager that returns itself is a file object. File
|
||||
objects return themselves from __enter__() to allow :func:`open` to be used as
|
||||
the context expression in a :keyword:`with` statement.
|
||||
An example of a context manager that returns itself is a :term:`file object`.
|
||||
File objects return themselves from __enter__() to allow :func:`open` to be
|
||||
used as the context expression in a :keyword:`with` statement.
|
||||
|
||||
An example of a context manager that returns a related object is the one
|
||||
returned by :func:`decimal.localcontext`. These managers set the active
|
||||
|
|
|
|||
|
|
@ -108,9 +108,9 @@ This module defines one class called :class:`Popen`:
|
|||
*stdin*, *stdout* and *stderr* specify the executed programs' standard input,
|
||||
standard output and standard error file handles, respectively. Valid values
|
||||
are :data:`PIPE`, an existing file descriptor (a positive integer), an
|
||||
existing file object, and ``None``. :data:`PIPE` indicates that a new pipe
|
||||
to the child should be created. With ``None``, no redirection will occur;
|
||||
the child's file handles will be inherited from the parent. Additionally,
|
||||
existing :term:`file object`, and ``None``. :data:`PIPE` indicates that a
|
||||
new pipe to the child should be created. With ``None``, no redirection will
|
||||
occur; the child's file handles will be inherited from the parent. Additionally,
|
||||
*stderr* can be :data:`STDOUT`, which indicates that the stderr data from the
|
||||
applications should be captured into the same file handle as for stdout.
|
||||
|
||||
|
|
@ -409,20 +409,20 @@ The following attributes are also available:
|
|||
|
||||
.. attribute:: Popen.stdin
|
||||
|
||||
If the *stdin* argument was :data:`PIPE`, this attribute is a file object
|
||||
that provides input to the child process. Otherwise, it is ``None``.
|
||||
If the *stdin* argument was :data:`PIPE`, this attribute is a :term:`file
|
||||
object` that provides input to the child process. Otherwise, it is ``None``.
|
||||
|
||||
|
||||
.. attribute:: Popen.stdout
|
||||
|
||||
If the *stdout* argument was :data:`PIPE`, this attribute is a file object
|
||||
that provides output from the child process. Otherwise, it is ``None``.
|
||||
If the *stdout* argument was :data:`PIPE`, this attribute is a :term:`file
|
||||
object` that provides output from the child process. Otherwise, it is ``None``.
|
||||
|
||||
|
||||
.. attribute:: Popen.stderr
|
||||
|
||||
If the *stderr* argument was :data:`PIPE`, this attribute is a file object
|
||||
that provides error output from the child process. Otherwise, it is
|
||||
If the *stderr* argument was :data:`PIPE`, this attribute is a :term:`file
|
||||
object` that provides error output from the child process. Otherwise, it is
|
||||
``None``.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -853,10 +853,10 @@ always available.
|
|||
stdout
|
||||
stderr
|
||||
|
||||
File objects corresponding to the interpreter's standard input, output and error
|
||||
streams. ``stdin`` is used for all interpreter input except for scripts but
|
||||
including calls to :func:`input`. ``stdout`` is used for
|
||||
the output of :func:`print` and :term:`expression` statements and for the
|
||||
:term:`File objects <file object>` corresponding to the interpreter's standard
|
||||
input, output and error streams. ``stdin`` is used for all interpreter input
|
||||
except for scripts but including calls to :func:`input`. ``stdout`` is used
|
||||
for the output of :func:`print` and :term:`expression` statements and for the
|
||||
prompts of :func:`input`. The interpreter's own prompts
|
||||
and (almost all of) its error messages go to ``stderr``. ``stdout`` and
|
||||
``stderr`` needn't be built-in file objects: any object is acceptable as long
|
||||
|
|
|
|||
|
|
@ -66,8 +66,8 @@ Some facts and figures:
|
|||
*mode* ``'r'`` to avoid this. If a compression method is not supported,
|
||||
:exc:`CompressionError` is raised.
|
||||
|
||||
If *fileobj* is specified, it is used as an alternative to a file object opened
|
||||
for *name*. It is supposed to be at position 0.
|
||||
If *fileobj* is specified, it is used as an alternative to a :term:`file object`
|
||||
opened in binary mode for *name*. It is supposed to be at position 0.
|
||||
|
||||
For special purposes, there is a second format for *mode*:
|
||||
``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile`
|
||||
|
|
@ -75,7 +75,7 @@ Some facts and figures:
|
|||
be done on the file. If given, *fileobj* may be any object that has a
|
||||
:meth:`read` or :meth:`write` method (depending on the *mode*). *bufsize*
|
||||
specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
|
||||
in combination with e.g. ``sys.stdin``, a socket file object or a tape
|
||||
in combination with e.g. ``sys.stdin``, a socket :term:`file object` or a tape
|
||||
device. However, such a :class:`TarFile` object is limited in that it does
|
||||
not allow to be accessed randomly, see :ref:`tar-examples`. The currently
|
||||
possible modes:
|
||||
|
|
@ -355,9 +355,9 @@ be finalized; only the internally used file object will be closed. See the
|
|||
.. method:: TarFile.extractfile(member)
|
||||
|
||||
Extract a member from the archive as a file object. *member* may be a filename
|
||||
or a :class:`TarInfo` object. If *member* is a regular file, a file-like object
|
||||
is returned. If *member* is a link, a file-like object is constructed from the
|
||||
link's target. If *member* is none of the above, :const:`None` is returned.
|
||||
or a :class:`TarInfo` object. If *member* is a regular file, a :term:`file-like
|
||||
object` is returned. If *member* is a link, a file-like object is constructed from
|
||||
the link's target. If *member* is none of the above, :const:`None` is returned.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -402,9 +402,9 @@ be finalized; only the internally used file object will be closed. See the
|
|||
|
||||
.. method:: TarFile.gettarinfo(name=None, arcname=None, fileobj=None)
|
||||
|
||||
Create a :class:`TarInfo` object for either the file *name* or the file object
|
||||
*fileobj* (using :func:`os.fstat` on its file descriptor). You can modify some
|
||||
of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
|
||||
Create a :class:`TarInfo` object for either the file *name* or the :term:`file
|
||||
object` *fileobj* (using :func:`os.fstat` on its file descriptor). You can modify
|
||||
some of the :class:`TarInfo`'s attributes before you add it using :meth:`addfile`.
|
||||
If given, *arcname* specifies an alternative name for the file in the archive.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -58,8 +58,9 @@ is exposed by the :mod:`weakref` module for the benefit of advanced uses.
|
|||
|
||||
Not all objects can be weakly referenced; those objects which can include class
|
||||
instances, functions written in Python (but not in C), instance methods, sets,
|
||||
frozensets, file objects, :term:`generator`\s, type objects, sockets, arrays,
|
||||
deques, regular expression pattern objects, and code objects.
|
||||
frozensets, some :term:`file objects <file object>`, :term:`generator`\s, type
|
||||
objects, sockets, arrays, deques, regular expression pattern objects, and code
|
||||
objects.
|
||||
|
||||
.. versionchanged:: 3.2
|
||||
Added support for thread.lock, threading.Lock, and code objects.
|
||||
|
|
|
|||
|
|
@ -92,8 +92,8 @@ Functions
|
|||
.. function:: iterparse(source, events=None, parser=None)
|
||||
|
||||
Parses an XML section into an element tree incrementally, and reports what's
|
||||
going on to the user. *source* is a filename or file object containing XML
|
||||
data. *events* is a list of events to report back. If omitted, only "end"
|
||||
going on to the user. *source* is a filename or :term:`file object` containing
|
||||
XML data. *events* is a list of events to report back. If omitted, only "end"
|
||||
events are reported. *parser* is an optional parser instance. If not
|
||||
given, the standard :class:`XMLParser` parser is used. Returns an
|
||||
:term:`iterator` providing ``(event, elem)`` pairs.
|
||||
|
|
@ -455,15 +455,15 @@ ElementTree Objects
|
|||
.. method:: parse(source, parser=None)
|
||||
|
||||
Loads an external XML section into this element tree. *source* is a file
|
||||
name or file object. *parser* is an optional parser instance. If not
|
||||
given, the standard XMLParser parser is used. Returns the section
|
||||
name or :term:`file object`. *parser* is an optional parser instance.
|
||||
If not given, the standard XMLParser parser is used. Returns the section
|
||||
root element.
|
||||
|
||||
|
||||
.. method:: write(file, encoding="us-ascii", xml_declaration=None, method="xml")
|
||||
|
||||
Writes the element tree to a file, as XML. *file* is a file name, or a
|
||||
file object opened for writing. *encoding* [1]_ is the output encoding
|
||||
:term:`file object` opened for writing. *encoding* [1]_ is the output encoding
|
||||
(default is US-ASCII). Use ``encoding="unicode"`` to write a Unicode string.
|
||||
*xml_declaration* controls if an XML declaration
|
||||
should be added to the file. Use False for never, True for always, None
|
||||
|
|
|
|||
|
|
@ -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)``.
|
||||
|
||||
::
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue