Decimal('0.0000005').quantize(Decimal('1.1111111')) -> Decimal('5E-7') # should be unchanged

[michael-db]

Bug report

Bug description:

import decimal
Decimal = decimal.Decimal
Decimal('0.000005').quantize(Decimal('1.111111')) # Decimal('0.000005') correct
Decimal('0.0000005').quantize(Decimal('1.1111111')) # Decimal('5E-7') wrong

According to the documentation, https://docs.python.org/3/library/decimal.html#decimal.Decimal.quantize
quantize() should "Return a value equal to the first operand after rounding and having the exponent of the second operand."
Clearly, it is not respecting the exponent of the second operand, even if that exponent is given explicitly:

Decimal('0.0000005').quantize(Decimal('1.1111111e0')) # Decimal('5E-7') wrong

CPython versions tested on:

3.13

Operating systems tested on:

Linux

[michael-db]

More directly, the immediate problem is

Decimal('0.0000005') # Decimal('5E-7')

But there is already a normalize() function for that if I wanted it

Decimal('0.0000005').normalize()

So, in this case of leading zeroes, normalize() has been rendered superfluous, while quantize() has been rendered useless.

If this limitation is not to be corrected then at a minimum it needs to be documented.

[skirpichev]

I suspect you misunderstand which "exponent" referenced in docs here, assuming it's just zero in both cases. It's not. You can use as_tuple() method to check exponent value. Then, results seems correct for me:

>>> Decimal('0.0000005').quantize(Decimal('1.1111111'))
Decimal('5E-7')
>>> _.as_tuple()[-1] == Decimal('1.1111111').as_tuple()[-1]
True
>>> Decimal('0.000005' ).quantize(Decimal('1.111111' ))
Decimal('0.000005')
>>> _.as_tuple()[-1] == Decimal('1.111111' ).as_tuple()[-1]
True

So, I don't think there is an issue.

Edit: For me it seems that from the documentation is clear which exponent referenced (and it's not one, shown in repr output or provided by you in string form of the Decimal constructor). So, I doubt there is a documentation issue as well.

But there is already a normalize() function for that

What do you mean by "that"? The normalize() function is to get the canonical representation for a Decimal.

[michael-db]

"No issue"? If the exponent referred to is the internal exponent, not that appearing in the representation, then the documentation at least needs to make that clear. The example doesn't, and I am not the first person to find this quite misleading https://stackoverflow.com/questions/61704496/ Documentation is supposed to be for those unfamiliar with a module, not those who already know.

Like the person asking that question, I wanted control over the representation. The normalize() and quantize() methods appear to provide that control within the decimal module, and would be more useful if they did.

[skirpichev]

If the exponent referred to is the internal exponent

It's not "internal", this value is available via public interface. And you also can construct a Decimal object from tuple.

then the documentation at least needs to make that clear

Just don't mix the exponent value for a Decimal object with it's string representation. Current documentation seems clear for me in this aspect.

You can take look on _pydecimal.Decimal.__str__ method to see how the exponent value used to form a string representation. Fixed point or scientific notation chosen based on the exponent value. But if the number formatted in a fixed point notation - that doesn't mean it has zero exponent.

I wanted control over the representation.

It's not clear what do you mean. Probably, you want to control a string representation. In this case you should look on string formatting (str.format() method and f-strings).

[michael-db]

Thank you for your reply, but I must say it again: Documentation is supposed to be for those unfamiliar with a module, not those who already know.

An example making clear that the exponent referred to was the internal one, together with a link to the as_tuple() method for what is meant by "exponent" would solve the problem as far as the documentation is concerned.

That would be more productive than arguing about words like "internal" (what you call it is entirely irrelevant, the fact is that it is a distinct exponent from the representative string) and disregarding the evidence that those unfamiliar with the module have found the documentation misleading on this point.

[skirpichev]

the exponent referred to was the internal one

Again, it's not "internal". It's the exponent value, referred in many other places across the docs. You mistakenly interpreted the "exponent" here as "the exponent in scientific notation, when some Decimal represented this way in a string form". Could you please explain how did you come to this interpretation from the docs?

There is a link to the decimal arithmetic specification, where all terms are defined. If you are unfamiliar with the floating-point arithmetic (not with the module!) - it's a good source to start with. Or just read Wikipedia article: https://en.wikipedia.org/wiki/Floating-point_arithmetic

together with a link to the as_tuple() method for what is meant by "exponent" would solve the problem

Unfortunately, this "problem" span many other methods. I don't think we should clutter documentation with examples, that should be obvious to a careful reader.

IMO, sphinx docs for the decimal module already have examples, showing the difference between string representation and exponent notion. For instance, from constructor docs:

If value is a tuple, it should have three components, a sign (0 for positive or 1 for negative), a tuple of digits, and an integer exponent. For example, Decimal((0, (1, 4, 1, 4), -3)) returns Decimal('1.414').

But lets keep this for a while, maybe someone else will see how docs should be improved.

[michael-db]

If you like Wikipedia, try reading this page about a certain cognitive bias in evidence here: https://en.wikipedia.org/wiki/Curse_of_knowledge It explains why, as a general principle, you should value feedback from reviewers instead of blaming them for being careless.

On a "careful reading", an error in the documentation for to_eng_string() would be obvious, yet you have not spotted it. Perhaps that example could lead you to have a little more empathy for readers. It is also one of several places where the word "exponent" is used to mean exactly what people expect it to mean, i.e., whatever comes after the 'E'.

Clutter: This is a poor excuse. With a little imagination, no clutter is required. If you really need to limit yourself to a single example, you could choose one that avoids misunderstanding. If you need to use the word "exponent" to refer to two different things, then you could add a one-word qualifier to avoid misinterpretation. If you have a peculiar objection to the word "internal" then make up another one and define it.

Arguing with someone whose default response is to put all their effort into denying that there is a problem and making excuses for not fixing it is not a good use of my time. I won't be commenting further.

[skirpichev]

If you like Wikipedia

Not at all. But it's enough to provide you some basic information about floating-point arithmetic.

an error in the documentation for to_eng_string() would be obvious

If you found an error in docs - feel free to open a bug.

It is also one of several places where the word "exponent" is used to mean exactly what people expect it to mean, i.e., whatever comes after the 'E'.

I don't sure you are right about people expectations. People, who read something such basic as https://en.wikipedia.org/wiki/Floating-point_arithmetic - will assume very different meaning for exponent in context of floating-point arithmetic.

Are other places also related to string representation of Decimal's?

If you need to use the word "exponent" to refer to two different things, then you could add a one-word qualifier to avoid misinterpretation.

Can you propose some concrete suggestion?

[terryjreedy]

@rhettinger