mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-10-31 09:41:08 +00:00
Code Issues 32 Releases Wiki Activity

[1.5.x] Fixed #20204 - Consistent usage of url() in URL dispatcher documentation

Browse Source 
Thanks Baptiste Mispelon for the patch and dave.lampton@ for the suggestion.

Backport of c852d45681 from master.
This commit is contained in:
Tim Graham
2013-04-10 20:38:25 -04:00
parent d04e8f8c78
commit 82b5e10e61
1 changed files with 67 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -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 ``(?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
@@ -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<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.
@@ -194,13 +194,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
@@ -259,12 +260,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'``.
@@ -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<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:
@@ -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<id>\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<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
@@ -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<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
@@ -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 <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`
@@ -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.