Document (undefined) rounding behaviour of new-style formatting

[jowagner]

Documentation

Current documentation of new-style formatting does not talk about rounding and that the rounding behaviour is undefined / platform-dependent. Popular platforms seem to round to the nearest number of the selected precision with ties rounded to the number with even last digit, e.g. '{:.2f}'.format(1/8) produces 0.12. This choice as well the dependence on the platform will be unexpected to many users.

While ties are rare for random numbers, ties can be frequent in some applications, e.g. when reporting a percentage where the total is a fairly small multiple (greater than 1) of a power of 10 and the number of digits selected for printing covers increments of 1 divided by that power of 10, e.g. n = 80000 and '{:.2f}%'.format(100*count/n).

The documentation should draw attention to the undefined rounding behaviour and to that there are a number of competing popular choices. A link to the list of rounding behaviours supported by the decimal module may also help.

Based on discussion in issue #99534.

Similar: issue #99875

Linked PRs

• gh-99880: document rounding mode for new-style formatting #121481
• [3.13] gh-99880: document rounding mode for new-style formatting (GH-121481) #126334
• [3.12] gh-99880: document rounding mode for new-style formatting (GH-121481) #126335

[ericvsmith]

I think this and the other similar issue should just point to the builtin round() function for details. No need for second or third similar explanation in the documentation.

[jowagner]

[...] should just point to the builtin round() function for details.

#99534 (comment) says the rounding behaviour of new-style formatting depends on the platform. In contrast, the rounding behaviour of round() is well defined (round ties to even). This implies that new-style formatting does NOT call round() and referring to its documentation would be misleading.

[ericvsmith]

As @mdickinson wrote elsewhere, it's difficult to provide an answer that is both precise and at the same time useful to most users. Personally, I think "rounds like the round() function" is close enough.

[jowagner]

Documentation should be trustworthy. Deliberately including wrong information is bad. Complexity is no excuse as the complexity does not have to be described. It suffices to say that the behaviour is complex, or, as in this case, that the behaviour is undefined and can change with the implementation (and/or the platform CPython is built for).

If "close enough" is the attitude to Python documentation it wouldn't be surprising if the behaviour of round() is in fact also undefined and the documentation just based on observations on popular platforms.

[skirpichev]

PR is ready for review: #121481 If this looks fine, I'll address #99875 in a similar way.

[skirpichev]

Closed by 7d7d56d