decimal.Context.to_eng_string wrong docstring

[ff59cd45-ebe3-4b3e-9696-65dc59a38b8c]

BPO	27720
Nosy	@rhettinger, @skrah, @ztane, @evelynmitchell
Files	patch27720 decimal_eng_doc.diff

^{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: ```python assignee = 'https://github.com/rhettinger' closed_at = created_at = labels = ['docs'] title = 'decimal.Context.to_eng_string wrong docstring' updated_at = user = 'https://github.com/ztane' ``` bugs.python.org fields: ```python activity = actor = 'rhettinger' assignee = 'rhettinger' closed = True closed_date = closer = 'rhettinger' components = ['Documentation'] creation = creator = 'ztane' dependencies = [] files = ['44072', '44073'] hgrepos = [] issue_num = 27720 keywords = ['patch'] message_count = 10.0 messages = ['272259', '272393', '272402', '272412', '272416', '272430', '272433', '272456', '272603', '272604'] nosy_count = 6.0 nosy_names = ['rhettinger', 'skrah', 'docs@python', 'python-dev', 'ztane', 'Evelyn Mitchell'] pr_nums = [] priority = 'normal' resolution = 'fixed' stage = 'patch review' status = 'closed' superseder = None type = None url = 'https://bugs.python.org/issue27720' versions = [] ```

[ff59cd45-ebe3-4b3e-9696-65dc59a38b8c]

https://docs.python.org/3/library/decimal.html#decimal.Context.to_eng_string

The docstring for Context.to_eng_string says "Converts a number to a string, using scientific notation.", which is, less extra comma, exactly the docstring for Context.to_sci_string. It should probably say "using engineering notation".

Additionally, docstring for Decimal.to_eng_string uses the term "an engineering-type string", which no one uses outside the said docstring. It should probably also say "Convert to a string using engineering notation."

[5bdc2844-6f38-4b45-8218-144d190d3165]

I had to look up what engineering notation meant, so I added detail to the docstring.

[rhettinger]

Thanks Evelyn. I've refined this a bit to incorporate the more precise wording in the decimal arithmetic specification (see http://speleotrove.com/decimal/daconvs.html ). Also added the missing doctests and synced-up the wording between the docstrings and the main docs.

[ff59cd45-ebe3-4b3e-9696-65dc59a38b8c]

Raymond: your doc patch is not quite right. Decimal('123e1') is converted to Decimal('1.23e3') internally already; so that str(d) will print 1.23e3, scientific notation of that number is '1.23e3' and engineering notation is '1.23e3', thus not a good example. A better example would be Also, the engineering notation is a string, not a Decimal instance.

Also, now that I test it, the whole to_eng_string seems to be utterly broken, same applies to "to_sci_string". They do not print in scientific notation if the exponent in the original number was 0:

decimal.Decimal('123456789101214161820222426.0e0').to_eng_string()

And all operations with decimal will now generate numbers with exponent of 0 if it is within their precision, so no engineering notation is ever printed, duh.

[5531d0d8-2a9c-46ba-8b8b-ef76132a492c]

@Antti The behavior follows this standard:

http://speleotrove.com/decimal/decarith.html

Nothing we can do about it even if we wanted to.

[ff59cd45-ebe3-4b3e-9696-65dc59a38b8c]

@Stefan after reading the bad standard I agree that it follows the standard, as unfortunate as it is.

However, that part is then also wrong in Raymond's documentation patch. It should be something like: the exponent is adjusted to a multiple of 3 if *any* exponent is to be shown, and exponent is shown only if the exponent is larger than there are significant figures in the number, or if it is less than or equal to -6, or something alike.

Or perhaps it should say "This is not the notation you are looking for."

[5531d0d8-2a9c-46ba-8b8b-ef76132a492c]

after reading the bad standard ...

Make sure not to buy a Power 6 processor and not to use IEEE 754-2008, because that's essentially what you'll get.

IEEE doesn't specify engineering notation though.

[5bdc2844-6f38-4b45-8218-144d190d3165]

Thank you Raymond for a detailed patch update.

I will mention that matlab does not support this conversion [1]. R doesn't support engineering notation, either.

It may be that this conversion isn't expected to be part of the standard library, and people are more likely to write their own. [2]

The rationale for engineering notation is that it corresponds to SI units of measure.

[1] https://www.mathworks.com/matlabcentral/newsreader/view_thread/22843 [2] http://stackoverflow.com/questions/8262302/python-fixed-exponent-in-scientific-notation

[1762cc99-3127-4a62-9baf-30c3d0f51ef7]

New changeset 825713d3786a by Raymond Hettinger in branch '2.7': Issue bpo-27720: Fix error in eng_to_decimal docs and add examples from the specification. https://hg.python.org/cpython/rev/825713d3786a

[1762cc99-3127-4a62-9baf-30c3d0f51ef7]

New changeset de2a9c98948e by Raymond Hettinger in branch '3.5': Issue bpo-27720: Fix error in eng_to_decimal docs and add examples from the specification. https://hg.python.org/cpython/rev/de2a9c98948e