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

Fri Aug 31 11:35:22 CEST 2007

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`.