diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 67a9b373ba..ce9a364d8e 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -67,13 +67,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: @@ -125,10 +125,10 @@ is ``(?Ppattern)``, 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\d{4})/$', 'news.views.year_archive'), - (r'^articles/(?P\d{4})/(?P\d{2})/$', 'news.views.month_archive'), - (r'^articles/(?P\d{4})/(?P\d{2})/(?P\d{2})/$', 'news.views.article_detail'), + url(r'^articles/2003/$', 'news.views.special_case_2003'), + url(r'^articles/(?P\d{4})/$', 'news.views.year_archive'), + url(r'^articles/(?P\d{4})/(?P\d{2})/$', 'news.views.month_archive'), + url(r'^articles/(?P\d{4})/(?P\d{2})/(?P\d{2})/$', 'news.views.article_detail'), ) This accomplishes exactly the same thing as the previous example, with one @@ -184,7 +184,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\d{4})/$', 'news.views.year_archive'), + url(r'^articles/(?P\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. @@ -194,13 +194,14 @@ Here's an example URLconf and view:: # URLconf urlpatterns = patterns('', - (r'^blog/$', 'blog.views.page'), - (r'^blog/page(?P\d+)/$', 'blog.views.page'), + url(r'^blog/$', 'blog.views.page'), + url(r'^blog/page(?P\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 @@ -259,12 +260,12 @@ code duplication. Here's the example URLconf from the :doc:`Django 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'``. @@ -274,12 +275,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 @@ -295,25 +296,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\d{4})/(?P[a-z]{3})/$', 'myapp.views.month_display'), - (r'^tag/(?P\w+)/$', 'weblog.views.tag'), + url(r'^$', 'myapp.views.app_index'), + url(r'^(?P\d{4})/(?P[a-z]{3})/$', 'myapp.views.month_display'), + url(r'^tag/(?P\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\d{4})/(?P[a-z]{3})/$','month_display'), + url(r'^$', 'app_index'), + url(r'^(?P\d{4})/(?P[a-z]{3})/$','month_display'), ) urlpatterns += patterns('weblog.views', - (r'^tag/(?P\w+)/$', 'tag'), + url(r'^tag/(?P\w+)/$', 'tag'), ) .. _including-other-urlconfs: @@ -327,14 +328,14 @@ 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')), - (r'^r/', include('django.conf.urls.shortcut')), + url(r'^comments/', include('django.contrib.comments.urls')), + url(r'^community/', include('django_website.aggregator.urls')), + url(r'^contact/', include('django_website.contact.urls')), + url(r'^r/', include('django.conf.urls.shortcut')), # ... snip ... ) @@ -349,7 +350,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\d+)/$', 'credit.views.report'), @@ -358,8 +359,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 @@ -375,13 +376,13 @@ the following example is valid:: # In settings/urls/main.py urlpatterns = patterns('', - (r'^(?P\w+)/blog/', include('foo.urls.blog')), + url(r'^(?P\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 @@ -395,13 +396,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\d{4})/$', 'year_archive', {'foo': 'bar'}), + url(r'^blog/(?P\d{4})/$', 'year_archive', {'foo': 'bar'}), ) In this example, for a request to ``/blog/2005/``, Django will call @@ -431,26 +433,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 @@ -468,9 +470,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 @@ -479,9 +481,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 @@ -491,9 +493,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. @@ -507,7 +509,7 @@ imported:: from mysite.views import ClassBasedView urlpatterns = patterns('', - (r'^myview/$', ClassBasedView.as_view()), + url(r'^myview/$', ClassBasedView.as_view()), ) Reverse resolution of URLs @@ -616,8 +618,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 @@ -635,7 +637,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 @@ -647,7 +649,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. @@ -790,7 +793,7 @@ Firstly, you can provide the :term:`application ` 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` @@ -810,7 +813,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.