Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#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

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 Changed 5 years ago by Daniele Procida

Owner: changed from nobody to Daniele Procida
Status: newassigned

comment:2 Changed 5 years ago by 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.

comment:3 Changed 5 years ago by Marten Kenbeek

Summary: django.conf.urls.include() documentation should be more consistentThe project template's URLconf doesn't follow the docs' convention for include()
Triage Stage: UnreviewedAccepted
Type: UncategorizedBug

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.

comment:4 Changed 5 years ago by 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

comment:5 Changed 5 years ago by Tim Graham <timograham@…>

Resolution: fixed
Status: assignedclosed

In 179fbab7:

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

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

comment:6 Changed 5 years ago by 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

comment:7 Changed 5 years ago by 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

Note: See TracTickets for help on using tickets.
Back to Top