The project template's URLconf doesn't follow the docs' convention for include()

[Daniele Procida]

• 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.

[Bas Peschier]

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.

[Marten Kenbeek]

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.

[Daniele Procida]

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

[Tim Graham <timograham@…>]

In 179fbab7:

Fixed #25711 -- Updated the project template's include() example.

Referencing URLs by dotted path is a stronger convention than
importing the URLs.

[Tim Graham <timograham@…>]

In 2c6624a:

[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

[Tim Graham <timograham@…>]

In 4211f8c9:

[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