[Django] #25711: django.conf.urls.include() documentation should be more consistent
Django
-------------------------------+--------------------
Reporter: EvilDMP | Owner: nobody
Type: Uncategorized | Status: new
Component: Documentation | Version: 1.8
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+--------------------
* in the tutorial https://docs.djangoproject.com/en/dev/intro/tutorial01
/#write-your-first-view we advise to use `include('polls.urls'))`
* in the default project template
https://github.com/django/django/blob/master/django/conf/project_template/project_name/urls.py#L12-L15
we advise to import the module and use `url(r'^blog/',
include(blog_urls))`
* in https://docs.djangoproject.com/en/dev/topics/http/urls/#including-
other-urlconfs we have examples of both - even in the same file
I think that we need to be more consistent and clearer about this.
For the tutorial and the default `urls.py` I like the use of a dotted
string rather than an import; it's one less thing to do.
Other than that, should we generally prefer one style over another? I can
imagine that a dotted string might sometimes help avoid a circular import
or have related advantages, but otherwise they seem to behave in just the
same way.
--
Ticket URL: <https://code.djangoproject.com/ticket/25711>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: EvilDMP | Owner: EvilDMP
Type: Uncategorized | Status: assigned
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
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 EvilDMP):
* status: new => assigned
* needs_docs: => 0
* owner: nobody => EvilDMP
* needs_tests: => 0
* needs_better_patch: => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:1>
Django
Reporter: EvilDMP | Owner: EvilDMP
Type: Uncategorized | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by bpeschier):
For reference: https://docs.djangoproject.com/en/1.8/releases/1.8/#django-
conf-urls-patterns
This is the argument made in 1.8 encouraging people to import **views**.
Unless there is a strong argument (or multiple!) against advising people
to do the same for includes, I think it would be consistent to advise
importing over dotted strings.
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:2>
Django
include()
-------------------------------+------------------------------------
Reporter: EvilDMP | Owner: EvilDMP
Type: Bug | Status: assigned
Component: Documentation | Version: 1.8
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by knbk):
* type: Uncategorized => Bug
* stage: Unreviewed => Accepted
Comment:
Consistency is good, but keep in mind that there are actually three ways
to include urls:
1. A dotted string: `include('polls.urls')`
2. A module containing an `url_patterns` attribute: `from polls import
urls; include(urls)`
3. A list containing patterns: `from polls.urls import url_patterns;
include(url_patterns)`
Method 3 is only ever used to include a list of patterns that's defined in
the same file. Other than that, method 1 is used consistently in all but
the default project template, where it was added in #24635. The ticket
only mentions the dotted view path, but the patch also changes the example
for include.
The convention in the docs is to use a dotted path to include other
URLconf files. In that light, the change in #24635 is simply overzealous
and the current description in the project template is a bug.
I don't think the convention should be changed from method 1 to method 2.
If you'd like to discuss this, I think we should do so on the mailing
list.
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:3>
Django
include()
-------------------------------+------------------------------------
Reporter: EvilDMP | Owner: EvilDMP
Type: Bug | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by EvilDMP):
You're right, it is consistent when it comes to the docs (at least I can't
find the example I thought I was looking at, or I just misread it in the
first place).
It should be explained though:
* ''why'' the dotted string is preferred over e.g. `from polls import
urls; include(urls)`
* when if ever it would be better to use an imported module rather than a
dotted string
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:4>
Django
include()
-------------------------------+------------------------------------
Reporter: EvilDMP | Owner: EvilDMP
Component: Documentation | Version: 1.8
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"179fbab7e05946b59ec9815d6e9b1901826ed610" 179fbab7]:
{{{
#!CommitTicketReference repository=""
revision="179fbab7e05946b59ec9815d6e9b1901826ed610"
Fixed #25711 -- Updated the project template's include() example.
Referencing URLs by dotted path is a stronger convention than
importing the URLs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:5>
Django
include()
-------------------------------+------------------------------------
Reporter: EvilDMP | Owner: EvilDMP
Type: Bug | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"2c6624a67397afc0f72a36559b53fb693e473bbc" 2c6624a]:
{{{
#!CommitTicketReference repository=""
revision="2c6624a67397afc0f72a36559b53fb693e473bbc"
[1.9.x] Fixed #25711 -- Updated the project template's include() example.
Referencing URLs by dotted path is a stronger convention than
importing the URLs.
Backport of 179fbab7e05946b59ec9815d6e9b1901826ed610 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:6>
Django
include()
-------------------------------+------------------------------------
Reporter: EvilDMP | Owner: EvilDMP
Type: Bug | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"4211f8c9d1cd543d9c6fe4b789aea7dddf07c44a" 4211f8c9]:
{{{
#!CommitTicketReference repository=""
revision="4211f8c9d1cd543d9c6fe4b789aea7dddf07c44a"
[1.8.x] Fixed #25711 -- Updated the project template's include() example.
Referencing URLs by dotted path is a stronger convention than
importing the URLs.
Backport of 179fbab7e05946b59ec9815d6e9b1901826ed610 from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/25711#comment:7>