Wrong default precision in documentation for format

[Barium]

BPO	22546
Nosy	@terryjreedy, @mdickinson, @ericvsmith
Files	missing_type_specifier.patch missing_type_specifier2.patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-10-06.06:06:23.368>
created_at = <Date 2014-10-03.09:31:18.767>
labels = ['type-bug', 'docs']
title = 'Wrong default precision in documentation for format'
updated_at = <Date 2014-10-06.06:06:23.367>
user = 'https://bugs.python.org/Barium'

bugs.python.org fields:

activity = <Date 2014-10-06.06:06:23.367>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-10-06.06:06:23.368>
closer = 'terry.reedy'
components = ['Documentation']
creation = <Date 2014-10-03.09:31:18.767>
creator = 'Barium'
dependencies = []
files = ['36798', '36799']
hgrepos = []
issue_num = 22546
keywords = ['patch']
message_count = 10.0
messages = ['228318', '228323', '228367', '228435', '228438', '228439', '228512', '228542', '228643', '228644']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'mark.dickinson', 'eric.smith', 'docs@python', 'python-dev', 'Barium']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue22546'
versions = ['Python 3.4', 'Python 3.5']

[Barium]

The format documentation for the Format Specification Mini-Language for python 3.3 (perhaps newer and older as well) at: https://docs.python.org/3.3/library/string.html

States for type '' (for floating point numbers):

Similar to 'g', except with at least one digit past the decimal point and a default precision of 12. This is intended to match str(), except you can add the other format modifiers.

This appears not to be true, the following code example, run in Python 3.3.2:

>>> '{}'.format(3.14159265358979323846264338327950288419)
'3.141592653589793'

As it can be seen form the output the default precision appears to be 15.

[ericvsmith]

I think this is a result of changing the precision of str() to match repr().

2.7 prints:
'3.14159265359'

[terryjreedy]

"The precision is a decimal number indicating how many digits should be displayed ... before and after the decimal point for a floating point value formatted with 'g' or 'G'. It seems that str, repr, and '' are using precision 16, and the doc should be changed to match.

>>str(.314159265358979323846264338327950288419)
'0.3141592653589793' # 16, not counting 0.

>>> '{}'.format(3.14159265358979323846264338327950288419)
'3.141592653589793'
>>> '{:.16g}'.format(3.14159265358979323846264338327950288419)
'3.141592653589793'
>>> str(3.14159265358979323846264338327950288419)
'3.141592653589793'  # 16

But I discovered this 'anomaly' (bug?)
>>> str(31.4159265358979323846264338327950288419)
'31.41592653589793'
>>> str(33.14159265358979323846264338327950288419)
'33.1415926535898'  # precision 15
I expected this last to be
'33.14159265358979'
as 32... rounds down, not up.

repr and '{}'.format act the same.

[mdickinson]

It seems that str, repr, and '' are using precision 16

None of them is using a fixed precision: they're all using David Gay's implementation of the "shortest string" algorithm (à la Burger and Dybvig). For repr, this is the case since Python 3.1 / 2.7; for str and formatting with no type specifier, since Python 3.2. The docs definitely do need updating here.

I expected this last to be
'33.14159265358979'

'33.1415926535898' is shorter, and rounds back to the same floating-point number, so that's what Gay's algorithm gives here.

[mdickinson]

Here's a proposed fix.

[mdickinson]

Hmm; it's only outputs in non-scientific notation that are guaranteed to have a decimal point. Patch updated.

[terryjreedy]

I see now that my expectation, based on decimal rounding rather than binary conversion and rounding, was wrong ;-)
>>> 33.14159265358979323846264338327950288419 == 33.1415926535898
True
>>> 33.14159265358979323846264338327950288419 == 33.14159265358979
False
>>> format(33.14159265358979323846264338327950288419, '.18')
'33.1415926535897967'

Tommy: 3.3 only gets security fixes. When a core developer (indicated by the blue and yellow snake symbol) resets Versions, you should leave them alone or ask before changing.

As for the patch: 'non-scientific' == 'fixed-point', the expression already used in the table. The rewrite omits the fact the exception is to match str and that g and str are otherwise the same except for fixed versus 'as needed' precision. I note that '' = 'd' for integers also makes '' for integers similar to str() as modified by the preceding options. An alternate rewrite:

Similar to 'g', except that fixed-point notation, when used, has at least one digit past the decimal point. The default precision is as high as needed to represent the particular value. The overall effect is to match the output of str() as altered by the other format modifiers.

--
The following in the examples could be fixed in the same patch
>>> '{:+f}; {:+f}'.format(3.14, -3.14)  # show it always
'+3.140000; -3.140000'

add to the comment 'it always displays a sign'.

[mdickinson]

Terry: your rewrite looks fine to me. +1 for committing that.

[python-dev]

New changeset 041d0752171a by Terry Jan Reedy in branch '3.4':
Issue bpo-22546: update doc for mini-language float None presentation type.
https://hg.python.org/cpython/rev/041d0752171a

[terryjreedy]

Tommy, thanks for reporting this.