Documentation should make clear that values on DecimalField is better to be passed as strings

[Alexandros Kanterakis]

On the documentation of ​DecimalField it does not mention that passing values as string instead of float has a significant difference. A user that tests the code in the documentation might come to a surprise to find that the following part raises a ValidationError:

class A(models.Model):
        # A DecimalField as mentioned on the doc
        # "For example, to store numbers up to 999 with a resolution of 2 decimal places, you’d use:"
	f = models.DecimalField(max_digits=5, decimal_places=2) 

A(f=10.1).clean_fields()  # This raises the following exception:
django.core.exceptions.ValidationError: {'f': ['Ensure that there are no more than 2 decimal places.']} 

If the value of f is passed as string, then it works as expected.

A(f="10.1").clean_fields() 

There is a very subtle reference about this on the documentation of the ​decimal module:

>>> Decimal(3.14)
Decimal('3.140000000000000124344978758017532527446746826171875')

See also discussion in SO: ​https://stackoverflow.com/questions/52376693/django-strange-decimalfield-validation

[Tim Graham]

Generally the value would be passed as a Decimal rather than as a string so I'm not sure it needs to be documented.

[Carlton Gibson]

I'm kind of sympathetic to this, because it may well be the first instance in which beginners come across this kind of computer weirdness.

However... I'm not sure the model field reference is the place to teach this kind of thing and we already like to the FloatFields vs DecimalFields discussion, and from there to the decimal docs.

This discussion (i.e. the decimal docs) is a bit advanced for the situation in mind, so I wonder if linking instead to the ​Decimal Floating Point Arithmetic section of the Python Tutorial (which itself links back to the decimal docs) wouldn't be a win?

[Tim Graham]

Yea, I don't think using strings is a best practice in the first place, so let's not get into the discussion.