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

[Eric Smith]

Georg Brandl wrote:
> 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?

If we want the docs to match the code, instead of:
None   similar to ``'g'``, except that it prints at least one digit 
after the decimal point.

it would be:
None   the same as 'g'.

But before you do that, I want see what Talin says.  I'm not sure if 
instead we shouldn't modify the code to match the docs.

(Sorry about not doing a real diff.  I'm short on time, and haven't 
checked out the new docs yet.)

Eric.