Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 25d535e

Browse files
pitroupitrou
committed
Merged revisions 84827-84829 via svnmerge from
svn+ssh://[email protected]/python/branches/py3k ........ r84827 | antoine.pitrou | 2010-09-15 11:58:26 +0200 (mer., 15 sept. 2010) | 3 lines Add a glossary entry for file objects. ........ r84828 | antoine.pitrou | 2010-09-15 12:08:31 +0200 (mer., 15 sept. 2010) | 3 lines Update file-related information in the FAQ. ........ r84829 | antoine.pitrou | 2010-09-15 13:11:28 +0200 (mer., 15 sept. 2010) | 3 lines Add cross-references to the glossary entry for file objects. ........
1 parent ecbf2de commit 25d535e

37 files changed

Lines changed: 218 additions & 187 deletions

‎Doc/faq/design.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,8 @@ have to remember to change two places in your program -- the second occurrence
209209
is hidden at the bottom of the loop.
210210

211211
The best approach is to use iterators, making it possible to loop through
212-
objects using the ``for`` statement. For example, in the current version of
213-
Python file objects support the iterator protocol, so you can now write simply::
212+
objects using the ``for`` statement. For example, :term:`file objects
213+
<file object>` support the iterator protocol, so you can write simply::
214214

215215
for line in f:
216216
... # do something with line...

‎Doc/faq/library.rst‎

Lines changed: 27 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -454,7 +454,7 @@ contents, use :func:`shutil.rmtree`.
454454

455455
To rename a file, use ``os.rename(old_path, new_path)``.
456456

457-
To truncate a file, open it using ``f = open(filename, "r+")``, and use
457+
To truncate a file, open it using ``f = open(filename, "rb+")``, and use
458458
``f.truncate(offset)``; offset defaults to the current seek position. There's
459459
also ```os.ftruncate(fd, offset)`` for files opened with :func:`os.open`, where
460460
``fd`` is the file descriptor (a small integer).
@@ -483,9 +483,9 @@ in big-endian format from a file::
483483

484484
import struct
485485

486-
f = open(filename, "rb") # Open in binary mode for portability
487-
s = f.read(8)
488-
x, y, z = struct.unpack(">hhl", s)
486+
with open(filename, "rb") as f:
487+
s = f.read(8)
488+
x, y, z = struct.unpack(">hhl", s)
489489

490490
The '>' in the format string forces big-endian data; the letter 'h' reads one
491491
"short integer" (2 bytes), and 'l' reads one "long integer" (4 bytes) from the
@@ -494,6 +494,13 @@ string.
494494
For data that is more regular (e.g. a homogeneous list of ints or thefloats),
495495
you can also use the :mod:`array` module.
496496

497+
.. note::
498+
To read and write binary data, it is mandatory to open the file in
499+
binary mode (here, passing ``"rb"`` to :func:`open`). If you use
500+
``"r"`` instead (the default), the file will be open in text mode
501+
and ``f.read()`` will return :class:`str` objects rather than
502+
:class:`bytes` objects.
503+
497504

498505
I can't seem to use os.read() on a pipe created with os.popen(); why?
499506
---------------------------------------------------------------------
@@ -597,27 +604,29 @@ For Unix, see a Usenet post by Mitch Chapman:
597604
Why doesn't closing sys.stdout (stdin, stderr) really close it?
598605
---------------------------------------------------------------
599606

600-
Python file objects are a high-level layer of abstraction on top of C streams,
601-
which in turn are a medium-level layer of abstraction on top of (among other
602-
things) low-level C file descriptors.
607+
Python :term:`file objects <file object>` are a high-level layer of
608+
abstraction on low-level C file descriptors.
603609

604-
For most file objects you create in Python via the builtin ``file`` constructor,
605-
``f.close()`` marks the Python file object as being closed from Python's point
606-
of view, and also arranges to close the underlying C stream. This also happens
607-
automatically in f's destructor, when f becomes garbage.
610+
For most file objects you create in Python via the built-in :func:`open`
611+
function, ``f.close()`` marks the Python file object as being closed from
612+
Python's point of view, and also arranges to close the underlying C file
613+
descriptor. This also happens automatically in ``f``'s destructor, when
614+
``f`` becomes garbage.
608615

609616
But stdin, stdout and stderr are treated specially by Python, because of the
610617
special status also given to them by C. Running ``sys.stdout.close()`` marks
611618
the Python-level file object as being closed, but does *not* close the
612-
associated C stream.
619+
associated C file descriptor.
620+
621+
To close the underlying C file descriptor for one of these three, you should
622+
first be sure that's what you really want to do (e.g., you may confuse
623+
extension modules trying to do I/O). If it is, use :func:`os.close`::
613624

614-
To close the underlying C stream for one of these three, you should first be
615-
sure that's what you really want to do (e.g., you may confuse extension modules
616-
trying to do I/O). If it is, use os.close::
625+
os.close(stdin.fileno())
626+
os.close(stdout.fileno())
627+
os.close(stderr.fileno())
617628

618-
os.close(0) # close C's stdin stream
619-
os.close(1) # close C's stdout stream
620-
os.close(2) # close C's stderr stream
629+
Or you can use the numeric constants 0, 1 and 2, respectively.
621630

622631

623632
Network/Internet Programming

‎Doc/glossary.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,23 @@ Glossary
178178
A module written in C or C++, using Python's C API to interact with the core and
179179
with user code.
180180

181+
file object
182+
An object exposing a file-oriented API (with methods such as
183+
:meth:`read()` or :meth:`write()`) to an underlying resource.
184+
Depending on the way it was created, a file object can mediate access
185+
to a real on-disk file or to another other type of storage or
186+
communication device (for example standard input/output, in-memory
187+
buffers, sockets, pipes, etc.). File objects are also called
188+
:dfn:`file-like objects` or :dfn:`streams`.
189+
190+
There are actually three categories of file objects: raw binary
191+
files, buffered binary files and text files. Their interfaces are
192+
defined in the :mod:`io` module. The canonical way to create a
193+
file object is by using the :func:`open` function.
194+
195+
file-like object
196+
A synonym for :term:`file object`.
197+
181198
finder
182199
An object that tries to find the :term:`loader` for a module. It must
183200
implement a method named :meth:`find_module`. See :pep:`302` for

‎Doc/library/aifc.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,10 @@ Module :mod:`aifc` defines the following function:
4040
.. function:: open(file, mode=None)
4141

4242
Open an AIFF or AIFF-C file and return an object instance with methods that are
43-
described below. The argument *file* is either a string naming a file or a file
44-
object. *mode* must be ``'r'`` or ``'rb'`` when the file must be opened for
45-
reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing. If
46-
omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
43+
described below. The argument *file* is either a string naming a file or a
44+
:term:`file object`. *mode* must be ``'r'`` or ``'rb'`` when the file must be
45+
opened for reading, or ``'w'`` or ``'wb'`` when the file must be opened for writing.
46+
If omitted, ``file.mode`` is used if it exists, otherwise ``'rb'`` is used. When
4747
used for writing, the file object should be seekable, unless you know ahead of
4848
time how many samples you are going to write in total and use
4949
:meth:`writeframesraw` and :meth:`setnframes`.

‎Doc/library/array.rst‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -138,11 +138,11 @@ The following data items and methods are also supported:
138138

139139
.. method:: array.fromfile(f, n)
140140

141-
Read *n* items (as machine values) from the file object *f* and append them to
142-
the end of the array. If less than *n* items are available, :exc:`EOFError` is
143-
raised, but the items that were available are still inserted into the array.
144-
*f* must be a real built-in file object; something else with a :meth:`read`
145-
method won't do.
141+
Read *n* items (as machine values) from the :term:`file object` *f* and append
142+
them to the end of the array. If less than *n* items are available,
143+
:exc:`EOFError` is raised, but the items that were available are still
144+
inserted into the array. *f* must be a real built-in file object; something
145+
else with a :meth:`read` method won't do.
146146

147147

148148
.. method:: array.fromlist(list)
@@ -196,7 +196,7 @@ The following data items and methods are also supported:
196196

197197
.. method:: array.tofile(f)
198198

199-
Write all items (as machine values) to the file object *f*.
199+
Write all items (as machine values) to the :term:`file object` *f*.
200200

201201

202202
.. method:: array.tolist()

‎Doc/library/asyncore.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -224,9 +224,9 @@ any that have been added to the map during asynchronous service) is closed.
224224

225225
.. class:: file_dispatcher()
226226

227-
A file_dispatcher takes a file descriptor or file object along with an
228-
optional map argument and wraps it for use with the :cfunc:`poll` or
229-
:cfunc:`loop` functions. If provided a file object or anything with a
227+
A file_dispatcher takes a file descriptor or :term:`file object` along
228+
with an optional map argument and wraps it for use with the :cfunc:`poll`
229+
or :cfunc:`loop` functions. If provided a file object or anything with a
230230
:cfunc:`fileno` method, that method will be called and passed to the
231231
:class:`file_wrapper` constructor. Availability: UNIX.
232232

‎Doc/library/base64.rst‎

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -122,9 +122,9 @@ The legacy interface:
122122
.. function:: decode(input, output)
123123

124124
Decode the contents of the binary *input* file and write the resulting binary
125-
data to the *output* file. *input* and *output* must either be file objects
126-
or objects that mimic the file object interface working with bytes
127-
objects. *input* will be read until ``input.read()`` returns an empty string.
125+
data to the *output* file. *input* and *output* must be :term:`file objects
126+
<file object>`. *input* will be read until ``input.read()`` returns an empty
127+
bytes object.
128128

129129

130130
.. function:: decodebytes(s)
@@ -138,11 +138,10 @@ The legacy interface:
138138
.. function:: encode(input, output)
139139

140140
Encode the contents of the binary *input* file and write the resulting base64
141-
encoded data to the *output* file. *input* and *output* must either be file
142-
objects or objects that mimic the file object interface working with bytes
143-
objects. *input* will be read until ``input.read()`` returns an empty string.
144-
:func:`encode` returns the encoded data plus a trailing newline character
145-
(``b'\n'``).
141+
encoded data to the *output* file. *input* and *output* must be :term:`file
142+
objects <file object>`. *input* will be read until ``input.read()`` returns
143+
an empty bytes object. :func:`encode` returns the encoded data plus a trailing
144+
newline character (``b'\n'``).
146145

147146

148147
.. function:: encodebytes(s)

‎Doc/library/bz2.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,8 @@ Here is a summary of the features offered by the bz2 module:
2525

2626
* :class:`BZ2File` class implements universal newline support;
2727

28-
* :class:`BZ2File` class offers an optimized line iteration using the readahead
29-
algorithm borrowed from file objects;
28+
* :class:`BZ2File` class offers an optimized line iteration using a readahead
29+
algorithm;
3030

3131
* Sequential (de)compression supported by :class:`BZ2Compressor` and
3232
:class:`BZ2Decompressor` classes;

‎Doc/library/configparser.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -298,7 +298,7 @@ RawConfigParser Objects
298298

299299
.. method:: RawConfigParser.write(fileobject)
300300

301-
Write a representation of the configuration to the specified file object,
301+
Write a representation of the configuration to the specified :term:`file object`,
302302
which must be opened in text mode (accepting strings). This representation
303303
can be parsed by a future :meth:`read` call.
304304

‎Doc/library/csv.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,9 @@ The :mod:`csv` module defines the following functions:
5050

5151
Return a reader object which will iterate over lines in the given *csvfile*.
5252
*csvfile* can be any object which supports the :term:`iterator` protocol and returns a
53-
string each time its :meth:`!next` method is called --- file objects and list
54-
objects are both suitable. If *csvfile* is a file object, it should be opened
55-
with ``newline=''``. [#]_ An optional
53+
string each time its :meth:`!next` method is called --- :term:`file objects
54+
<file object>` and list objects are both suitable. If *csvfile* is a file object,
55+
it should be opened with ``newline=''``. [#]_ An optional
5656
*dialect* parameter can be given which is used to define a set of parameters
5757
specific to a particular CSV dialect. It may be an instance of a subclass of
5858
the :class:`Dialect` class or one of the strings returned by the

0 commit comments

Comments
 (0)