Decimals do not obey ':g' exponential notation formatting rules

[ikelly]

BPO	23460
Nosy	@mdickinson, @ezio-melotti, @skrah, @suutari, @JulienPalard, @sir-sigurd, @tirkarthi, @LorenzMende, @bdbaraban
PRs	bpo-23460: Fix documentation for decimal string :g formatting #11850 [3.8] bpo-23460: Fix documentation for decimal string :g formatting (GH-11850) #15954
Files	issue23460.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 2019-09-11.14:38:47.035>
created_at = <Date 2015-02-13.17:15:21.075>
labels = ['easy', 'type-feature', 'docs']
title = "Decimals do not obey ':g' exponential notation formatting rules"
updated_at = <Date 2019-09-11.14:38:47.035>
user = 'https://bugs.python.org/ikelly'

bugs.python.org fields:

activity = <Date 2019-09-11.14:38:47.035>
actor = 'mdk'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-11.14:38:47.035>
closer = 'mdk'
components = ['Documentation']
creation = <Date 2015-02-13.17:15:21.075>
creator = 'ikelly'
dependencies = []
files = ['38370']
hgrepos = []
issue_num = 23460
keywords = ['patch', 'easy']
message_count = 18.0
messages = ['235904', '235984', '237025', '237032', '237438', '324473', '335183', '335198', '335199', '335200', '335201', '335251', '335503', '336470', '336471', '337049', '351885', '351909']
nosy_count = 11.0
nosy_names = ['mark.dickinson', 'ikelly', 'ezio.melotti', 'skrah', 'docs@python', 'tuomas.suutari', 'mdk', 'sir-sigurd', 'xtreak', 'LorenzMende', 'bdbaraban']
pr_nums = ['11850', '15954']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23460'
versions = ['Python 2.7', 'Python 3.4', 'Python 3.5']

[ikelly]

>>> '{:g}'.format(D('0.000001'))
'0.000001'

Formatted with '{:e}', the exponent would be -6, so per the formatting rules described under the 'g' specifier at https://docs.python.org/3/library/string.html#format-specification-mini-language the above should be formatted using exponential notation.

[skrah]

For Decimal the cutoff point is -6 instead of -4 (following the
decimal specification instead of the C standard).

[ezio-melotti]

Should we add a note to the format docs, or just close this?

[mdickinson]

I don't think we should close: the documentation as written explicitly says that the rules apply to both Decimal and float: "The available presentation types for floating point and decimal values are ...". But the details listed for 'g' are incorrect. We could either fix the description for 'g' to explain what happens for Decimal, or state up front that the table only applies directly to the float type, and that Decimal is similar but not identical.

[suutari]

Here's a patch that fixes the description for 'g' to explain what happens for Decimal and also documents the Decimal.format in the documentation of the decimal module.

[LorenzMende]

I want to bring this issue up again.
As the others correctly stated, either the documentation or the implementation of Decimal 'g' formatting is incorrect.

For floats the implementation suits the docu:
>>> '{:g}'.format(0.00001)
'1e-05'
For decimals:
>>> '{:g}'.format(decimal.Decimal('0.00001'))
'0.00001'

As there is a deviation between documentation and implementation, I advise to modify one of both.

[bdbaraban]

What is the status of this issue? I can submit a PR based on Tuomas Suutari's patch.

[suutari]

What is the status of this issue? I can submit a PR based on Tuomas Suutari's patch.

Don't know more about the status, but nobody seemed to care to take my
patch forward. If contributions are accepted as GitHub pull requests
these days, I can do it myself too.

[skrah]

The patch LGTM, but I'm not sure if we need to document __format__().
Personally I probably wouldn't.

[tirkarthi]

If contributions are accepted as GitHub pull requests
these days, I can do it myself too.

GitHub pull requests are accepted. Please see https://devguide.python.org/ .

Thanks

[skrah]

Yes, these days PRs are the only way to get anything done. Before
GitHub it would have been possible to just commit the small diff
directly to master.

[bdbaraban]

Well, Tuomas, I defer submission of a PR to you, as its your original patch.

[bdbaraban]

I submitted a PR just now. I only pushed the change to string.rst, as per Stefan Krah's suggestion.

[skrah]

I just noticed that there are other differences, for example the "removal of trailing zeros" passage does not apply to Decimal:

>>> format(Decimal("1.000000e-6"), "g")
'0.000001000000'

Perhaps it would be easier to have separate docs for float and decimal after all, or a long footnote for decimal.

[skrah]

On the other hand, the docs say "insignificant trailing zeros are removed from the significand", so technically it *is* correct, because trailing zeros are significant in decimal.

[bdbaraban]

Hi Stefan. Is there an update you would like me to make on this PR? Otherwise, pinging for review.

[JulienPalard]

New changeset 1660a61 by Julien Palard (Brennan D Baraban) in branch 'master':
bpo-23460: Fix documentation for decimal string :g formatting (GH-11850)
1660a61

[JulienPalard]

New changeset 629f1f8 by Julien Palard (Miss Islington (bot)) in branch '3.8':
bpo-23460: Fix documentation for decimal string :g formatting (GH-11850) (GH-15954)
629f1f8