Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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

Thanks Baptiste Mispelon for the patch and dave.lampton@ for the suggestion.
  • Loading branch information...
commit c852d4568186b9a23af510762acb94003fc83e65 1 parent 68d6c52
@timgraham timgraham authored
Showing with 66 additions and 63 deletions.
  1. +66 −63 docs/topics/http/urls.txt
View
129 docs/topics/http/urls.txt
@@ -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.
Please sign in to comment.
Something went wrong with that request. Please try again.