Django

Code

Changeset 1471

Show
Ignore:
Timestamp:
11/27/05 17:03:56 (3 years ago)
Author:
adrian
Message:

Updated middleware.txt and url_dispatch.txt docs to reflect [1470] (support for non-named groups in URLconf regexes)

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/middleware.txt

    r1166 r1471  
    126126------------ 
    127127 
    128 Interface: ``process_view(self, request, view_func, param_dict)`` 
     128Interface: ``process_view(self, request, view_func, view_args, view_kwargs)`` 
    129129 
    130130``request`` is an ``HttpRequest`` object. ``view_func`` is the Python function 
    131131that Django is about to use. (It's the actual function object, not the name of 
    132 the function as a string.) ``param_dict`` is a dictionary of keyword arguments 
    133 that will be passed to the view -- NOT including the first argument (``request``). 
     132the function as a string.) ``view_args`` is a list of positional arguments that 
     133will be passed to the view, and ``view_kwargs`` is a dictionary of keyword 
     134arguments that will be passed to the view. Neither ``view_args`` nor 
     135``view_kwargs`` include the first view argument (``request``). 
    134136 
    135137``process_view()`` is called just before Django calls the view. It should 

  • django/trunk/docs/url_dispatch.txt

    r1453 r1471  
    4343    4. Once one of the regexes matches, Django imports and calls the given 
    4444       view, which is a simple Python function. The view gets passed a 
    45        `request object`_ and any values captured in the regex as keyword 
     45       `request object`_ and any values captured in the regex as function 
    4646       arguments. 
    4747 
    …… 
    5252======= 
    5353 
     54**This syntax is new in the Django development version.** See "Named groups" 
     55below if you're using Django 0.90. 
     56 
    5457Here's a sample URLconf:: 
    5558 
    5659    from django.conf.urls.defaults import * 
     60 
     61    urlpatterns = patterns('', 
     62        (r'^articles/2003/$', 'news.views.special_case_2003'), 
     63        (r'^articles/(\d{4})/$', 'news.views.year_archive'), 
     64        (r'^articles/(\d{4})/(\d{2})/$', 'news.views.month_archive'), 
     65        (r'^articles/(\d{4})/(\d{2})/(\d+)/$', 'news.views.article_detail'), 
     66    ) 
     67 
     68Notes: 
     69 
     70    * ``from django.conf.urls.defaults import *`` makes the ``patterns`` 
     71      function available. 
     72 
     73    * To capture a value from the URL, just put parenthesis around it. 
     74 
     75    * There's no need to add a leading slash, because every URL has that. For 
     76      example, it's ``^articles``, not ``^/articles``. 
     77 
     78    * The ``"r"`` in front of each regular expression string is optional but 
     79      recommended. It tells Python that a string is "raw" -- that nothing in 
     80      the string should be escaped. See `Dive Into Python's explanation`_. 
     81 
     82Examples: 
     83 
     84    * A request to ``/articles/2005/03/`` would match the third entry in the 
     85      list. Django would call the function 
     86      ``news.views.month_archive(request, '2005', '03')``. 
     87 
     88    * ``/articles/2005/3/`` would not match any URL patterns, because the 
     89      third entry in the list requires two digits for the month. 
     90 
     91    * ``/articles/2003/`` would match the first pattern in the list, not the 
     92      second one, because the patterns are tested in order, and the first one 
     93      is the first test to pass. Feel free to exploit the ordering to insert 
     94      special cases like this. 
     95 
     96    * ``/articles/2003`` would not match any of these patterns, because each 
     97      pattern requires that the URL end with a slash. 
     98 
     99    * ``/articles/2003/03/3/`` would match the final pattern. Django would call 
     100      the function ``news.views.article_detail(request, '2003', '03', '3')``. 
     101 
     102.. _Dive Into Python's explanation: http://diveintopython.org/regular_expressions/street_addresses.html#re.matching.2.3 
     103 
     104Named groups 
     105============ 
     106 
     107The above example used simple, *non-named* regular-expression groups (via 
     108parenthesis) to capture bits of the URL and pass them as *positional* arguments 
     109to a view. In more advanced usage, it's possible to use *named* 
     110regular-expression groups to capture URL bits and pass them as *keyword* 
     111arguments to a view. 
     112 
     113(Note that support for non-named regex groups is a new feature in the Django 
     114development version. Django 0.90 requires named groups.) 
     115 
     116In Python regular expressions, the syntax for named regular-expression groups 
     117is ``(?P<name>pattern)``, where ``name`` is the name of the group and 
     118``pattern`` is some pattern to match. 
     119 
     120Here's the above example URLconf, rewritten to use named groups:: 
    57121 
    58122    urlpatterns = patterns('', 
    …… 
    63127    ) 
    64128 
    65 Notes: 
    66  
    67     * ``from django.conf.urls.defaults import *`` makes the ``patterns`` 
    68       function available. 
    69  
    70     * To capture a value from the URL, use the syntax ``(?P<name>pattern)``, 
    71       where ``name`` is the name for that value and ``pattern`` is some pattern 
    72       to match. 
    73  
    74     * There's no need to add a leading slash, because every URL has that. For 
    75       example, it's ``^articles``, not ``^/articles``. 
    76  
    77     * The ``"r"`` in front of each regular expression string is optional but 
    78       recommended. It tells Python that a string is "raw" -- that nothing in 
    79       the string should be escaped. See `Dive Into Python's explanation`_. 
    80  
    81 Examples: 
    82  
    83     * A request to ``/articles/2005/03/`` would match the third entry in the 
    84       list. Django would call the function 
    85       ``news.views.month_archive(request, year='2005', month='03')``. 
    86  
    87     * ``/articles/2005/3/`` would not match any URL patterns, because the 
    88       third entry in the list requires two digits for the month. 
    89  
    90     * ``/articles/2003/`` would match the first pattern in the list, not the 
    91       second one, because the patterns are tested in order, and the first one 
    92       is the first test to pass. Feel free to exploit the ordering to insert 
    93       special cases like this. 
    94  
    95     * ``/articles/2003`` would not match any of these patterns, because each 
    96       pattern requires that the URL end with a slash. 
    97  
    98     * ``/articles/2003/03/3/`` would match the final pattern. Django would call 
    99       the function 
     129This accomplishes exactly the same thing as the previous example, with one 
     130subtle difference: The captured values are passed as keyword arguments rather 
     131than positional arguments. For example: 
     132 
     133    * A request to ``/articles/2005/03/`` would call the function 
     134      ``news.views.month_archive(request, year='2005', month='03')``, instead 
     135      of ``news.views.month_archive(request, '2005', '03')``. 
     136 
     137    * A request to ``/articles/2003/03/3/`` would call the function 
    100138      ``news.views.article_detail(request, year='2003', month='03', day='3')``. 
    101139 
    102 .. _Dive Into Python's explanation: http://diveintopython.org/regular_expressions/street_addresses.html#re.matching.2.3 
     140In practice, this means your URLconfs are slightly more explicit and less prone 
     141to argument-order bugs -- and you can reorder the arguments in your views' 
     142function definitions. Of course, these benefits come at the cost of brevity; 
     143some folks find the named-group syntax ugly and too verbose. 
     144 
     145The matching/grouping algorithm 
     146------------------------------- 
     147 
     148Here's the algorithm the URLconf parser follows, with respect to named groups 
     149vs. non-named groups in a regular expression: 
     150 
     151    * If there are any named groups, it will use those as keyword arguments, 
     152      ignoring any non-named groups. 
     153    * Otherwise, it will pass all non-named groups as positional arguments. 
     154    * In both cases, it will pass any extra 
     155 
     156If there are any named arguments, it will use those, ignoring non-named arguments. 
     157Otherwise, it will pass all non-named arguments as positional arguments. 
     158 
     159In both cases, it will pass any extra keyword arguments as keyword arguments. 
     160See "Passing extra options to view functions" below. 
    103161 
    104162What the URLconf searches against 
    …… 
    170228Each captured argument is sent to the view as a plain Python string, regardless 
    171229of what sort of match the regular expression makes. For example, in this 
    172 URLconf:: 
     230URLconf line:: 
    173231 
    174232    (r'^articles/(?P<year>\d{4})/$', 'news.views.year_archive'),