Commit c852d456 authored by Tim Graham's avatar Tim Graham
Browse files

Fixed #20204 - Consistent usage of url() in URL dispatcher documentation 

Thanks Baptiste Mispelon for the patch and dave.lampton@ for the suggestion.
parent 68d6c52e

docs/topics/http/urls.txt

+66 −63
Original line number Diff line number Diff line
@@ -66,13 +66,13 @@ Example 


Here's a sample URLconf::



    from django.conf.urls import patterns

    from django.conf.urls import patterns, url



    urlpatterns = patterns('',

        (r'^articles/2003/$', 'news.views.special_case_2003'),

        (r'^articles/(\d{4})/$', 'news.views.year_archive'),

        (r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'),

        (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),

        url(r'^articles/2003/$', 'news.views.special_case_2003'),

        url(r'^articles/(\d{4})/$', 'news.views.year_archive'),

        url(r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'),

        url(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),

    )



Notes:
@@ -124,10 +124,10 @@ is ``(?P<name>pattern)``, where ``name`` is the name of the group and 
Here's the above example URLconf, rewritten to use named groups::



    urlpatterns = patterns('',

        (r'^articles/2003/$', 'news.views.special_case_2003'),

        (r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),

        (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive'),

        (r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d{2})/$', 'news.views.article_detail'),

        url(r'^articles/2003/$', 'news.views.special_case_2003'),

        url(r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),

        url(r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/$', 'news.views.month_archive'),

        url(r'^articles/(?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d{2})/$', 'news.views.article_detail'),

    )



This accomplishes exactly the same thing as the previous example, with one
@@ -183,7 +183,7 @@ Each captured argument is sent to the view as a plain Python string, regardless 
of what sort of match the regular expression makes. For example, in this

URLconf line::



    (r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),

    url(r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),



...the ``year`` argument to ``news.views.year_archive()`` will be a string, not

an integer, even though the ``\d{4}`` will only match integer strings.
@@ -193,13 +193,14 @@ Here's an example URLconf and view:: 


    # URLconf

    urlpatterns = patterns('',

        (r'^blog/$', 'blog.views.page'),

        (r'^blog/page(?P<num>\d+)/$', 'blog.views.page'),

        url(r'^blog/$', 'blog.views.page'),

        url(r'^blog/page(?P<num>\d+)/$', 'blog.views.page'),

    )



    # View (in blog/views.py)

    def page(request, num="1"):

        # Output the appropriate page of blog entries, according to num.

        ...



In the above example, both URL patterns point to the same view --

``blog.views.page`` -- but the first pattern doesn't capture anything from the
@@ -255,12 +256,12 @@ code duplication. 


Here's the example URLconf from the :doc:`Django overview </intro/overview>`::



    from django.conf.urls import patterns

    from django.conf.urls import patterns, url



    urlpatterns = patterns('',

        (r'^articles/(\d{4})/$', 'news.views.year_archive'),

        (r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'),

        (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),

        url(r'^articles/(\d{4})/$', 'news.views.year_archive'),

        url(r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'),

        url(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'),

    )



In this example, each view has a common prefix -- ``'news.views'``.
@@ -270,12 +271,12 @@ each view function. 


With this in mind, the above example can be written more concisely as::



    from django.conf.urls import patterns

    from django.conf.urls import patterns, url



    urlpatterns = patterns('news.views',

        (r'^articles/(\d{4})/$', 'year_archive'),

        (r'^articles/(\d{4})/(\d{2})/$', 'month_archive'),

        (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'article_detail'),

        url(r'^articles/(\d{4})/$', 'year_archive'),

        url(r'^articles/(\d{4})/(\d{2})/$', 'month_archive'),

        url(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'article_detail'),

    )



Note that you don't put a trailing dot (``"."``) in the prefix. Django puts
@@ -291,25 +292,25 @@ Just add multiple ``patterns()`` objects together, like this: 


Old::



    from django.conf.urls import patterns

    from django.conf.urls import patterns, url



    urlpatterns = patterns('',

        (r'^$', 'myapp.views.app_index'),

        (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'myapp.views.month_display'),

        (r'^tag/(?P<tag>\w+)/$', 'weblog.views.tag'),

        url(r'^$', 'myapp.views.app_index'),

        url(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'myapp.views.month_display'),

        url(r'^tag/(?P<tag>\w+)/$', 'weblog.views.tag'),

    )



New::



    from django.conf.urls import patterns

    from django.conf.urls import patterns, url



    urlpatterns = patterns('myapp.views',

        (r'^$', 'app_index'),

        (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$','month_display'),

        url(r'^$', 'app_index'),

        url(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$','month_display'),

    )



    urlpatterns += patterns('weblog.views',

        (r'^tag/(?P<tag>\w+)/$', 'tag'),

        url(r'^tag/(?P<tag>\w+)/$', 'tag'),

    )



.. _including-other-urlconfs:
@@ -323,13 +324,13 @@ essentially "roots" a set of URLs below other ones. 
For example, here's an excerpt of the URLconf for the `Django Web site`_

itself. It includes a number of other URLconfs::



    from django.conf.urls import patterns, include

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



    urlpatterns = patterns('',

        # ... snip ...

        (r'^comments/', include('django.contrib.comments.urls')),

        (r'^community/', include('django_website.aggregator.urls')),

        (r'^contact/', include('django_website.contact.urls')),

        url(r'^comments/', include('django.contrib.comments.urls')),

        url(r'^community/', include('django_website.aggregator.urls')),

        url(r'^contact/', include('django_website.contact.urls')),

        # ... snip ...

    )
@@ -344,7 +345,7 @@ URLconf Python module defining them as the ``include()`` argument but by using 
directly the pattern list as returned by :func:`~django.conf.urls.patterns`

instead. For example, consider this URLconf::



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

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



    extra_patterns = patterns('',

        url(r'^reports/(?P<id>\d+)/$', 'credit.views.report'),
@@ -353,8 +354,8 @@ instead. For example, consider this URLconf:: 


    urlpatterns = patterns('',

        url(r'^$', 'apps.main.views.homepage'),

        (r'^help/', include('apps.help.urls')),

        (r'^credit/', include(extra_patterns)),

        url(r'^help/', include('apps.help.urls')),

        url(r'^credit/', include(extra_patterns)),

    )



In this example, the ``/credit/reports/`` URL will be handled by the
@@ -370,13 +371,13 @@ the following example is valid:: 


    # In settings/urls/main.py

    urlpatterns = patterns('',

        (r'^(?P<username>\w+)/blog/', include('foo.urls.blog')),

        url(r'^(?P<username>\w+)/blog/', include('foo.urls.blog')),

    )



    # In foo/urls/blog.py

    urlpatterns = patterns('foo.views',

        (r'^$', 'blog.index'),

        (r'^archive/$', 'blog.archive'),

        url(r'^$', 'blog.index'),

        url(r'^archive/$', 'blog.archive'),

    )



In the above example, the captured ``"username"`` variable is passed to the
@@ -390,13 +391,14 @@ Passing extra options to view functions 
URLconfs have a hook that lets you pass extra arguments to your view functions,

as a Python dictionary.



Any URLconf tuple can have an optional third element, which should be a

dictionary of extra keyword arguments to pass to the view function.

The :func:`django.conf.urls.url` function can take an optional third argument

which should be a dictionary of extra keyword arguments to pass to the view

function.



For example::



    urlpatterns = patterns('blog.views',

        (r'^blog/(?P<year>\d{4})/$', 'year_archive', {'foo': 'bar'}),

        url(r'^blog/(?P<year>\d{4})/$', 'year_archive', {'foo': 'bar'}),

    )



In this example, for a request to ``/blog/2005/``, Django will call
@@ -426,26 +428,26 @@ Set one:: 


    # main.py

    urlpatterns = patterns('',

        (r'^blog/', include('inner'), {'blogid': 3}),

        url(r'^blog/', include('inner'), {'blogid': 3}),

    )



    # inner.py

    urlpatterns = patterns('',

        (r'^archive/$', 'mysite.views.archive'),

        (r'^about/$', 'mysite.views.about'),

        url(r'^archive/$', 'mysite.views.archive'),

        url(r'^about/$', 'mysite.views.about'),

    )



Set two::



    # main.py

    urlpatterns = patterns('',

        (r'^blog/', include('inner')),

        url(r'^blog/', include('inner')),

    )



    # inner.py

    urlpatterns = patterns('',

        (r'^archive/$', 'mysite.views.archive', {'blogid': 3}),

        (r'^about/$', 'mysite.views.about', {'blogid': 3}),

        url(r'^archive/$', 'mysite.views.archive', {'blogid': 3}),

        url(r'^about/$', 'mysite.views.about', {'blogid': 3}),

    )



Note that extra options will *always* be passed to *every* line in the included
@@ -463,9 +465,9 @@ supported -- you can pass any callable object as the view. 
For example, given this URLconf in "string" notation::



    urlpatterns = patterns('',

        (r'^archive/$', 'mysite.views.archive'),

        (r'^about/$', 'mysite.views.about'),

        (r'^contact/$', 'mysite.views.contact'),

        url(r'^archive/$', 'mysite.views.archive'),

        url(r'^about/$', 'mysite.views.about'),

        url(r'^contact/$', 'mysite.views.contact'),

    )



You can accomplish the same thing by passing objects rather than strings. Just
@@ -474,9 +476,9 @@ be sure to import the objects:: 
    from mysite.views import archive, about, contact



    urlpatterns = patterns('',

        (r'^archive/$', archive),

        (r'^about/$', about),

        (r'^contact/$', contact),

        url(r'^archive/$', archive),

        url(r'^about/$', about),

        url(r'^contact/$', contact),

    )



The following example is functionally identical. It's just a bit more compact
@@ -486,9 +488,9 @@ each view individually:: 
    from mysite import views



    urlpatterns = patterns('',

        (r'^archive/$', views.archive),

        (r'^about/$', views.about),

        (r'^contact/$', views.contact),

        url(r'^archive/$', views.archive),

        url(r'^about/$', views.about),

        url(r'^contact/$', views.contact),

    )



The style you use is up to you.
@@ -502,7 +504,7 @@ imported:: 
    from mysite.views import ClassBasedView



    urlpatterns = patterns('',

        (r'^myview/$', ClassBasedView.as_view()),

        url(r'^myview/$', ClassBasedView.as_view()),

    )



Reverse resolution of URLs
@@ -611,8 +613,8 @@ your URLconf. For example, these two URL patterns both point to the ``archive`` 
view::



    urlpatterns = patterns('',

        (r'^archive/(\d{4})/$', archive),

        (r'^archive-summary/(\d{4})/$', archive, {'summary': True}),

        url(r'^archive/(\d{4})/$', archive),

        url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}),

    )



This is completely valid, but it leads to problems when you try to do reverse
@@ -630,7 +632,7 @@ Here's the above example, rewritten to use named URL patterns:: 


    urlpatterns = patterns('',

        url(r'^archive/(\d{4})/$', archive, name="full-archive"),

        url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}, "arch-summary"),

        url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}, name="arch-summary"),

    )



With these names in place (``full-archive`` and ``arch-summary``), you can
@@ -642,7 +644,8 @@ target each pattern individually by using its name: 
    {% url 'full-archive' 2007 %}



Even though both URL patterns refer to the ``archive`` view here, using the

``name`` parameter to ``url()`` allows you to tell them apart in templates.

``name`` parameter to :func:`django.conf.urls.url` allows you to tell them

apart in templates.



The string used for the URL name can contain any characters you like. You are

not restricted to valid Python names.
@@ -785,7 +788,7 @@ Firstly, you can provide the :term:`application <application namespace>` and 
:func:`django.conf.urls.include()` when you construct your URL patterns. For

example,::



    (r'^help/', include('apps.help.urls', namespace='foo', app_name='bar')),

    url(r'^help/', include('apps.help.urls', namespace='foo', app_name='bar')),



This will include the URLs defined in ``apps.help.urls`` into the

:term:`application namespace` ``'bar'``, with the :term:`instance namespace`
@@ -805,7 +808,7 @@ For example:: 
        url(r'^advanced/$', 'apps.help.views.views.advanced'),

    )



    (r'^help/', include(help_patterns, 'bar', 'foo')),

    url(r'^help/', include(help_patterns, 'bar', 'foo')),



This will include the nominated URL patterns into the given application and

instance namespace.