#34808: Some aggregation functions may return None; this isn't well documented
-------------------------------------+-------------------------------------
Reporter: Eric Baumgartner | Owner: Lufafa
Type: | Joshua
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 4.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Eric Baumgartner):
>Hey guys, would it be necessary to add a possible return of None on every
aggregate function
I'm curious what others think, but I'm pretty firm that the documentation
for specific aggregation functions like **Sum** should account for
**None** as a possible return value.
I know this may seem redundant given that **default** is already
documented under Aggregation functions generally.
However, the way some people use the documentation means that they won't
see the general aggregation documentation, because that's not what they're
looking for.
Example (which is pretty close to my experience, which is what led me to
file this issue):
- I want to calculate the total of some field across the records in a
queryset.
- I'm pretty sure this will be called Sum, so I hit the documentation to
look up that function.
- On the querysets page, I scan down the Contents sidebar on the right.
- I find **Sum** in the sidebar. Great! I click it.
I'm now scrolled directly to the definition of the Sum function, which
says:
>Return type: same as input field, or output_field if supplied
Why would I not take that at face value? There's nothing in the definition
of Sum that would lead me to scroll up the page to see the general
documentation for aggregation functions.
If I'm calling Sum for an IntegerField, the return type is int. I
interpret that line as equivalent to `Sum(...) -> int`. When in reality it
is `Sum(...) -> Optional[int]`.
I think a relatively simple fix would be to change this to:
>Return type: same as input field, or output_field if supplied. Returns
**None** for empty querysets.
I would suggest adding this for all aggregation functions except `Count`.
--
Ticket URL: <https://code.djangoproject.com/ticket/34808#comment:13>
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/0107018ab3e19c9a-24668ee2-f216-4eda-ab75-ef5ab1222ace-000000%40eu-central-1.amazonses.com.
