diff -r e70cbd83611a docs/topics/http/urls.txt
--- a/docs/topics/http/urls.txt Thu Jul 16 13:16:13 2009 -0300
+++ b/docs/topics/http/urls.txt Thu Jul 16 18:42:30 2009 -0300
@@ -3,6 +3,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
@@ -182,11 +184,13 @@
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 @@
.. 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 @@
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.
@@ -252,6 +260,8 @@
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
@@ -263,12 +273,14 @@
include
-------
+.. function:: include()
+
A function that takes a full Python import path to another URLconf module that
should be "included" in this place.
.. versionadded:: 1.1
-:meth:``include`` also accepts as an argument an iterable that returns URL
+:func:`include` also accepts as an argument an iterable that returns URL
patterns.
See `Including other URLconfs`_ below.
@@ -421,7 +433,7 @@
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 ``included()`` into your projects ``urlpatterns`` when you
+attribute that you ``include()`` into your projects ``urlpatterns`` when you
deploy the admin instance.
.. _`Django Web site`: http://www.djangoproject.com/
@@ -451,7 +463,7 @@
Defining URL Namespaces
-----------------------
-When you need to deploying multiple instances of a single application, it can
+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 _`named URL patterns `, since
multiple instances of a single application will share named URLs. Namespaces
@@ -466,15 +478,15 @@
* An **instance namespace**. This identifies a specific instance of an
application. Instance namespaces should be unique across your entire
- project. However, and instance namespace can be the same as the
+ 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 applicaiton and instance namespace as arguments
-to the ``include()`` when you construct your URL patterns. For example,::
+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')),
@@ -494,7 +506,7 @@
an admin site, plus the name of the admin instance, and the application
namespace ``admin``.
-Once you have defined namespace URLs, you can reverse them. For details on
+Once you have defined namespaced URLs, you can reverse them. For details on
reversing namespaced urls, see the documentation on :ref:`reversing namespaced
URLs `.
@@ -679,18 +691,18 @@
.. 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``.
+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
+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. Django then looks for a matching application namespace (in this
+ 1. It looks for a matching application namespace (in this
example, ``myapp``). This will yield a list of instances of that
application.
@@ -702,15 +714,15 @@
template.
The current application can also be specified manually as an argument
- to the :method:``reverse()`` function.
+ 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``)
+ 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 it's instance name may be.
+ deployed instance of the application, whatever its instance name may be.
5. If the provided namespace doesn't match an application namespace in
step 2, Django will attempt a direct lookup of the namespace as an
@@ -762,7 +774,6 @@
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, current_app=None)
``viewname`` is either the function name (either a function reference, or the
@@ -812,7 +823,6 @@
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