Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Updated middleware.txt and url_dispatch.txt docs to reflect [1470] (s…

…upport for non-named groups in URLconf regexes)

git-svn-id: http://code.djangoproject.com/svn/django/trunk@1471 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit f1eff69a4f89905e9b36a83b1825a3a2c4454899 1 parent cc3660c
@adrianholovaty adrianholovaty authored
Showing with 74 additions and 14 deletions.
  1. +5 −3 docs/middleware.txt
  2. +69 −11 docs/url_dispatch.txt
View
8 docs/middleware.txt
@@ -125,12 +125,14 @@ the appropriate view; it'll return that ``HttpResponse``.
process_view
------------
-Interface: ``process_view(self, request, view_func, param_dict)``
+Interface: ``process_view(self, request, view_func, view_args, view_kwargs)``
``request`` is an ``HttpRequest`` object. ``view_func`` is the Python function
that Django is about to use. (It's the actual function object, not the name of
-the function as a string.) ``param_dict`` is a dictionary of keyword arguments
-that will be passed to the view -- NOT including the first argument (``request``).
+the function as a string.) ``view_args`` is a list of positional arguments that
+will be passed to the view, and ``view_kwargs`` is a dictionary of keyword
+arguments that will be passed to the view. Neither ``view_args`` nor
+``view_kwargs`` include the first view argument (``request``).
``process_view()`` is called just before Django calls the view. It should
return either ``None`` or an ``HttpResponse`` object. If it returns ``None``,
View
80 docs/url_dispatch.txt
@@ -42,7 +42,7 @@ algorithm the system follows to determine which Python code to execute:
first one that matches the requested URL.
4. Once one of the regexes matches, Django imports and calls the given
view, which is a simple Python function. The view gets passed a
- `request object`_ and any values captured in the regex as keyword
+ `request object`_ and any values captured in the regex as function
arguments.
.. _settings file: http://www.djangoproject.com/documentation/settings/
@@ -51,15 +51,18 @@ algorithm the system follows to determine which Python code to execute:
Example
=======
+**This syntax is new in the Django development version.** See "Named groups"
+below if you're using Django 0.90.
+
Here's a sample URLconf::
from django.conf.urls.defaults import *
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+)/$', 'news.views.article_detail'),
+ (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'),
)
Notes:
@@ -67,9 +70,7 @@ Notes:
* ``from django.conf.urls.defaults import *`` makes the ``patterns``
function available.
- * To capture a value from the URL, use the syntax ``(?P<name>pattern)``,
- where ``name`` is the name for that value and ``pattern`` is some pattern
- to match.
+ * To capture a value from the URL, just put parenthesis around it.
* There's no need to add a leading slash, because every URL has that. For
example, it's ``^articles``, not ``^/articles``.
@@ -82,7 +83,7 @@ Examples:
* A request to ``/articles/2005/03/`` would match the third entry in the
list. Django would call the function
- ``news.views.month_archive(request, year='2005', month='03')``.
+ ``news.views.month_archive(request, '2005', '03')``.
* ``/articles/2005/3/`` would not match any URL patterns, because the
third entry in the list requires two digits for the month.
@@ -96,11 +97,68 @@ Examples:
pattern requires that the URL end with a slash.
* ``/articles/2003/03/3/`` would match the final pattern. Django would call
- the function
- ``news.views.article_detail(request, year='2003', month='03', day='3')``.
+ the function ``news.views.article_detail(request, '2003', '03', '3')``.
.. _Dive Into Python's explanation: http://diveintopython.org/regular_expressions/street_addresses.html#re.matching.2.3
+Named groups
+============
+
+The above example used simple, *non-named* regular-expression groups (via
+parenthesis) to capture bits of the URL and pass them as *positional* arguments
+to a view. In more advanced usage, it's possible to use *named*
+regular-expression groups to capture URL bits and pass them as *keyword*
+arguments to a view.
+
+(Note that support for non-named regex groups is a new feature in the Django
+development version. Django 0.90 requires named groups.)
+
+In Python regular expressions, the syntax for named regular-expression groups
+is ``(?P<name>pattern)``, where ``name`` is the name of the group and
+``pattern`` is some pattern to match.
+
+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+)/$', 'news.views.article_detail'),
+ )
+
+This accomplishes exactly the same thing as the previous example, with one
+subtle difference: The captured values are passed as keyword arguments rather
+than positional arguments. For example:
+
+ * A request to ``/articles/2005/03/`` would call the function
+ ``news.views.month_archive(request, year='2005', month='03')``, instead
+ of ``news.views.month_archive(request, '2005', '03')``.
+
+ * A request to ``/articles/2003/03/3/`` would call the function
+ ``news.views.article_detail(request, year='2003', month='03', day='3')``.
+
+In practice, this means your URLconfs are slightly more explicit and less prone
+to argument-order bugs -- and you can reorder the arguments in your views'
+function definitions. Of course, these benefits come at the cost of brevity;
+some folks find the named-group syntax ugly and too verbose.
+
+The matching/grouping algorithm
+-------------------------------
+
+Here's the algorithm the URLconf parser follows, with respect to named groups
+vs. non-named groups in a regular expression:
+
+ * If there are any named groups, it will use those as keyword arguments,
+ ignoring any non-named groups.
+ * Otherwise, it will pass all non-named groups as positional arguments.
+ * In both cases, it will pass any extra
+
+If there are any named arguments, it will use those, ignoring non-named arguments.
+Otherwise, it will pass all non-named arguments as positional arguments.
+
+In both cases, it will pass any extra keyword arguments as keyword arguments.
+See "Passing extra options to view functions" below.
+
What the URLconf searches against
=================================
@@ -169,7 +227,7 @@ Notes on capturing text in URLs
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::
+URLconf line::
(r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),
Please sign in to comment.
Something went wrong with that request. Please try again.