classification
Title: %f is confusingly associated with fixed point format
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: MikeFoxtrot, docs@python, mark.dickinson, miss-islington, terry.reedy
Priority: normal Keywords: patch

Created on 2018-07-29 21:25 by MikeFoxtrot, last changed 2018-08-06 13:04 by terry.reedy. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 8673 merged terry.reedy, 2018-08-04 19:22
PR 8686 merged miss-islington, 2018-08-06 12:41
PR 8687 merged miss-islington, 2018-08-06 12:41
PR 8688 merged terry.reedy, 2018-08-06 12:57
Messages (9)
msg322644 - (view) Author: Michael Fischer (MikeFoxtrot) Date: 2018-07-29 21:25
In section "7.1.3.1. Format Specification Mini-Language" of the documentation (https://docs.python.org/2/library/string.html) both %f and %F are labelled "Fixed point". This is confusing for someone who a) transitions over from C or variants or b) knows the difference between fixed and floating point numbers. 

I suggest either changing the "Fixed" to "Floating" or explaining what is meant by "Fixed Point" (because I'm sure there's a reason why someone has named it like that in the first place).
msg322679 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2018-07-30 14:52
FTR, here "fixed point" refers to the output representation (a decimal string) rather than the input (a floating-point binary value). The output of %f gives a *fixed* number of places after the decimal point (6 by default).

Contrast with %e, which gives a floating-point output representation.

But yes, there are probably less confusing ways to word this. Did you have a particular alternative wording in mind?

Here's the behaviour of %f for different scale values: note that the output always has the same number of digits after the point, but the number of significant digits varies.

>>> "%f" % math.pi
'3.141593'
>>> "%f" % (100.0 * math.pi)
'314.159265'
>>> "%f" % (0.01 * math.pi)
'0.031416'

And here's %e. Now it's the other way around: the number of significant digits stays the same, but the exponent changes to reflect the magnitude.

>>> "%e" % math.pi
'3.141593e+00'
>>> "%e" % (100 * math.pi)
'3.141593e+02'
>>> "%e" % (0.01 * math.pi)
'3.141593e-02'
msg322852 - (view) Author: Michael Fischer (MikeFoxtrot) Date: 2018-08-01 09:15
Thank you for your quick reply. I understand why you chose this description better now. However in C %f behaves exactly the same as in Python (for floating-point numbers) and you will mostly find the description for it along the lines of:

'%f' Print a floating-point number in normal (fixed-point) notation. [The GNU C Library Reference Manual - https://www.gnu.org/software/libc/manual/pdf/libc.pdf]

For the sake of simplicity I suggest the following wording:

Fixed point notation. Displays the (floating-point) number as a fixed-point number. The default precision is 6.

In my opinion this emphasizes the intent (fixed precision representation) and hints at the independence of input type, by putting the floating-point in brackets.
msg323080 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-08-03 21:21
The closest anchor is https://docs.python.org/3.8/library/string.html#format-specification-mini-language.

The table title is "The available presentation types for floating point and decimal values are:".

This is slightly confusing to me.  Does this mean instances of 'float' and 'decimal' classes?  or 'floating point numbers (floats and decimals)  and integral numbers, sometimes called decimals since usually written with decimal digits'?

Within the table, 'number' refers to whatever the title refers to. So I think adding '(floating point)' would be confusing and wrong, as it excludes 'decimals' whatever they are.  On the other hand, changing 'Fixed point' to 'Fixed point notation', in parallel with 'Exponential notation', is correct and should be helpful.
msg323102 - (view) Author: Michael Fischer (MikeFoxtrot) Date: 2018-08-04 13:08
Terry: I absolutely agree with you. Changing 'Fixed point' to 'Fixed point notation' is the optimal solution here.
msg323201 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-08-06 12:41
New changeset 28c7f8c8ce34a0cb848822a252a9d0a761fb42d5 by Terry Jan Reedy in branch 'master':
bpo-34273: Change 'Fixed point' to 'Fixed-point notation'. (#8673)
https://github.com/python/cpython/commit/28c7f8c8ce34a0cb848822a252a9d0a761fb42d5
msg323202 - (view) Author: miss-islington (miss-islington) Date: 2018-08-06 12:47
New changeset e39fb207f26f8007e95fcf120f5ff1cb7372791a by Miss Islington (bot) in branch '3.7':
bpo-34273: Change 'Fixed point' to 'Fixed-point notation'. (GH-8673)
https://github.com/python/cpython/commit/e39fb207f26f8007e95fcf120f5ff1cb7372791a
msg323203 - (view) Author: miss-islington (miss-islington) Date: 2018-08-06 12:49
New changeset ed8dd598ae7e0d944974af0fd73c2fbb6105fd5c by Miss Islington (bot) in branch '3.6':
bpo-34273: Change 'Fixed point' to 'Fixed-point notation'. (GH-8673)
https://github.com/python/cpython/commit/ed8dd598ae7e0d944974af0fd73c2fbb6105fd5c
msg323204 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-08-06 13:03
New changeset 9027502e99cba700cadb675b3b2db03c311d1c4d by Terry Jan Reedy in branch '2.7':
[2.7] bpo-34273: Change 'Fixed point' to 'Fixed-point notation'. (GH-8673)
https://github.com/python/cpython/commit/9027502e99cba700cadb675b3b2db03c311d1c4d
History
Date User Action Args
2018-08-06 13:04:24terry.reedysetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-08-06 13:03:47terry.reedysetmessages: + msg323204
2018-08-06 12:57:07terry.reedysetpull_requests: + pull_request8183
2018-08-06 12:49:37miss-islingtonsetmessages: + msg323203
2018-08-06 12:47:39miss-islingtonsetnosy: + miss-islington
messages: + msg323202
2018-08-06 12:41:43miss-islingtonsetpull_requests: + pull_request8182
2018-08-06 12:41:35miss-islingtonsetpull_requests: + pull_request8181
2018-08-06 12:41:26terry.reedysetmessages: + msg323201
2018-08-04 19:22:32terry.reedysetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request8165
2018-08-04 13:08:41MikeFoxtrotsetmessages: + msg323102
2018-08-03 21:21:57terry.reedysetversions: + Python 2.7, Python 3.6, Python 3.7, Python 3.8
nosy: + terry.reedy

messages: + msg323080

stage: needs patch
2018-08-01 09:15:56MikeFoxtrotsetmessages: + msg322852
2018-07-30 14:52:32mark.dickinsonsetnosy: + mark.dickinson
messages: + msg322679
2018-07-29 21:25:52MikeFoxtrotcreate