#25711 closed Bug (fixed)
The project template's URLconf doesn't follow the docs' convention for include()
Reported by: | Daniele Procida | Owned by: | Daniele Procida |
---|---|---|---|
Component: | Documentation | Version: | 1.8 |
Severity: | Normal | Keywords: | |
Cc: | Triage Stage: | Accepted | |
Has patch: | no | Needs documentation: | no |
Needs tests: | no | Patch needs improvement: | no |
Easy pickings: | no | UI/UX: | no |
Description
- 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.
Change History (7)
comment:1 by , 9 years ago
Owner: | changed from | to
---|---|
Status: | new → assigned |
comment:2 by , 9 years ago
comment:3 by , 9 years ago
Summary: | django.conf.urls.include() documentation should be more consistent → The project template's URLconf doesn't follow the docs' convention for include() |
---|---|
Triage Stage: | Unreviewed → Accepted |
Type: | Uncategorized → Bug |
Consistency is good, but keep in mind that there are actually three ways to include urls:
- A dotted string:
include('polls.urls')
- A module containing an
url_patterns
attribute:from polls import urls; include(urls)
- 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.
comment:4 by , 9 years ago
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
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.