Overall, I agree with Simon analysis. Specifically, the docs for db_default say:
The database-computed default value for this field.
So, when doing val = IntegerField(db_default=10); foo = Foo(); foo.val, I would expect anything but the value that was set as db_default (10), since the code "hasn't gone to the db yet". Intuitively I would have expected an exception such as "you can't have a value since DB hasn't been reached yet", but getting a instance of a "db value promise" is even better and clearer.
OTOH, I do agree that we may be lacking docs about this. In particular, I think we should:
- add a small note to the existing
ref/models/fields.txt docs about db_default, and
- add a richer section to the
topics/db/models.txt for :attr:~Field.db_default since most of the Field options are documented there but db_default is missing.
Accepting and re-purposing this ticket with that goal in mind.