mirrors/django
mirrors/django
0
0
Fork 0
mirror of https://github.com/django/django.git synced 2024-12-01 15:42:04 +01:00
Code Issues Releases Wiki Activity

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

Browse Source 
Thanks Baptiste Mispelon for the patch and dave.lampton@ for the suggestion.
This commit is contained in:
Tim Graham 2013-04-10 20:38:25 -04:00
parent 68d6c52ed6
commit c852d45681
1 changed files with 66 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

129
docs/topics/http/urls.txt
View File

@ -66,13 +66,13 @@ Example
Here's a sample URLconf:: Here's a sample URLconf::
from django.conf.urls import patterns from django.conf.urls import patterns, url
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^articles/2003/$', 'news.views.special_case_2003'), url(r'^articles/2003/$', 'news.views.special_case_2003'),
(r'^articles/(\d{4})/$', 'news.views.year_archive'), url(r'^articles/(\d{4})/$', 'news.views.year_archive'),
(r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'), url(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})/(\d{2})/(\d+)/$', 'news.views.article_detail'),
) )
Notes: 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:: Here's the above example URLconf, rewritten to use named groups::
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^articles/2003/$', 'news.views.special_case_2003'), url(r'^articles/2003/$', 'news.views.special_case_2003'),
(r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'), url(r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),
(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})/$', '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/(?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 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 of what sort of match the regular expression makes. For example, in this
URLconf line:: 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 ...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. an integer, even though the ``\d{4}`` will only match integer strings.
@ -193,13 +193,14 @@ Here's an example URLconf and view::
# URLconf # URLconf
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^blog/$', 'blog.views.page'), url(r'^blog/$', 'blog.views.page'),
(r'^blog/page(?P<num>\d+)/$', 'blog.views.page'), url(r'^blog/page(?P<num>\d+)/$', 'blog.views.page'),
) )
# View (in blog/views.py) # View (in blog/views.py)
def page(request, num="1"): def page(request, num="1"):
# Output the appropriate page of blog entries, according to num. # Output the appropriate page of blog entries, according to num.
...
In the above example, both URL patterns point to the same view -- 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 ``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>`:: 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('', urlpatterns = patterns('',
(r'^articles/(\d{4})/$', 'news.views.year_archive'), url(r'^articles/(\d{4})/$', 'news.views.year_archive'),
(r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'), url(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})/(\d{2})/(\d+)/$', 'news.views.article_detail'),
) )
In this example, each view has a common prefix -- ``'news.views'``. 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:: 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', urlpatterns = patterns('news.views',
(r'^articles/(\d{4})/$', 'year_archive'), url(r'^articles/(\d{4})/$', 'year_archive'),
(r'^articles/(\d{4})/(\d{2})/$', 'month_archive'), url(r'^articles/(\d{4})/(\d{2})/$', 'month_archive'),
(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'article_detail'), url(r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'article_detail'),
) )
Note that you don't put a trailing dot (``"."``) in the prefix. Django puts 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:: Old::
from django.conf.urls import patterns from django.conf.urls import patterns, url
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^$', 'myapp.views.app_index'), url(r'^$', 'myapp.views.app_index'),
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'myapp.views.month_display'), url(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$', 'myapp.views.month_display'),
(r'^tag/(?P<tag>\w+)/$', 'weblog.views.tag'), url(r'^tag/(?P<tag>\w+)/$', 'weblog.views.tag'),
) )
New:: New::
from django.conf.urls import patterns from django.conf.urls import patterns, url
urlpatterns = patterns('myapp.views', urlpatterns = patterns('myapp.views',
(r'^$', 'app_index'), url(r'^$', 'app_index'),
(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$','month_display'), url(r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$','month_display'),
) )
urlpatterns += patterns('weblog.views', urlpatterns += patterns('weblog.views',
(r'^tag/(?P<tag>\w+)/$', 'tag'), url(r'^tag/(?P<tag>\w+)/$', 'tag'),
) )
.. _including-other-urlconfs: .. _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`_ For example, here's an excerpt of the URLconf for the `Django Web site`_
itself. It includes a number of other URLconfs:: 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('', urlpatterns = patterns('',
# ... snip ... # ... snip ...
(r'^comments/', include('django.contrib.comments.urls')), url(r'^comments/', include('django.contrib.comments.urls')),
(r'^community/', include('django_website.aggregator.urls')), url(r'^community/', include('django_website.aggregator.urls')),
(r'^contact/', include('django_website.contact.urls')), url(r'^contact/', include('django_website.contact.urls')),
# ... snip ... # ... 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` directly the pattern list as returned by :func:`~django.conf.urls.patterns`
instead. For example, consider this URLconf:: 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('', extra_patterns = patterns('',
url(r'^reports/(?P<id>\d+)/$', 'credit.views.report'), url(r'^reports/(?P<id>\d+)/$', 'credit.views.report'),
@ -353,8 +354,8 @@ instead. For example, consider this URLconf::
urlpatterns = patterns('', urlpatterns = patterns('',
url(r'^$', 'apps.main.views.homepage'), url(r'^$', 'apps.main.views.homepage'),
(r'^help/', include('apps.help.urls')), url(r'^help/', include('apps.help.urls')),
(r'^credit/', include(extra_patterns)), url(r'^credit/', include(extra_patterns)),
) )
In this example, the ``/credit/reports/`` URL will be handled by the 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 # In settings/urls/main.py
urlpatterns = patterns('', 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 # In foo/urls/blog.py
urlpatterns = patterns('foo.views', urlpatterns = patterns('foo.views',
(r'^$', 'blog.index'), url(r'^$', 'blog.index'),
(r'^archive/$', 'blog.archive'), url(r'^archive/$', 'blog.archive'),
) )
In the above example, the captured ``"username"`` variable is passed to the 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, URLconfs have a hook that lets you pass extra arguments to your view functions,
as a Python dictionary. as a Python dictionary.
Any URLconf tuple can have an optional third element, which should be a The :func:`django.conf.urls.url` function can take an optional third argument
dictionary of extra keyword arguments to pass to the view function. which should be a dictionary of extra keyword arguments to pass to the view
function.
For example:: For example::
urlpatterns = patterns('blog.views', 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 In this example, for a request to ``/blog/2005/``, Django will call
@ -426,26 +428,26 @@ Set one::
# main.py # main.py
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^blog/', include('inner'), {'blogid': 3}), url(r'^blog/', include('inner'), {'blogid': 3}),
) )
# inner.py # inner.py
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/$', 'mysite.views.archive'), url(r'^archive/$', 'mysite.views.archive'),
(r'^about/$', 'mysite.views.about'), url(r'^about/$', 'mysite.views.about'),
) )
Set two:: Set two::
# main.py # main.py
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^blog/', include('inner')), url(r'^blog/', include('inner')),
) )
# inner.py # inner.py
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/$', 'mysite.views.archive', {'blogid': 3}), url(r'^archive/$', 'mysite.views.archive', {'blogid': 3}),
(r'^about/$', 'mysite.views.about', {'blogid': 3}), url(r'^about/$', 'mysite.views.about', {'blogid': 3}),
) )
Note that extra options will *always* be passed to *every* line in the included 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:: For example, given this URLconf in "string" notation::
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/$', 'mysite.views.archive'), url(r'^archive/$', 'mysite.views.archive'),
(r'^about/$', 'mysite.views.about'), url(r'^about/$', 'mysite.views.about'),
(r'^contact/$', 'mysite.views.contact'), url(r'^contact/$', 'mysite.views.contact'),
) )
You can accomplish the same thing by passing objects rather than strings. Just 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 from mysite.views import archive, about, contact
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/$', archive), url(r'^archive/$', archive),
(r'^about/$', about), url(r'^about/$', about),
(r'^contact/$', contact), url(r'^contact/$', contact),
) )
The following example is functionally identical. It's just a bit more compact The following example is functionally identical. It's just a bit more compact
@ -486,9 +488,9 @@ each view individually::
from mysite import views from mysite import views
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/$', views.archive), url(r'^archive/$', views.archive),
(r'^about/$', views.about), url(r'^about/$', views.about),
(r'^contact/$', views.contact), url(r'^contact/$', views.contact),
) )
The style you use is up to you. The style you use is up to you.
@ -502,7 +504,7 @@ imported::
from mysite.views import ClassBasedView from mysite.views import ClassBasedView
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^myview/$', ClassBasedView.as_view()), url(r'^myview/$', ClassBasedView.as_view()),
) )
Reverse resolution of URLs Reverse resolution of URLs
@ -611,8 +613,8 @@ your URLconf. For example, these two URL patterns both point to the ``archive``
view:: view::
urlpatterns = patterns('', urlpatterns = patterns('',
(r'^archive/(\d{4})/$', archive), url(r'^archive/(\d{4})/$', archive),
(r'^archive-summary/(\d{4})/$', archive, {'summary': True}), url(r'^archive-summary/(\d{4})/$', archive, {'summary': True}),
) )
This is completely valid, but it leads to problems when you try to do reverse 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('', urlpatterns = patterns('',
url(r'^archive/(\d{4})/$', archive, name="full-archive"), 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 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 %} {% url 'full-archive' 2007 %}
Even though both URL patterns refer to the ``archive`` view here, using the 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 The string used for the URL name can contain any characters you like. You are
not restricted to valid Python names. 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 :func:`django.conf.urls.include()` when you construct your URL patterns. For
example,:: 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 This will include the URLs defined in ``apps.help.urls`` into the
:term:`application namespace` ``'bar'``, with the :term:`instance namespace` :term:`application namespace` ``'bar'``, with the :term:`instance namespace`
@ -805,7 +808,7 @@ For example::
url(r'^advanced/$', 'apps.help.views.views.advanced'), 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 This will include the nominated URL patterns into the given application and
instance namespace. instance namespace.