[Django] #27587: str(QuerySet.query) should be documented

[Django]

#27587: str(QuerySet.query) should be documented
------------------------------------------+------------------------
Reporter: Peter Inglesby | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.10
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------+------------------------
As far as I can tell, the only place where the behaviour of
`str(QuerySet.query)` is mentioned in the docs is as a throwaway comment
in [https://docs.djangoproject.com/en/1.10/topics/db/aggregation/ the
aggregation topic], and in a code example in
[https://docs.djangoproject.com/en/1.10/ref/contrib/gis/tutorial/ the
GeoDjango tutorial].

This is very useful behaviour but it is not widely known. Additionally,
its limitations (see ticket:12611, "Incorrect quoting in
QuerySet.query.__str__()") are even less widely known.

I think it would be suitable to add this to
[https://docs.djangoproject.com/en/1.10/intro/tutorial02/ section 2 of the
tutorial], and to the
[https://docs.djangoproject.com/en/1.10/topics/db/queries/ Making queries
topic guide].

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

[Django]

#27587: str(QuerySet.query) should be documented

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

Reporter: Peter Inglesby | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0

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

Comment (by Aymeric Augustin):

Regarding the limitations, I don't think we should accept the current
status quo as the best we can do:

1. if it's reasonably easy to perform the escaping correctly, typically
just by escaping arguments with a function provided by the database
adapter prior to interpolation, then Django should do it.
2. if there's no function for escaping arguments, but a well documented
and not too complicated process do to so (replace " by "" then wrap in
"...") then we should consider doing it as well
3. if the escaping rules are unclear and there's no way to ask the
database to do it, then we should return something that is *obviously*
invalid, like QUERY = ... ; PARAMS = ...

I did that some time ago for `last_executed_query`. SQLite stayed at 3 for
half a decade before moving to 2.

I believe the same logic should apply to QuerySet.query and similar
methods.

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

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------
Changes (by Tim Graham):

* stage: Unreviewed => Accepted
* type: Uncategorized => Cleanup/optimization
* easy: 1 => 0

Comment:

Another place to document it is `docs/ref/models/querysets.txt`.

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

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Comment (by Mads Jensen):

[https://github.com/django/django/pull/7789 PR]

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

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Mads Jensen):

* has_patch: 0 => 1

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

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

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

Changes (by Tim Graham):

* needs_better_patch: 0 => 1

Comment:

The current limitations described in this ticket and in #18631 should also
be mentioned.

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

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
--------------------------------------+------------------------------------

Changes (by Mads Jensen):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:6>

[Django]

#27587: Document str(QuerySet.query)
--------------------------------------+------------------------------------

Reporter: Peter Inglesby | Owner: nobody

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

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

Changes (by Tim Graham):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:7>

[Django]

#27587: Document str(QuerySet.query)
-------------------------------------+-------------------------------------
Reporter: Peter Inglesby | Owner: JosiahDub
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by JosiahDub):

* owner: nobody => JosiahDub

* needs_better_patch: 1 => 0

* has_patch: 1 => 0
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:8>

[Django]

#27587: Document str(QuerySet.query)
-------------------------------------+-------------------------------------
Reporter: Peter Inglesby | Owner: JosiahDub
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Carlton Gibson):

* needs_better_patch: 0 => 1

Comment:

Docs patch looks good. Small comments on PR.

I recall related work to improve the output of `str(qs.query)` — by having
the backend do the quoting — but I'm not 100% sure how far that got. This
matters for the ''it's not great'' disclaimer, and whether we want to
close this as completed (or not) on merge? 🤔

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:9>

[Django]

#27587: Document str(QuerySet.query)
-------------------------------------+-------------------------------------
Reporter: Peter Inglesby | Owner: JosiahDub
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 1.10

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

Changes (by Jacob Walls):

* has_patch: 0 => 1

Comment:

[https://github.com/django/django/pull/16200 PR]

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:10>

[Django]

#27587: Document str(QuerySet.query)
-------------------------------------+-------------------------------------
Reporter: Peter Inglesby | Owner: JosiahDub
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Michael Howitz):

* needs_better_patch: 1 => 0

Comment:

The [https://github.com/django/django/pull/16200 PR] is an improvement
over what is currently there, so why not merge it?

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:11>

[Django]

#27587: Document str(QuerySet.query)
-------------------------------------+-------------------------------------
Reporter: Peter Inglesby | Owner: JosiahDub
Type: | Status: assigned
Cleanup/optimization |

Component: Documentation | Version: 1.10

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

Changes (by Mariusz Felisiak):

* needs_better_patch: 0 => 1

Comment:

Have you checked comments on the latest PR? We cannot merge this as
`.query` is not something that we can recommend to users without fixing
#25705.

--
Ticket URL: <https://code.djangoproject.com/ticket/27587#comment:12>