[Python-3000] PATCH: library reference docs for PEP 3101

[Eric Smith]

Talin wrote:
> I just posted on the tracker a patch which adds extensive documentation 
> for PEP 3101 to the Python Library Reference. This includes:
> 
>    str.format()
>    format()
>    __format__
>    Formatter
>    format string syntax
>    format specification mini-language
> 
> http://bugs.python.org/issue1068
> 
> (Eric, my description of the Formatter overloaded methods may not match 
> your latest revisions. Feel free to point out any errors.)

This is awesome!  Thanks.

The only 2 differences are:

- in the implementation for float formatting, a type of '' is the same 
as 'g'.  I think the PEP originally had the wording it does so that 
float(1.0, '') would match str(1.0).  This case now matches, because of 
the change that says zero length format_spec's are the same as str(). 
However, if there's anything else in the format_spec (still with no 
type), it doesn't match what str() would do.
 >>> str(1.0)
'1.0'
 >>> format(1.0)
'1.0'
 >>> format(1.0, "-")
'1'
 >>> format(1.0, "g")
'1'
Actually, str() doesn't add a decimal for exponential notation:
 >>> str(1e100)
'1e+100'

I'd like to see the docs just say that an empty type is the same as 'g', 
but I'm not sure of the use case for what the documentation currently says.


- I changed Formatter.get_field to something like:

    .. method:: get_field(field_name, args, kwargs)

       Given *field_name* as returned by :meth:`parse` (see above),
       convert it to an object to be formatted.  Returns a tuple (obj,
       used_key).  The default version takes strings of the form
       defined in :pep:`3101`, such as "0[name]" or "label.title".
       *args* and *kwargs* are as passed in to :meth:`vformat`.  The
       return value *used_key* has the same meaning as the *key*
       parameter to :meth:`get_value`.