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

[Georg Brandl]

Eric Smith schrieb:
> 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.

Can you suggest a patch?

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

I changed this.

Georg

-- 
Thus spake the Lord: Thou shalt indent with four spaces. No more, no less.
Four shall be the number of spaces thou shalt indent, and the number of thy
indenting shall be four. Eight shalt thou not indent, nor either indent thou
two, excepting that thou then proceed to four. Tabs are right out.