A common mistake I see people doing is using output_field with the field type instead of an instance:
Cast('some_field', output_field=BooleanField)
This is incorrect because output_field expects an instance.
Would there be any interest in allowing output_field to accept types and automatically instantiate the type if so? Naturally this would only make sense for fields that don’t require any arguments.
What happens when people make this mistake? Do they always immediately get a traceback or can we silently do the wrong thing?
If it’s easy to diagnose and fix for a user, it might be reasonable for Django to wontfix. That said, the added complexity in the Django codebase sounds like it would be minimal, so maybe it’s worth smoothing the experience here.
I have myself made this mistake several times. This post made me dedicate a few minutes to wonder why, whether it’s something (missing or indicating otherwise) in the docs, or something else.
While I (sometimes) need to read (docs) slower to catch this subtleties, I think the Django docs could benefit from the following:
Add an introductory paragraph, below “Supported arithmetic”, dedicated to output_field specifics. This could build from the existing paragraph shown in Value or in Aggregate.
The reason for my suggestion is that many of the functions in the referenced doc page use output_field but none except Value and Aggregate describe the param and that’s midway the page content. Specifically, the first time is encountered (when reading top bottom) is in the F docs and is completely out of the blue:
Since F() does not directly support output_field you will need to wrap the expression with ExpressionWrapper
@nessita +1. I think the docs throughout this section are a little terse (or not easy to break into) so clarification is definitely welcome from my POV.