[Python-checkins] cpython (merge 3.2 -> default): Document default fmtspec. Fix inaccurate note. Document exceptions.

[raymond.hettinger]

http://hg.python.org/cpython/rev/a85cf047f56a
changeset:   70038:a85cf047f56a
parent:      70036:482f60d6a687
parent:      70037:65f8a084220f
user:        Raymond Hettinger <python at rcn.com>
date:        Wed May 11 10:48:02 2011 -0700
summary:
  Document default fmtspec. Fix inaccurate note. Document exceptions.

files:
  Doc/library/functions.rst |  11 +++++++----
  1 files changed, 7 insertions(+), 4 deletions(-)


diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -498,11 +498,14 @@
    of the *value* argument, however there is a standard formatting syntax that
    is used by most built-in types: :ref:`formatspec`.
 
-   .. note::
+   The default *format_spec* is an empty string which usually gives the same
+   effect as calling ``str(value)``.
 
-      ``format(value, format_spec)`` merely calls
-      ``value.__format__(format_spec)``.
-
+   A call to ``format(value, format_spec)`` is translated to
+   ``type(value).__format__(format_spec)`` which bypasses the instance
+   dictionary when searching for the value's :meth:`__format__` method.  A
+   :exc:`TypeError` exception is raised if the method is not found or if either
+   the *format_spec* or the return value are not strings.
 
 .. function:: frozenset([iterable])
    :noindex:

-- 
Repository URL: http://hg.python.org/cpython