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

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

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.