[Python-checkins] cpython (2.7): Multiple clean-ups to the docs for builtin functions.
raymond.hettinger
python-checkins at python.org
Thu Jun 2 00:50:42 CEST 2011
http://hg.python.org/cpython/rev/cc678de70d17
changeset: 70597:cc678de70d17
branch: 2.7
user: Raymond Hettinger <python at rcn.com>
date: Wed Jun 01 15:50:34 2011 -0700
summary:
Multiple clean-ups to the docs for builtin functions.
* Use concrete example for dir() and eliminate the distracting doctest directives.
* Add a pure python equivalent for enumerate()
* Modify the enumerate() example to demonstrate the start argument
* Remove incorrect reference the *iterable* in the enumerate() docs.
* Downgrade the comments on input() from a warning to a note.
* Fix the iter() example to use the empty string as the terminating
condition for file.readline(). Also, the old example was broken
because readline() results include a newline, so 'STOP\n' would have
been the correct terminating condition. Even with that fix, the
STOP example was fragile and would have lead to infinite loops with
malformed inputs.
* Do not refer to classmethod as being "more advanced" than staticmethod.
files:
Doc/library/functions.rst | 62 ++++++++++++++------------
1 files changed, 34 insertions(+), 28 deletions(-)
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -298,19 +298,19 @@
The resulting list is sorted alphabetically. For example:
>>> import struct
- >>> dir() # doctest: +SKIP
+ >>> dir() # show the names in the module namespace
['__builtins__', '__doc__', '__name__', 'struct']
- >>> dir(struct) # doctest: +NORMALIZE_WHITESPACE
+ >>> dir(struct) # show the names in the struct module
['Struct', '__builtins__', '__doc__', '__file__', '__name__',
'__package__', '_clearcache', 'calcsize', 'error', 'pack', 'pack_into',
'unpack', 'unpack_from']
- >>> class Foo(object):
- ... def __dir__(self):
- ... return ["kan", "ga", "roo"]
- ...
- >>> f = Foo()
+ >>> class Shape(object):
+ def __dir__(self):
+ return ['area', 'perimter', 'location']
+
+ >>> f = Shape()
>>> dir(f)
- ['ga', 'kan', 'roo']
+ ['area', 'perimter', 'location']
.. note::
@@ -342,16 +342,22 @@
:term:`iterator`, or some other object which supports iteration. The
:meth:`!next` method of the iterator returned by :func:`enumerate` returns a
tuple containing a count (from *start* which defaults to 0) and the
- corresponding value obtained from iterating over *iterable*.
- :func:`enumerate` is useful for obtaining an indexed series: ``(0, seq[0])``,
- ``(1, seq[1])``, ``(2, seq[2])``, .... For example:
+ corresponding value obtained from iterating over *sequence*::
- >>> for i, season in enumerate(['Spring', 'Summer', 'Fall', 'Winter']):
- ... print i, season
- 0 Spring
- 1 Summer
- 2 Fall
- 3 Winter
+ >>> for i, season in enumerate('Spring Summer Fall Winter'.split(), start=1):
+ print i, season
+ 1 Spring
+ 2 Summer
+ 3 Fall
+ 4 Winter
+
+ Equivalent to::
+
+ def enumerate(sequence, start=0):
+ n = start
+ for elem in sequence:
+ yield n, elem
+ n += 1
.. versionadded:: 2.3
.. versionadded:: 2.6
@@ -586,13 +592,12 @@
Equivalent to ``eval(raw_input(prompt))``.
- .. warning::
+ .. note::
- This function is not safe from user errors! It expects a valid Python
- expression as input; if the input is not syntactically valid, a
- :exc:`SyntaxError` will be raised. Other exceptions may be raised if there is an
- error during evaluation. (On the other hand, sometimes this is exactly what you
- need when writing a quick script for expert use.)
+ This function does not catch user errors. It expects a valid Python
+ expression as input. If the input is not syntactically valid, a
+ :exc:`SyntaxError` will be raised. Other exceptions may be raised if there
+ is an error during evaluation.
If the :mod:`readline` module was loaded, then :func:`input` will use it to
provide elaborate line editing and history features.
@@ -660,10 +665,10 @@
One useful application of the second form of :func:`iter` is to read lines of
a file until a certain line is reached. The following example reads a file
- until ``"STOP"`` is reached: ::
+ until the :meth:`readline` method returns an empty string::
- with open("mydata.txt") as fp:
- for line in iter(fp.readline, "STOP"):
+ with open('mydata.txt') as fp:
+ for line in iter(fp.readline, ''):
process_line(line)
.. versionadded:: 2.2
@@ -1241,8 +1246,9 @@
It can be called either on the class (such as ``C.f()``) or on an instance (such
as ``C().f()``). The instance is ignored except for its class.
- Static methods in Python are similar to those found in Java or C++. For a more
- advanced concept, see :func:`classmethod` in this section.
+ Static methods in Python are similar to those found in Java or C++. Also see
+ :func:`classmethod` for a variant that is useful for creating alternate
+ class constructors.
For more information on static methods, consult the documentation on the
standard type hierarchy in :ref:`types`.
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list