Refactored URL mapping documentation.

Reorganized topic document so it introduces concepts form simple to more
complex. Moved reference parts to their own documents.

3 files changed, 346 insertions, 1 deletions

diff --git a/docs/ref/index.txt b/docs/ref/index.txt
index 01a8ab22d1..e1959d44a6 100644
--- a/docs/ref/index.txt
+++ b/docs/ref/index.txt
@@ -6,7 +6,7 @@ API Reference
    :maxdepth: 1
 
    authbackends
-   class-based-views/index   
+   class-based-views/index
    clickjacking
    contrib/index
    databases
@@ -22,5 +22,7 @@ API Reference
    signals
    templates/index
    unicode
+   urlresolvers
+   urls
    utils
    validators
diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt
new file mode 100644
index 0000000000..965cafb29b
--- /dev/null
+++ b/docs/ref/urlresolvers.txt
@@ -0,0 +1,204 @@
+==============================================
+``django.core.urlresolvers`` utility functions
+==============================================
+
+.. module:: django.core.urlresolvers
+
+reverse()
+---------
+
+If you need to use something similar to the :ttag:`url` template tag in
+your code, Django provides the following function (in the
+:mod:`django.core.urlresolvers` module):
+
+.. function:: reverse(viewname, [urlconf=None, args=None, kwargs=None, current_app=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
+:ref:`URL pattern name <naming-url-patterns>`.  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]))
+
+The ``reverse()`` function can reverse a large variety of regular expression
+patterns for URLs, but not every possible one. The main restriction at the
+moment is that the pattern cannot contain alternative choices using the
+vertical bar (``"|"``) character. You can quite happily use such patterns for
+matching against incoming URLs and sending them off to views, but you cannot
+reverse such patterns.
+
+The ``current_app`` argument allows you to provide a hint to the resolver
+indicating the application to which the currently executing view belongs.
+This ``current_app`` argument is used as a hint to resolve application
+namespaces into URLs on specific application instances, according to the
+:ref:`namespaced URL resolution strategy <topics-http-reversing-url-namespaces>`.
+
+You can use ``kwargs`` instead of ``args``. For example::
+
+    >>> reverse('admin:app_list', kwargs={'app_label': 'auth'})
+    '/admin/auth/'
+
+``args`` and ``kwargs`` cannot be passed to ``reverse()`` at the same time.
+
+.. admonition:: Make sure your views are all correct.
+
+    As part of working out which URL names map to which patterns, the
+    ``reverse()`` function has to import all of your URLconf files and examine
+    the name of each view. This involves importing each view function. If
+    there are *any* errors whilst importing any of your view functions, it
+    will cause ``reverse()`` to raise an error, even if that view function is
+    not the one you are trying to reverse.
+
+    Make sure that any views you reference in your URLconf files exist and can
+    be imported correctly. Do not include lines that reference views you
+    haven't written yet, because those views will not be importable.
+
+.. note::
+
+    The string returned by :meth:`~django.core.urlresolvers.reverse` is already
+    :ref:`urlquoted <uri-and-iri-handling>`. For example::
+
+        >>> reverse('cities', args=[u'Orléans'])
+        '.../Orl%C3%A9ans/'
+
+    Applying further encoding (such as :meth:`~django.utils.http.urlquote` or
+    ``urllib.quote``) to the output of :meth:`~django.core.urlresolvers.reverse`
+    may produce undesirable results.
+
+reverse_lazy()
+--------------
+
+.. versionadded:: 1.4
+
+A lazily evaluated version of `reverse()`_.
+
+.. function:: reverse_lazy(viewname, [urlconf=None, args=None, kwargs=None, current_app=None])
+
+It is useful for when you need to use a URL reversal before your project's
+URLConf is loaded. Some common cases where this function is necessary are:
+
+* providing a reversed URL as the ``url`` attribute of a generic class-based
+  view.
+
+* providing a reversed URL to a decorator (such as the ``login_url`` argument
+  for the :func:`django.contrib.auth.decorators.permission_required`
+  decorator).
+
+* providing a reversed URL as a default value for a parameter in a function's
+  signature.
+
+resolve()
+---------
+
+The :func:`django.core.urlresolvers.resolve` function can be used for
+resolving URL paths to the corresponding view functions. It has the
+following signature:
+
+.. function:: resolve(path, urlconf=None)
+
+``path`` is the URL path you want to resolve. As with
+:func:`~django.core.urlresolvers.reverse`, you don't need to
+worry about the ``urlconf`` parameter. The function returns a
+:class:`ResolverMatch` object that allows you
+to access various meta-data about the resolved URL.
+
+If the URL does not resolve, the function raises an
+:class:`~django.http.Http404` exception.
+
+.. class:: ResolverMatch
+
+    .. attribute:: ResolverMatch.func
+
+        The view function that would be used to serve the URL
+
+    .. attribute:: ResolverMatch.args
+
+        The arguments that would be passed to the view function, as
+        parsed from the URL.
+
+    .. attribute:: ResolverMatch.kwargs
+
+        The keyword arguments that would be passed to the view
+        function, as parsed from the URL.
+
+    .. attribute:: ResolverMatch.url_name
+
+        The name of the URL pattern that matches the URL.
+
+    .. attribute:: ResolverMatch.app_name
+
+        The application namespace for the URL pattern that matches the
+        URL.
+
+    .. attribute:: ResolverMatch.namespace
+
+        The instance namespace for the URL pattern that matches the
+        URL.
+
+    .. attribute:: ResolverMatch.namespaces
+
+        The list of individual namespace components in the full
+        instance namespace for the URL pattern that matches the URL.
+        i.e., if the namespace is ``foo:bar``, then namespaces will be
+        ``['foo', 'bar']``.
+
+A :class:`ResolverMatch` object can then be interrogated to provide
+information about the URL pattern that matches a URL::
+
+    # Resolve a URL
+    match = resolve('/some/path/')
+    # Print the URL pattern that matches the URL
+    print(match.url_name)
+
+A :class:`ResolverMatch` object can also be assigned to a triple::
+
+    func, args, kwargs = resolve('/some/path/')
+
+One possible use of :func:`~django.core.urlresolvers.resolve` would be to test
+whether a view would raise a ``Http404`` error before redirecting to it::
+
+    from urlparse import urlparse
+    from django.core.urlresolvers import resolve
+    from django.http import HttpResponseRedirect, Http404
+
+    def myview(request):
+        next = request.META.get('HTTP_REFERER', None) or '/'
+        response = HttpResponseRedirect(next)
+
+        # modify the request and response as required, e.g. change locale
+        # and set corresponding locale cookie
+
+        view, args, kwargs = resolve(urlparse(next)[2])
+        kwargs['request'] = request
+        try:
+            view(*args, **kwargs)
+        except Http404:
+            return HttpResponseRedirect('/')
+        return response
+
+
+permalink()
+-----------
+
+The :func:`django.db.models.permalink` decorator is useful for writing short
+methods that return a full URL path. For example, a model's
+``get_absolute_url()`` method. See :func:`django.db.models.permalink` for more.
+
+get_script_prefix()
+-------------------
+
+.. function:: get_script_prefix()
+
+Normally, you should always use :func:`~django.core.urlresolvers.reverse` or
+:func:`~django.db.models.permalink` to define URLs within your application.
+However, if your application constructs part of the URL hierarchy itself, you
+may occasionally need to generate URLs. In that case, you need to be able to
+find the base URL of the Django project within its Web server
+(normally, :func:`~django.core.urlresolvers.reverse` takes care of this for
+you). In that case, you can call ``get_script_prefix()``, which will return the
+script prefix portion of the URL for your Django project. If your Django
+project is at the root of its Web server, this is always ``"/"``.
diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt
new file mode 100644
index 0000000000..3d860fc0ed
--- /dev/null
+++ b/docs/ref/urls.txt
@@ -0,0 +1,139 @@
+======================================
+``django.conf.urls`` utility functions
+======================================
+
+.. module:: django.conf.urls
+
+.. versionchanged:: 1.4
+    Starting with Django 1.4 functions ``patterns``, ``url``, ``include`` plus
+    the ``handler*`` symbols described below live in the ``django.conf.urls``
+    module.
+
+    Until Django 1.3 they were located in ``django.conf.urls.defaults``. You
+    still can import them from there but it will be removed in Django 1.6.
+
+patterns()
+----------
+
+.. function:: patterns(prefix, pattern_description, ...)
+
+A function that takes a prefix, and an arbitrary number of URL patterns, and
+returns a list of URL patterns in the format Django needs.
+
+The first argument to ``patterns()`` is a string ``prefix``. See
+:ref:`The view prefix <urlpatterns-view-prefix>`.
+
+The remaining arguments should be tuples in this format::
+
+    (regular expression, Python callback function [, optional_dictionary [, optional_name]])
+
+The ``optional_dictionary`` and ``optional_name`` parameters are described in
+:ref:`Passing extra options to view functions <views-extra-options>`.
+
+.. note::
+    Because `patterns()` is a function call, it accepts a maximum of 255
+    arguments (URL patterns, in this case). This is a limit for all Python
+    function calls. This is rarely a problem in practice, because you'll
+    typically structure your URL patterns modularly by using `include()`
+    sections. However, on the off-chance you do hit the 255-argument limit,
+    realize that `patterns()` returns a Python list, so you can split up the
+    construction of the list.
+
+    ::
+
+        urlpatterns = patterns('',
+            ...
+            )
+        urlpatterns += patterns('',
+            ...
+            )
+
+    Python lists have unlimited size, so there's no limit to how many URL
+    patterns you can construct. The only limit is that you can only create 254
+    at a time (the 255th argument is the initial prefix argument).
+
+url()
+-----
+
+.. function:: url(regex, view, kwargs=None, name=None, prefix='')
+
+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"),
+        ...
+    )
+
+This function takes five arguments, most of which are optional::
+
+    url(regex, view, kwargs=None, name=None, prefix='')
+
+See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name``
+parameter is useful.
+
+The ``prefix`` parameter has the same meaning as the first argument to
+``patterns()`` and is only relevant when you're passing a string as the
+``view`` parameter.
+
+include()
+---------
+
+.. function:: include(<module or pattern_list>)
+
+A function that takes a full Python import path to another URLconf module that
+should be "included" in this place.
+
+:func:`include` also accepts as an argument an iterable that returns URL
+patterns.
+
+See :ref:`Including other URLconfs <including-other-urlconfs>`.
+
+handler403
+----------
+
+.. data:: handler403
+
+A callable, or a string representing the full Python import path to the view
+that should be called if the user doesn't have the permissions required to
+access a resource.
+
+By default, this is ``'django.views.defaults.permission_denied'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 403 (HTTP Forbidden) view
+<http_forbidden_view>` for more information.
+
+.. versionadded:: 1.4
+    ``handler403`` is new in Django 1.4.
+
+handler404
+----------
+
+.. data:: handler404
+
+A callable, or a string representing the full Python import path to the view
+that should be called if none of the URL patterns match.
+
+By default, this is ``'django.views.defaults.page_not_found'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 404 (HTTP Not Found) view
+<http_not_found_view>` for more information.
+
+handler500
+----------
+
+.. data:: handler500
+
+A callable, or a string representing the full Python import path to the view
+that should be called in case of server errors. Server errors happen when you
+have runtime errors in view code.
+
+By default, this is ``'django.views.defaults.server_error'``. That default
+value should suffice.
+
+See the documentation about :ref:`the 500 (HTTP Internal Server Error) view
+<http_internal_server_error_view>` for more information.
+