per-object-permissions: Merged to trunk [5486] NOTE: Not fully tested, will be working on this over the next few weeks.

git-svn-id: http://code.djangoproject.com/svn/django/branches/per-object-permissions@5488 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 122 insertions, 12 deletions

diff --git a/docs/url_dispatch.txt b/docs/url_dispatch.txt
index 00a7af027a..402b1200b5 100644
--- a/docs/url_dispatch.txt
+++ b/docs/url_dispatch.txt
@@ -45,8 +45,8 @@ algorithm the system follows to determine which Python code to execute:
        `request object`_ as its first argument and any values captured in the
        regex as remaining arguments.
 
-.. _settings file: http://www.djangoproject.com/documentation/settings/
-.. _request object: http://www.djangoproject.com/documentation/request_response/#httprequest-objects
+.. _settings file: ../settings/
+.. _request object: ../request_response/#httprequest-objects
 
 Example
 =======
@@ -185,10 +185,26 @@ The first argument to ``patterns()`` is a string ``prefix``. See
 
 The remaining arguments should be tuples in this format::
 
-    (regular expression, Python callback function [, optional dictionary])
+    (regular expression, Python callback function [, optional dictionary [, optional name]])
 
-...where ``optional dictionary`` is optional. (See
-_`Passing extra options to view functions` below.)
+...where ``optional dictionary`` and ``optional name`` are optional. (See
+`Passing extra options to view functions`_ below.)
+
+url
+---
+
+**New in Django development version**
+
+You can use the ``url()`` function, instead of a tuple, as an argument to
+``patterns()``. This is convenient if you want to specify a name without the
+optional extra arguments dictionary. For example::
+
+    urlpatterns = patterns('',
+        url(r'/index/$', index_view, name="main-view"),
+        ...
+    )
+
+See `Naming URL patterns`_ for why the ``name`` parameter is useful.
 
 handler404
 ----------
@@ -286,7 +302,7 @@ With this in mind, the above example can be written more concisely as::
 Note that you don't put a trailing dot (``"."``) in the prefix. Django puts
 that in automatically.
 
-.. _Django overview: http://www.djangoproject.com/documentation/overview/
+.. _Django overview: ../overview/
 
 Multiple view prefixes
 ----------------------
@@ -387,14 +403,19 @@ In this example, for a request to ``/blog/2005/``, Django will call the
 This technique is used in `generic views`_ and in the `syndication framework`_
 to pass metadata and options to views.
 
-.. _generic views: http://www.djangoproject.com/documentation/generic_views/
-.. _syndication framework: http://www.djangoproject.com/documentation/syndication/
+.. _generic views: ../generic_views/
+.. _syndication framework: ../syndication/
+
+.. admonition:: Dealing with conflicts
+
+    It's possible to have a URL pattern which captures named keyword arguments,
+    and also passes arguments with the same names in its dictionary of extra
+    arguments. When this happens, the arguments in the dictionary will be used
+    instead of the arguments captured in the URL.
 
 Passing extra options to ``include()``
 --------------------------------------
 
-**New in the Django development version.**
-
 Similarly, you can pass extra options to ``include()``. When you pass extra
 options to ``include()``, *each* line in the included URLconf will be passed
 the extra options.
@@ -435,8 +456,6 @@ every view in the the included URLconf accepts the extra options you're passing.
 Passing callable objects instead of strings
 ===========================================
 
-**New in the Django development version.**
-
 Some developers find it more natural to pass the actual Python function object
 rather than a string containing the path to its module. This alternative is
 supported -- you can pass any callable object as the view.
@@ -476,3 +495,94 @@ The style you use is up to you.
 
 Note that if you use this technique -- passing objects rather than strings --
 the view prefix (as explained in "The view prefix" above) will have no effect.
+
+Naming URL patterns
+===================
+
+**New in Django development version**
+
+It's fairly common to use the same view function in multiple URL patterns in
+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}),
+    )
+
+This is completely valid, but it leads to problems when you try to do reverse
+URL matching (through the ``permalink()`` decorator or the ``{% url %}``
+template tag). Continuing this example, if you wanted to retrieve the URL for
+the ``archive`` view, Django's reverse URL matcher would get confused, because
+*two* URLpatterns point at that view.
+
+To solve this problem, Django supports **named URL patterns**. That is, you can
+give a name to a URL pattern in order to distinguish it from other patterns
+using the same view and parameters. Then, you can use this name in reverse URL
+matching.
+
+Here's the above example, rewritten to used 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"),
+    )
+
+With these names in place (``full-archive`` and ``arch-summary``), you can
+target each pattern individually by using its name::
+
+    {% url arch-summary 1945 %}
+    {% 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.
+
+The string used for the URL name can contain any characters you like. You are
+not restricted to valid Python names.
+
+.. note::
+
+    When you name your URL patterns, make sure you use names that are unlikely
+    to clash with any other application's choice of names. If you call your URL
+    pattern ``comment``, and another application does the same thing, there's
+    no guarantee which URL will be inserted into your template when you use
+    this name.
+
+    Putting a prefix on your URL names, perhaps derived from the application
+    name, will decrease the chances of collision. We recommend something like
+    ``myapp-comment`` instead of ``comment``.
+
+Utility methods
+===============
+
+reverse()
+---------
+
+If you need to use something similar to the ``{% url %}`` template tag in your
+code, Django provides the ``django.core.urlresolvers.reverse()``. The
+``reverse()`` function has the following signature::
+
+    reverse(viewname, urlconf=None, args=None, kwargs=None)
+
+``viewname`` is either the function name (either a function reference, or the
+string version of the name, if you used that form in ``urlpatterns``) or the
+`URL pattern name`_.  Normally, you won't need to worry about the
+``urlconf`` parameter and will only pass in the positional and keyword
+arguments to use in the URL matching. For example::
+
+    from django.core.urlresolvers import reverse
+
+    def myview(request):
+        return HttpResponseRedirect(reverse('arch-summary', args=[1945]))
+
+.. _URL pattern name: `Naming URL patterns`_
+
+permalink()
+-----------
+
+The ``permalink()`` decorator is useful for writing short methods that return
+a full URL path. For example, a model's ``get_absolute_url()`` method. Refer
+to the `model API documentation`_ for more information about ``permalink()``.
+
+.. _model API documentation: ../model-api/#the-permalink-decorator
+