[Django] #33484: Improve docs

Django

unread,

Feb 1, 2022, 1:20:05 PM2/1/22

to django-...@googlegroups.com

#33484: Improve docs
------------------------------------------------+------------------------
Reporter: MojixCoder | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 4.0
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 |
------------------------------------------------+------------------------
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
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 value instead of date?

Here is the
[link](https://docs.djangoproject.com/en/4.0/ref/models/querysets/#date)
in the docs.

--
Ticket URL: <https://code.djangoproject.com/ticket/33484>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

Django

unread,

Feb 1, 2022, 1:20:44 PM2/1/22

to django-...@googlegroups.com

-------------------------------------+-------------------------------------
Description changed by MojixCoder:

Old description:

> 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 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 value instead of date?
>
> Here is the
> [link](https://docs.djangoproject.com/en/4.0/ref/models/querysets/#date)
> in the docs.

New description:

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
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 value instead of date?

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

--

--
Ticket URL: <https://code.djangoproject.com/ticket/33484#comment:1>

Django

unread,

Feb 1, 2022, 1:21:46 PM2/1/22

to django-...@googlegroups.com

-------------------------------------+-------------------------------------
Description changed by MojixCoder:

Old description:

> 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 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 value instead of date?
>
> Here is the

> [https://docs.djangoproject.com/en/4.0/ref/models/querysets/#date] in the
> docs.

New description:

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
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 value instead of date?

Here is the

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

--

--
Ticket URL: <https://code.djangoproject.com/ticket/33484#comment:2>

Django

unread,

Feb 1, 2022, 1:23:37 PM2/1/22

to django-...@googlegroups.com

-------------------------------------+-------------------------------------
Description changed by MojixCoder:

Old description:

> 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 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 value instead of date?
>
> Here is the

> [https://docs.djangoproject.com/en/4.0/ref/models/querysets/#date] in the
> docs.

New description:

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 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.

--

--
Ticket URL: <https://code.djangoproject.com/ticket/33484#comment:3>

Django

unread,

Feb 1, 2022, 1:24:05 PM2/1/22

to django-...@googlegroups.com

#33484: Improve docs about date lookup filter
-------------------------------------+-------------------------------------
Reporter: MojixCoder | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 4.0
Severity: Normal | Resolution:

-------------------------------------+-------------------------------------

--
Ticket URL: <https://code.djangoproject.com/ticket/33484#comment:4>

Django

unread,

Feb 1, 2022, 1:26:10 PM2/1/22

to django-...@googlegroups.com

#33484: Improve docs about date lookup filter
-------------------------------------+-------------------------------------
Reporter: MojixCoder | Owner: nobody
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 4.0
Severity: Normal | Resolution:

-------------------------------------+-------------------------------------
Description changed by MojixCoder:

Old description:

> 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 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.

New description:

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.

--

--
Ticket URL: <https://code.djangoproject.com/ticket/33484#comment:5>

Django

unread,

Feb 2, 2022, 10:01:45 AM2/2/22

to django-...@googlegroups.com

#33484: Improve docs about date lookup filter
-------------------------------------+-------------------------------------
Reporter: MojixCoder | Owner: nobody
Type: | Status: closed
Cleanup/optimization |
Component: Documentation | Version: 4.0
Severity: Normal | Resolution: wontfix

-------------------------------------+-------------------------------------
Changes (by Carlton Gibson):

* status: new => closed
* resolution: => wontfix

Comment:

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.