Default value for optional parameter "default" in the model field reference is not specified

[Paul Dejean]

​https://docs.djangoproject.com/en/dev/ref/models/fields/#default

Optional paramaters in python always have a default value. This default value should be documented.

In this case the default value for the optional parameter "default" is not documented.

[Baptiste Mispelon]

Hi,

I think the reason why it's not currently documented is that the default is the special value django.db.models.NOT_PROVIDED which is not documented either.

I don't believe there's any reason why this special value should remain undocumented so I'd say let's do it!

Thanks.

[Aymeric Augustin]

I beg to differ.

There are three strategies for defining functions with optional keyword arguments:

1. arg=None: this works well when None doesn't make sense as an argument. The target function can assume that the argument wasn't passed if it's None.
2. arg=GUARD where GUARD is a private singleton: this variant is required when the target function needs to be able to tell apart "arg set to None" and "arg not passed", which is the case here.
3. **kwargs: this is an alternative to 2. The target function can check if 'arg' in kwargs to check if arg was passed.

Here, Django uses a different code path when the default argument is provided and when it isn't provided. As a consequence, Django doesn't use its value when it isn't provided. The argument doesn't have a default value; it simply isn't used at all. Implying there's a default value would be misleading and confuse users.

It happens that this particular piece of code is implemented with pattern 2 instead of 3, which makes it look like there's a default value, but that isn't something the users should be aware of. Worse, documenting NOT_PROVIDED would ruin pattern 2, because it only works as long as users don't know the guard value!

If you aren't convinced yet, I'll simply say that this bug report is based upon the idea that "optional paramaters in python always have a default value", which is wrong. Any function that takes **kwargs has optional parameters without a default value -- see django.shortcuts.render for a good example.