[soc2009/i18n] merged up to trunk r11385

git-svn-id: http://code.djangoproject.com/svn/django/branches/soc2009/i18n-improvements@11388 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 193 insertions, 10 deletions

diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 4248d4f02e..0b2257cefe 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -4,6 +4,8 @@
 URL dispatcher
 ==============
 
+.. module:: django.core.urlresolvers
+
 A clean, elegant URL scheme is an important detail in a high-quality Web
 application. Django lets you design URLs however you want, with no framework
 limitations.
@@ -40,14 +42,14 @@ algorithm the system follows to determine which Python code to execute:
        this is the value of the ``ROOT_URLCONF`` setting, but if the incoming
        ``HttpRequest`` object has an attribute called ``urlconf``, its value
        will be used in place of the ``ROOT_URLCONF`` setting.
-    
+
     2. Django loads that Python module and looks for the variable
        ``urlpatterns``. This should be a Python list, in the format returned by
        the function ``django.conf.urls.defaults.patterns()``.
-    
+
     3. Django runs through each URL pattern, in order, and stops at the 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 an
        :class:`~django.http.HttpRequest` as its first argument and any values
@@ -182,11 +184,13 @@ your URLconf. This gives your module access to these objects:
 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
-"The view prefix" below.
+`The view prefix`_ below.
 
 The remaining arguments should be tuples in this format::
 
@@ -222,6 +226,8 @@ url
 
 .. versionadded:: 1.0
 
+.. 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::
@@ -244,6 +250,8 @@ The ``prefix`` parameter has the same meaning as the first argument to
 handler404
 ----------
 
+.. data:: handler404
+
 A string representing the full Python import path to the view that should be
 called if none of the URL patterns match.
 
@@ -253,6 +261,8 @@ value should suffice.
 handler500
 ----------
 
+.. data:: handler500
+
 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.
@@ -263,8 +273,17 @@ value should suffice.
 include
 -------
 
-A function that takes a full Python import path to another URLconf that should
-be "included" in this place. See `Including other URLconfs`_ below.
+.. 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.
+
+.. versionadded:: 1.1
+
+:func:`include` also accepts as an argument an iterable that returns URL
+patterns.
+
+See `Including other URLconfs`_ below.
 
 Notes on capturing text in URLs
 ===============================
@@ -391,6 +410,32 @@ Django encounters ``include()``, it chops off whatever part of the URL matched
 up to that point and sends the remaining string to the included URLconf for
 further processing.
 
+.. versionadded:: 1.1
+
+Another possibility is to include additional URL patterns not by specifying the
+URLconf Python module defining them as the `include`_ argument but by using
+directly the pattern list as returned by `patterns`_ instead. For example::
+
+    from django.conf.urls.defaults import *
+
+    extra_patterns = patterns('',
+        url(r'reports/(?P<id>\d+)/$', 'credit.views.report', name='credit-reports'),
+        url(r'charge/$', 'credit.views.charge', name='credit-charge'),
+    )
+
+    urlpatterns = patterns('',
+        url(r'^$',    'apps.main.views.homepage', name='site-homepage'),
+        (r'^help/',   include('apps.help.urls')),
+        (r'^credit/', include(extra_patterns)),
+    )
+
+This approach can be seen in use when you deploy an instance of the Django
+Admin application. The Django Admin is deployed as instances of a
+:class:`AdminSite`; each :class:`AdminSite` instance has an attribute
+``urls`` that returns the url patterns available to that instance. It is this
+attribute that you ``include()`` into your projects ``urlpatterns`` when you
+deploy the admin instance.
+
 .. _`Django Web site`: http://www.djangoproject.com/
 
 Captured parameters
@@ -413,6 +458,58 @@ the following example is valid::
 In the above example, the captured ``"username"`` variable is passed to the
 included URLconf, as expected.
 
+.. _topics-http-defining-url-namespaces:
+
+Defining URL Namespaces
+-----------------------
+
+When you need to deploy multiple instances of a single application, it can be
+helpful to be able to differentiate between instances. This is especially
+important when using :ref:`named URL patterns <naming-url-patterns>`, since
+multiple instances of a single application will share named URLs. Namespaces
+provide a way to tell these named URLs apart.
+
+A URL namespace comes in two parts, both of which are strings:
+
+    * An **application namespace**. This describes the name of the application
+      that is being deployed. Every instance of a single application will have
+      the same application namespace. For example, Django's admin application
+      has the somewhat predictable application namespace of ``admin``.
+
+    * An **instance namespace**. This identifies a specific instance of an
+      application. Instance namespaces should be unique across your entire
+      project. However, an instance namespace can be the same as the
+      application namespace. This is used to specify a default instance of an
+      application. For example, the default Django Admin instance has an
+      instance namespace of ``admin``.
+
+URL Namespaces can be specified in two ways.
+
+Firstly, you can provide the application and instance namespace as arguments
+to ``include()`` when you construct your URL patterns. For example,::
+
+    (r'^help/', include('apps.help.urls', namespace='foo', app_name='bar')),
+
+This will include the URLs defined in ``apps.help.urls`` into the application
+namespace ``bar``, with the instance namespace ``foo``.
+
+Secondly, you can include an object that contains embedded namespace data. If
+you ``include()`` a ``patterns`` object, that object will be added to the
+global namespace. However, you can also ``include()`` an object that contains
+a 3-tuple containing::
+
+    (<patterns object>, <application namespace>, <instance namespace>)
+
+This will include the nominated URL patterns into the given application and
+instance namespace. For example, the ``urls`` attribute of Django's
+:class:`AdminSite` object returns a 3-tuple that contains all the patterns in
+an admin site, plus the name of the admin instance, and the application
+namespace ``admin``.
+
+Once you have defined namespaced URLs, you can reverse them. For details on
+reversing namespaced urls, see the documentation on :ref:`reversing namespaced
+URLs <topics-http-reversing-url-namespaces>`.
+
 Passing extra options to view functions
 =======================================
 
@@ -545,7 +642,7 @@ view::
 
 This is completely valid, but it leads to problems when you try to do reverse
 URL matching (through the ``permalink()`` decorator or the :ttag:`url` template
-tag. Continuing this example, if you wanted to retrieve the URL for the
+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.
 
@@ -587,6 +684,86 @@ not restricted to valid Python names.
     name, will decrease the chances of collision. We recommend something like
     ``myapp-comment`` instead of ``comment``.
 
+.. _topics-http-reversing-url-namespaces:
+
+URL namespaces
+--------------
+
+.. versionadded:: 1.1
+
+Namespaced URLs are specified using the ``:`` operator. For example, the main
+index page of the admin application is referenced using ``admin:index``. This
+indicates a namespace of ``admin``, and a named URL of ``index``.
+
+Namespaces can also be nested. The named URL ``foo:bar:whiz`` would look for
+a pattern named ``whiz`` in the namespace ``bar`` that is itself defined within
+the top-level namespace ``foo``.
+
+When given a namespaced URL (e.g. ``myapp:index``) to resolve, Django splits
+the fully qualified name into parts, and then tries the following lookup:
+
+    1. First, Django looks for a matching application namespace (in this
+       example, ``myapp``). This will yield a list of instances of that
+       application.
+
+    2. If there is a *current* application defined, Django finds and returns
+       the URL resolver for that instance. The *current* application can be
+       specified as an attribute on the template context - applications that
+       expect to have multiple deployments should set the ``current_app``
+       attribute on any ``Context`` or ``RequestContext`` that is used to
+       render a template.
+
+       The current application can also be specified manually as an argument
+       to the :func:`reverse()` function.
+
+    3. If there is no current application. Django looks for a default
+       application instance. The default application instance is the instance
+       that has an instance namespace matching the application namespace (in
+       this example, an instance of the ``myapp`` called ``myapp``).
+
+    4. If there is no default application instance, Django will pick the first
+       deployed instance of the application, whatever its instance name may be.
+
+    5. If the provided namespace doesn't match an application namespace in
+       step 1, Django will attempt a direct lookup of the namespace as an
+       instance namespace.
+
+If there are nested namespaces, these steps are repeated for each part of the
+namespace until only the view name is unresolved. The view name will then be
+resolved into a URL in the namespace that has been found.
+
+To show this resolution strategy in action, consider an example of two instances
+of ``myapp``: one called ``foo``, and one called ``bar``. ``myapp`` has a main
+index page with a URL named `index`. Using this setup, the following lookups are
+possible:
+
+    * If one of the instances is current - say, if we were rendering a utility page
+      in the instance ``bar`` - ``myapp:index`` will resolve to the index page of
+      the instance ``bar``.
+
+    * If there is no current instance - say, if we were rendering a page
+      somewhere else on the site - ``myapp:index`` will resolve to the first
+      registered instance of ``myapp``. Since there is no default instance,
+      the first instance of ``myapp`` that is registered will be used. This could
+      be ``foo`` or ``bar``, depending on the order they are introduced into the
+      urlpatterns of the project.
+
+    * ``foo:index`` will always resolve to the index page of the instance ``foo``.
+
+If there was also a default instance - i.e., an instance named `myapp` - the
+following would happen:
+
+    * If one of the instances is current - say, if we were rendering a utility page
+      in the instance ``bar`` - ``myapp:index`` will resolve to the index page of
+      the instance ``bar``.
+
+    * If there is no current instance - say, if we were rendering a page somewhere
+      else on the site - ``myapp:index`` will resolve to the index page of the
+      default instance.
+
+    * ``foo:index`` will again resolve to the index page of the instance ``foo``.
+
+
 Utility methods
 ===============
 
@@ -597,8 +774,7 @@ If you need to use something similar to the :ttag:`url` template tag in
 your code, Django provides the following method (in the
 ``django.core.urlresolvers`` module):
 
-.. currentmodule:: django.core.urlresolvers
-.. function:: reverse(viewname, urlconf=None, args=None, kwargs=None)
+.. 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
@@ -620,6 +796,14 @@ 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.
 
+.. versionadded:: 1.1
+
+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>`.
+
 .. admonition:: Make sure your views are all correct
 
     As part of working out which URL names map to which patterns, the
@@ -639,7 +823,6 @@ 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:
 
-.. currentmodule:: django.core.urlresolvers
 .. function:: resolve(path, urlconf=None)
 
 ``path`` is the URL path you want to resolve. As with ``reverse()`` above, you