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."

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

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.

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.

@Antti The behavior follows this standard:

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


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

@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."

> 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.

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

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

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