#27617: Better ORM internals documentation
-------------------------------------+-------------------------------------
Reporter: Mads | Owner: nobody
Jensen |
Type: | Status: new
Uncategorized |
Component: Database | Version: 1.10
layer (models, ORM) | Keywords: documentation
Severity: Normal | internals
Triage Stage: | Has patch: 0
Unreviewed |
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
-------------------------------------+-------------------------------------
Overall, Django's documentation is quite good for the average user, and it
also covers topics on how to write custom aggregate-functions and
expressions, custom lookups and more. However, documentation on how the
ORM works internally is mostly something that can be achieved through
talks from YouTube, and from reading the code (albeit, there are some
comments, and IDE tools letting you jump between symbols and methods do
help) this takes time.
Something more elaborate on the compilers would be nice
(`SQLInsertCompiler`, `SQLDeleteCompiler`, `SQLAggregateCompiler`,
`SQLDeleteCompiler`, `SQLCompiler`), and structures such as `PathInfo` are
missing, the different methods in Query, and how Query in the
`django.db.models.models` and `django.db.models.sql.query`, as well as the
chain of calls that are called to generate and optimize the code/query.
The structure of a backend and what files that are necessary is also a bit
absent. It's a bit tricky to see where this would fit into the current
documentation structure, but it would augment Django a lot. In
https://docs.djangoproject.com/en/dev/howto/custom-lookups/ there's a
comment about the compiler.
SQLalchemy outlines the structure of its architecture in a chapter in
Architecture of Open Source Applications:
http://aosabook.org/en/sqlalchemy.html My requests aims at providing a bit
of this in some form.
Talks on YouTube that were helpful in getting some idea on how the ORM
works. Since the ORM was built for relational databases, this is also the
scope of this documentation request.
1. https://www.youtube.com/watch?v=CGF-0csOjPwa
2. https://opbeat.com/community/posts/expressions-by-josh-smeaton/
3. https://www.youtube.com/watch?v=OCq2eUmrCfI
--
Ticket URL: <https://code.djangoproject.com/ticket/27617>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/053.2a053dc85cb4f0a61d4d51be904258eb%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
