#30958: Documentation for Cast function is somewhat misleading.
------------------------------------------------+------------------------
Reporter: Keryn Knight | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
[https://docs.djangoproject.com/en/dev/ref/models/database-
functions/#django.db.models.functions.Cast Cast docs] make use of a
`Value` model, whose definition isn't given, which has a **field** called
integer, which is then referenced via {{{annotate(as_float=Cast('integer',
FloatField()))}}}
If you gloss over the previous line, it looks like "integer" is the
**type** to cast into, and as doesn't use output_field as a named
argument, it becomes unclear how to adapt it to your own code (this is
exactly what has happened for a user on IRC)
Additionally, the docs lead with
> We’ll be using the following model in examples of each function
and a definition for an `Author`, whose **age** field could be used as the
stand-in for the Cast example, instead of the mysterious `Value` model
class (and `Value` is re-used elsewhere in that page, but not as a random
model, but `django.db.models.Value`)
I think it would be less confusing if it looked something like:
{{{
>>> Author.objects.create(age=4, name='Margaret Smith')
>>> msmith = Author.objects.annotate(age_as_float=Cast('age',
output_field=FloatField())).get()
>>> print(msmith.age_as_float)
4.0
}}}
instead of
{{{
>>> Value.objects.create(integer=4)
>>> value = Value.objects.annotate(as_float=Cast('integer',
FloatField())).get()
>>> print(value.as_float)
4.0
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/30958>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/052.5bfd399dd057717af143747abb3e544c%40djangoproject.com.
