[Python-Dev] [Python-checkins] cpython (3.2): Issue #14123: Explicitly mention that old style % string formatting has caveats

[Terry Reedy]

On 2/26/2012 1:50 PM, martin at v.loewis.de wrote:
>
> Zitat von Eli Bendersky <eliben at gmail.com>:
>
>>>
>>> - The formatting operations described here are obsolete and may go away
>>> in future
>>> - versions of Python. Use the new :ref:`string-formatting` in new code.
>>> + The formatting operations described here are modelled on C's printf()
>>> + syntax. They only support formatting of certain builtin types. The
>>> + use of a binary operator means that care may be needed in order to
>>> + format tuples and dictionaries correctly. As the new
>>> + :ref:`string-formatting` syntax is more flexible and handles tuples
>>> and
>>> + dictionaries naturally, it is recommended for new code. However, there
>>> + are no current plans to deprecate printf-style formatting.
>>>
>>
>> Please consider just deleting the last sentence. Documentation is
>> meant for
>> users (often new users) and not core devs. As such, I just don't see what
>> it adds. If the aim to to document this intent somewhere, a PEP would
>> be a
>> better place than the formal documentation.
>
> I'd rather leave the last sentence, and delete the penultimate sentence.
> The last sentence is useful information to the end user ("we will not
> deprecate printf-style formatting, so there is no need to change existing
> code"). I'd drop the penultimate sentence because there is no consensus
> that it is a useful recommendation (and it is certainly not a statement
> of fact).

I agree that the 'recommendation' is subjective, even though I strongly 
agree with it *for new Python programmers who are not already familiar 
with printf style formatting*. However, that sort of nuanced 
recommendation goes better in a HowTo. Statements about non-deprecation 
are also out of place as that is the default. So I agree with both of 
you. Let us drop both of the last two sentences. Then we can all be happy.

There is a difference between 'There are no current plans to ...' and 
'We will never ...'. However, '...' should not be discussed or even 
proposed or even mentioned until there is a bug-free automatic 
converter. I think the recent rehashing was mostly a needless irritation 
except as it prompted a doc update.

---
Terry Jan Reedy