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

[Antoine Pitrou]

On Sun, 26 Feb 2012 19:50:10 +0100
martin at v.loewis.de wrote:
> >> -   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).

It would be nice to call it something else than "printf-style
formatting". While it is certainly modelled on printf(), knowledge of C
or printf is not required to understand %-style formatting, nor even to
appreciate it.

Regards

Antoine.