Opened 3 years ago

Closed 3 years ago

#33484 closed Cleanup/optimization (wontfix)

Improve docs about date lookup filter

Reported by: MojixCoder Owned by: nobody
Component: Documentation Version: 4.0
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description (last modified by MojixCoder)

Django docs about date lookup filter:

For datetime fields, casts the value as date. Allows chaining additional field lookups. Takes a date value.

But I have tried that we can also use a string value representing the date or datetime object instead of date object.
and also all of the examples of this filter are implemented using date objects.
Shouldn't we add that we can also pass a string or datetime value instead of date?

So the docs says it only takes date object.
But in reality it takes datetime, date, str objects.

Here is the https://docs.djangoproject.com/en/4.0/ref/models/querysets/#date in the docs.

Change History (6)

comment:1 by MojixCoder, 3 years ago

Description: modified (diff)

comment:2 by MojixCoder, 3 years ago

Description: modified (diff)

comment:3 by MojixCoder, 3 years ago

Description: modified (diff)

comment:4 by MojixCoder, 3 years ago

Summary: Improve docsImprove docs about date lookup filter

comment:5 by MojixCoder, 3 years ago

Description: modified (diff)

comment:6 by Carlton Gibson, 3 years ago

Resolution: wontfix
Status: newclosed

Hi MojixCoder.

I'm going to say wontfix here.

That you can pass a datetime or suitably formatted string is relying on the internals of DateField.to_python(). If you know about it then fair enough, but I don't think it makes for more readable code to document and promote that. It's more in-line with the expectations to just use, and just show using, a date.

Moreover, if we open the gates here we probably need to reference django.utils.dateparse.parse_date(), and give examples of the kinds of values that are acceptable, and then maybe expand DateField docs to leak some of that info too — which is all implementation details. I'm not at all sure it makes anything clearer for the majority of readers.

Nonetheless, if you want to suggest a concise edit, we can consider.

I hope that makes sense.


Note: See TracTickets for help on using tickets.
Back to Top