summaryrefslogtreecommitdiff
path: root/docs/topics/http/urls.txt
diff options
context:
space:
mode:
Diffstat (limited to 'docs/topics/http/urls.txt')
-rw-r--r--docs/topics/http/urls.txt105
1 files changed, 93 insertions, 12 deletions
diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt
index 5a2980f9d2..1f499909ee 100644
--- a/docs/topics/http/urls.txt
+++ b/docs/topics/http/urls.txt
@@ -1,5 +1,3 @@
-.. _topics-http-urls:
-
==============
URL dispatcher
==============
@@ -335,7 +333,7 @@ The view prefix
You can specify a common prefix in your ``patterns()`` call, to cut down on
code duplication.
-Here's the example URLconf from the :ref:`Django overview <intro-overview>`::
+Here's the example URLconf from the :doc:`Django overview </intro/overview>`::
from django.conf.urls.defaults import *
@@ -537,8 +535,8 @@ In this example, for a request to ``/blog/2005/``, Django will call the
year='2005', foo='bar'
-This technique is used in :ref:`generic views <ref-generic-views>` and in the
-:ref:`syndication framework <ref-contrib-syndication>` to pass metadata and
+This technique is used in :doc:`generic views </ref/generic-views>` and in the
+:doc:`syndication framework </ref/contrib/syndication>` to pass metadata and
options to views.
.. admonition:: Dealing with conflicts
@@ -827,17 +825,80 @@ namespaces into URLs on specific application instances, according to the
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:
+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 ``reverse()`` above, you
-don't need to worry about the ``urlconf`` parameter. The function returns the
-triple (view function, arguments, keyword arguments).
+``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:`django.core.urlresolvers.ResolverMatch` object that allows you
+to access various meta-data about the resolved URL.
+
+.. 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.
-For example, it can be used for testing if a view would raise a ``Http404``
-error before redirecting to it::
+ .. 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:`~django.core.urlresolvers.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:`~django.core.urlresolvers.ResolverMatch` object can also be
+assigned to a triple::
+
+ func, args, kwargs = resolve('/some/path/')
+
+.. versionchanged:: 1.3
+ Triple-assignment exists for backwards-compatibility. Prior to
+ Django 1.3, :func:`~django.core.urlresolvers.resolve` returned a
+ triple containing (view function, arguments, keyword arguments);
+ the :class:`~django.core.urlresolvers.ResolverMatch` object (as
+ well as the namespace and pattern information it provides) is not
+ available in earlier Django releases.
+
+One possible use of :func:`~django.core.urlresolvers.resolve` would be
+to testing if a view would raise a ``Http404`` error before
+redirecting to it::
from urlparse import urlparse
from django.core.urlresolvers import resolve
@@ -858,9 +919,29 @@ error before redirecting to it::
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()
+
+.. versionadded:: 1.0
+
+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 webserver, this is always ``"/"``, but it can be
+changed, for instance by using ``django.root`` (see :ref:`How to use
+Django with Apache and mod_python <howto-deployment-modpython>`).