[Django] #27936: ASCII Art for docs "Spanning multi-valued relationships"
Django
------------------------------------------+------------------------
Reporter: Thomas Güttler | 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: 0
UI/UX: 0 |
------------------------------------------+------------------------
First of all: Thank you for the great docs.
Since it took some time until we got the difference:
{{{
filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)
vs
filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)
}}}
The docs are great:
https://docs.djangoproject.com/en/dev/topics/db/queries/#spanning-multi-
valued-relationships
But maybe the ascii art below helps to understand it better?
What do you think?
{{{
+--------------------+
| Lennon |
- | Entry 1 |
+---------------+ / | 2008 |
| | / +--------------------+
| Blog 1 |/
filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)
| |\ -
+---------------+ \ -
\ +--------------------+
\ | |
-| Entry 2 |
| |
+--------------------+
+--------------------+
| Lennon |
- | Entry 3 |
+---------------+ / | |
| | / +--------------------+
| Blog 2 |/
filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)
| |\
+---------------+ \ -
\ +--------------------+
\ | 2008 |
-| Entry 4 |
| |
+--------------------+
}}}
Ascii Art: https://textik.com/#100375b764993664
The ascii art could get improved, I wanted to ask you first before
polishing it.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: Thomas Güttler | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.10
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Josh Smeaton):
I think there's definitely scope to improve the docs around multi valued
relationships, but I don't think ASCII art (or that diagram) is really the
right way of doing it. For some added confusion, the docs fail to mention
that duplicates are possible with the second query (with multiple filters)
if there is an entry with the headline Lennon AND it was posted in 2008.
It seems the docs go through a lot of effort to avoid mentioning that a
second filter causes the query to create a second join to the same table.
I'm not proposing new language for this myself, but I've seen many an
experienced developer get caught by this without understanding what was
actually happening with the underlying query. I'd very much like to see
these docs improved in some way.
Here's some shell output for those curious about what's happening:
{{{
In [1]: from datetime import date
In [2]: d2008 = date(2008, 6, 6)
In [3]: d2009 = date(2009, 6, 6)
In [4]: both = Blog.objects.create(name='Match Both')
In [5]: Entry.objects.create(blog=both, headline='1 Lennon 1',
body_text='body', pub_date=d2008)
Out[5]: <Entry: Entry object>
In [6]: Entry.objects.create(blog=both, headline='2 Lennon 2',
body_text='body', pub_date=d2009)
Out[6]: <Entry: Entry object>
In [7]: Entry.objects.create(blog=both, headline='3 Blah 3',
body_text='body', pub_date=d2008)
Out[7]: <Entry: Entry object>
In [8]: Blog.objects.filter(entry__headline__contains='Lennon',
entry__pub_date__year=2008)
Out[8]: <QuerySet [<Blog: Match Both>]>
In [9]: justdate = Blog.objects.create(name='Match Date Only')
In [10]: Entry.objects.create(blog=justdate, headline='4 Blah 4',
body_text='body', pub_date=d2008)
Out[10]: <Entry: Entry object>
In [11]: justheadline = Blog.objects.create(name='Match Headline Only')
In [12]: Entry.objects.create(blog=justheadline, headline='5 Lennon 5',
body_text='body', pub_date=d2009)
Out[12]: <Entry: Entry object>
In [13]: Blog.objects.filter(entry__headline__contains='Lennon',
entry__pub_date__year=2008)
Out[13]: <QuerySet [<Blog: Match Both>]>
In [14]:
Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)
Out[14]: <QuerySet [<Blog: Match Both>, <Blog: Match Both>, <Blog: Match
Both>, <Blog: Match Both>]>
}}}
And the queries:
{{{
# Blog.objects.filter(entry__headline__contains='Lennon',
entry__pub_date__year=2008)
SELECT
"scratch_blog"."id",
"scratch_blog"."name",
"scratch_blog"."tagline"
FROM "scratch_blog"
INNER JOIN "scratch_entry" ON ("scratch_blog"."id" =
"scratch_entry"."blog_id")
WHERE (
"scratch_entry"."pub_date" BETWEEN '2008-01-01' :: DATE AND '2008-12-31'
:: DATE)
AND "scratch_entry"."headline" LIKE '%Lennon%'
);
#
Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)
SELECT
"scratch_blog"."id",
"scratch_blog"."name",
"scratch_blog"."tagline"
FROM "scratch_blog"
INNER JOIN "scratch_entry" ON ("scratch_blog"."id" =
"scratch_entry"."blog_id")
INNER JOIN "scratch_entry" T3 ON ("scratch_blog"."id" = T3."blog_id")
WHERE (
"scratch_entry"."headline" LIKE '%Lennon%'
AND T3."pub_date" BETWEEN '2008-01-01'::date AND '2008-12-31'::Date)
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:1>
Django
Reporter: Thomas Güttler | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.10
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by TZanke):
* cc: tzanke@… (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:2>
Django
--------------------------------------+------------------------------------
Reporter: Thomas Güttler | Owner: nobody
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):
* type: Uncategorized => Cleanup/optimization
* stage: Unreviewed => Accepted
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:3>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
Replying to [comment:1 Josh Smeaton]:
> I think there's definitely scope to improve the docs around multi valued
relationships, but I don't think ASCII art (or that diagram) is really the
right way of doing it. For some added confusion, the docs fail to mention
that duplicates are possible with the second query (with multiple filters)
if there is an entry with the headline Lennon AND it was posted in 2008.
It seems the docs go through a lot of effort to avoid mentioning that a
second filter causes the query to create a second join to the same table.
Hi Josh,
I think your proposal to change the docs are valid.
This issue is about the ascii art.
Why not open a new issue for your proposal?
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:4>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham):
I don't think there would be consensus to use ASCII art in the Django
documentation. If you think some diagram might be helpful (even though
Josh said he didn't think the diagram is the right way to clarify the
situation), please follow the pattern used by
[https://docs.djangoproject.com/en/dev/_images/triage_process.svg existing
images]. For simplicity, I retitled this ticket rather than closing it and
creating a new one.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:5>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
Yes, you are right. the ASCII art is not a perfect solution.
If I would provide a SVG diagram instead of the ascii art, would you
include it into the docs?
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:6>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham):
I agree with Josh that a diagram probably isn't the best way to clarify
things. The " To select all blogs" sentences seem clear to me but perhaps
you can help state them more clearly if you found them confusing.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:7>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
Experts like you are, don't need a diagram.
Last weekend I taught 32 people the joy of python programming who had few
or no experience with this language. I do this yearly since about 13
years.
Trust me, this helps to see the IT world from a different perspective.
My goal is to make software development newbee friendly.
I think a diagram like this would help.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:8>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham):
Diagrams are used sparsely because they are more difficult to maintain. I
don't think the diagram offers advantages compared to an example shell
session that creates objects, runs queries, and shows the results.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:9>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
Yes, now I see. The real problem is that diagrams are hard to maintain. If
maintaining them would be easier, then there would be more.
There are several extensions for sphinx which could be used (I needed to
remove a link to the sphinx plugin overview page, otherwise trac thinks my
post is spam)
But this gets off topic for this particular issue.
Tim, what do you think?
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:10>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham):
I'm not convinced that a diagram is advantageous for this but if you want
to create one, you can get other opinions on the DevelopersMailingList.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:11>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: 1.10
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
Yes, know I think I understood you. The real problem is that diagrams are
hard to maintain.
If maintaining them would be easier, then there would be more diagrams.
The problem is the media break between human editable ascii (which we all
love) and some svg which looks like some binary randomly encoded to xml.
There are several extensions for sphinx which could be used: http://www
.sphinx-doc.org/en/stable/develop.html
But this gets off topic for this particular issue.
Tim, what do you think?
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:12>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Simon Charette):
* cc: Simon Charette (added)
* version: 1.10 => master
Comment:
Given how often the multi-valued `filter()` chaining behavior is reported
as a bug I think this might be worth a shot.
I'm not a big fan of diagrams either and I think a simplified shell
session would be a good step forward. I guess mixing both is also an
option.
If we really want to go with graphs I'd suggest we use the [http://www
.sphinx-doc.org/en/master/ext/graphviz.html#module-sphinx.ext.graphviz the
Graphiz extension] which makes it easy to maintain, generate SVGs, and
should be flexible enough to express the previously mentioned ASCII graph.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:13>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Thomas Güttler):
I personnaly prefer the ascii art (https://textik.com/#100375b764993664)
but with graphiz you can do much more. But on the other hand the
ascii art is straight forward. It is WYSIWYG :-)
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:14>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Josh Smeaton):
My objection was not to any diagram, but to that one specifically. I think
the right diagram definitely would help, but it should clearly show items
that match and items that don't match for each query type, perhaps with
colors. Bonus points if it's able to call out the duplicates problem, but
that could be documented separately.
I don't personally mind which technology choice is used.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:15>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Adam (Chainz) Johnson):
Coming here from django-developers post
I side with Josh that the proposed diagram probably isn't the best, and if
we were to include one, another could explain the problem better. I find
the existing text fairly clear - I've forgotten and re-learned this
distinction from the docs a few times.
On technology, graphviz isn't the most flexible as it can only do graphs.
Other diagrams we might add to the docs in future might need more
flexibility, so I think SVG is a better choice. There's nothing stopping
the first version of an SVG diagram being generated with graphviz.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:16>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Claude Paroz):
WRT the format, +1 for SVG, but *clean* SVG if possible for better
maintainership. The SVG syntax of the OmniGraffle-generated ones is awful.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:17>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Zach Borboa):
* cc: Zach Borboa (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:18>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by TZanke):
* cc: TZanke (added)
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:19>
Django
--------------------------------------+------------------------------------
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by TZanke):
* cc: TZanke (removed)
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:20>
Django
Reporter: Thomas Güttler | Owner: Jacob
Type: | Walls
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Jacob Walls):
* owner: nobody => Jacob Walls
* status: new => assigned
Comment:
I linked to this doc in the release note I wrote for #16063. I think the
main flaw of the doc is it's a bit wordy. It starts with examples, but
sort of hypothetically, then discusses the implementation, then does
concrete examples. Could be streamlined. Use the saved space to discuss
duplicates and joins (that's where I could see the shell session coming
in). I'll try to give it a go.
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:19>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner: Jacob
Type: | Walls
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Jacob Walls):
* has_patch: 0 => 1
Comment:
[https://github.com/django/django/pull/15236 PR]
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:20>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner: Jacob
Type: | Walls
Cleanup/optimization | Status: assigned
Component: Documentation | Version: dev
Severity: Normal | Resolution:
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak):
* stage: Accepted => Ready for checkin
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:21>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner: Jacob
Type: | Walls
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Mariusz Felisiak <felisiak.mariusz@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"6174814dbe04fb6668aa212a6cdbca765a8b0522" 6174814d]:
{{{
#!CommitTicketReference repository=""
revision="6174814dbe04fb6668aa212a6cdbca765a8b0522"
Fixed #27936 -- Rewrote spanning multi-valued relationships docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:22>
Django
-------------------------------------+-------------------------------------
Reporter: Thomas Güttler | Owner: Jacob
Type: | Walls
Cleanup/optimization | Status: closed
Component: Documentation | Version: dev
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):
In [changeset:"c46e996307b58439eb82343356129a1b971d05ee" c46e996]:
{{{
#!CommitTicketReference repository=""
revision="c46e996307b58439eb82343356129a1b971d05ee"
[4.0.x] Fixed #27936 -- Rewrote spanning multi-valued relationships docs.
Backport of 6174814dbe04fb6668aa212a6cdbca765a8b0522 from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/27936#comment:23>