Why do some includes in Django need strings, and others variable names?

Question

Referring to the Django Book, chapter 3:

from django.conf.urls import patterns, include, url

# Uncomment the next two lines to enable the admin:
# from django.contrib import admin
# admin.autodiscover()

urlpatterns = patterns('',
    # Examples:
    # url(r'^$', 'mysite.views.home', name='home'),
    # url(r'^mysite/', include('mysite.foo.urls')),
    # url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
    # url(r'^admin/', include(admin.site.urls)),
)

What determines why one thing is included as a string, and another as regular variable? Why admin.site.urls but not 'admin.site.urls'? All other includes are included as strings... I see no logical pattern here.

Answer 1

First of all, the first pattern ('mysite.views.home' -> a view function) is deprecated in 1.8: it led to all kinds of trouble.

As for the rest, it generally works both. 'mysite.foo.urls' is resolved to include the patterns in the module mysite.foo.urls, but from mysite.foo import urls as foo_urls; include(foo_urls) works as well. The string-based imports are mostly a historical artifact that hasn't been removed, but it is convenient and doesn't have any real drawbacks as the module is immediately imported (and thus, any ImportError is easily traceable to the url config).

admin.site.urls is different, because admin.site.urls is not a module, but site is an object and urls is an attribute. For that reason, string-based imports of admin.site.urls won't work, and you have to use the second method.

As a last note, the warning at the beginning of the Django Book, stating that it is extremely out of date, is outdated. More up-to-date resources, such as the official documentation (one of the best official documentations I know), would be preferable.

Answer 2

If you're passing to include() a list of url() instances, then you don't use a string (see Include() docs and Including other URLconfs docs). In your admin urls example, admin.site.urls refers to a list of url instances. See the get_urls method in the source code (which provides the list of url instances referred to by admin.site.urls).

def get_urls(self):
    ...
    # Admin-site-wide views.
    urlpatterns = [
        url(r'^$', wrap(self.index), name='index'),
        url(r'^login/$', self.login, name='login'),
        url(r'^logout/$', wrap(self.logout), name='logout'),
        url(r'^password_change/$', wrap(self.password_change, cacheable=True), name='password_change'),
        url(r'^password_change/done/$', wrap(self.password_change_done, cacheable=True),
            name='password_change_done'),
        url(r'^jsi18n/$', wrap(self.i18n_javascript, cacheable=True), name='jsi18n'),
        url(r'^r/(?P<content_type_id>\d+)/(?P<object_id>.+)/$', wrap(contenttype_views.shortcut),
            name='view_on_site'),
    ]