|
|
@@ -2,8 +2,6 @@
|
|
|
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.
|
|
|
@@ -160,7 +158,8 @@ vs. non-named groups in a regular expression:
|
|
|
|
|
|
2. Otherwise, it will pass all non-named arguments as positional arguments.
|
|
|
|
|
|
-In both cases, any extra keyword arguments that have been given as per `Passing extra options to view functions`_ (below) will also be passed to the view.
|
|
|
+In both cases, any extra keyword arguments that have been given as per `Passing
|
|
|
+extra options to view functions`_ (below) will also be passed to the view.
|
|
|
|
|
|
What the URLconf searches against
|
|
|
=================================
|
|
|
@@ -215,7 +214,6 @@ Performance
|
|
|
Each regular expression in a ``urlpatterns`` is compiled the first time it's
|
|
|
accessed. This makes the system blazingly fast.
|
|
|
|
|
|
-
|
|
|
Syntax of the urlpatterns variable
|
|
|
==================================
|
|
|
|
|
|
@@ -223,154 +221,35 @@ Syntax of the urlpatterns variable
|
|
|
:func:`django.conf.urls.patterns`. Always use ``patterns()`` to create
|
|
|
the ``urlpatterns`` variable.
|
|
|
|
|
|
-``django.conf.urls`` utility functions
|
|
|
-======================================
|
|
|
-
|
|
|
-.. module:: django.conf.urls
|
|
|
-
|
|
|
-.. deprecated:: 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
|
|
|
-`The view prefix`_ below.
|
|
|
-
|
|
|
-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
|
|
|
-`Passing extra options to view functions`_ below.
|
|
|
-
|
|
|
-.. 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 `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 `Including other URLconfs`_ below.
|
|
|
-
|
|
|
Error handling
|
|
|
==============
|
|
|
|
|
|
When Django can't find a regex matching the requested URL, or when an
|
|
|
-exception is raised, Django will invoke an error-handling view. The
|
|
|
-views to use for these cases are specified by three variables which can
|
|
|
-be set in your root URLconf. Setting these variables in any other
|
|
|
-URLconf will have no effect.
|
|
|
+exception is raised, Django will invoke an error-handling view.
|
|
|
|
|
|
-See the documentation on :ref:`customizing error views
|
|
|
-<customizing-error-views>` for more details.
|
|
|
+The views to use for these cases are specified by three variables. Their
|
|
|
+default values should suffice for most projects, but further customization is
|
|
|
+possible by assigning values to them.
|
|
|
|
|
|
-handler403
|
|
|
-----------
|
|
|
+See the documentation on :ref:`customizing error views
|
|
|
+<customizing-error-views>` for the full details.
|
|
|
|
|
|
-.. data:: handler403
|
|
|
+Such values can be set in your root URLconf. Setting these variables in any
|
|
|
+other URLconf will have no effect.
|
|
|
|
|
|
-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.
|
|
|
+Values must be callables, or strings representing the full Python import path
|
|
|
+to the view that should be called to handle the error condition at hand.
|
|
|
|
|
|
-By default, this is ``'django.views.defaults.permission_denied'``. That default
|
|
|
-value should suffice.
|
|
|
+The variables are:
|
|
|
|
|
|
-See the documentation about :ref:`the 403 (HTTP Forbidden) view
|
|
|
-<http_forbidden_view>` for more information.
|
|
|
+* ``handler404`` -- See :data:`django.conf.urls.handler404`.
|
|
|
+* ``handler500`` -- See :data:`django.conf.urls.handler500`.
|
|
|
+* ``handler403`` -- See :data:`django.conf.urls.handler403`.
|
|
|
|
|
|
.. 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.
|
|
|
+.. _urlpatterns-view-prefix:
|
|
|
|
|
|
The view prefix
|
|
|
===============
|
|
|
@@ -437,6 +316,8 @@ New::
|
|
|
(r'^tag/(?P<tag>\w+)/$', 'tag'),
|
|
|
)
|
|
|
|
|
|
+.. _including-other-urlconfs:
|
|
|
+
|
|
|
Including other URLconfs
|
|
|
========================
|
|
|
|
|
|
@@ -459,13 +340,14 @@ itself. It includes a number of other URLconfs::
|
|
|
|
|
|
Note that the regular expressions in this example don't have a ``$``
|
|
|
(end-of-string match character) but do include a trailing slash. Whenever
|
|
|
-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.
|
|
|
+Django encounters ``include()`` (:func:`django.conf.urls.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.
|
|
|
|
|
|
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::
|
|
|
+URLconf Python module defining them as the ``include()`` argument but by using
|
|
|
+directly the pattern list as returned by :func:`~django.conf.urls.patterns`
|
|
|
+instead. For example::
|
|
|
|
|
|
from django.conf.urls import patterns, url, include
|
|
|
|
|
|
@@ -510,57 +392,7 @@ 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:`~django.contrib.admin.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>`.
|
|
|
+.. _views-extra-options:
|
|
|
|
|
|
Passing extra options to view functions
|
|
|
=======================================
|
|
|
@@ -698,10 +530,10 @@ 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
|
|
|
-``archive`` view, Django's reverse URL matcher would get confused, because *two*
|
|
|
-URL patterns point at that view.
|
|
|
+URL matching (through the :func:`~django.db.models.permalink` decorator or the
|
|
|
+:ttag:`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* URL patterns 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
|
|
|
@@ -741,10 +573,36 @@ 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:
|
|
|
+.. _topics-http-defining-url-namespaces:
|
|
|
|
|
|
URL namespaces
|
|
|
---------------
|
|
|
+==============
|
|
|
+
|
|
|
+Introduction
|
|
|
+------------
|
|
|
+
|
|
|
+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:
|
|
|
+
|
|
|
+.. glossary::
|
|
|
+
|
|
|
+ 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``.
|
|
|
+
|
|
|
+ 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``.
|
|
|
|
|
|
Namespaced URLs are specified using the ``:`` operator. For example, the main
|
|
|
index page of the admin application is referenced using ``admin:index``. This
|
|
|
@@ -754,6 +612,11 @@ 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``.
|
|
|
|
|
|
+.. _topics-http-reversing-url-namespaces:
|
|
|
+
|
|
|
+Reversing namespaced URLs
|
|
|
+-------------------------
|
|
|
+
|
|
|
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:
|
|
|
|
|
|
@@ -787,6 +650,9 @@ 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.
|
|
|
|
|
|
+Example
|
|
|
+~~~~~~~
|
|
|
+
|
|
|
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
|
|
|
@@ -818,209 +684,28 @@ following would happen:
|
|
|
|
|
|
* ``foo:index`` will again resolve to the index page of the instance ``foo``.
|
|
|
|
|
|
+URL namespaces and included URLconfs
|
|
|
+------------------------------------
|
|
|
|
|
|
-``django.core.urlresolvers`` utility functions
|
|
|
-==============================================
|
|
|
-
|
|
|
-.. currentmodule:: 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
|
|
|
-`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`_
|
|
|
-
|
|
|
-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()
|
|
|
----------
|
|
|
+URL namespaces of included URLconfs can be specified in two ways.
|
|
|
|
|
|
-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
|
|
|
+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')),
|
|
|
|
|
|
-permalink()
|
|
|
------------
|
|
|
+This will include the URLs defined in ``apps.help.urls`` into the application
|
|
|
+namespace ``bar``, with the instance namespace ``foo``.
|
|
|
|
|
|
-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.
|
|
|
+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::
|
|
|
|
|
|
-get_script_prefix()
|
|
|
--------------------
|
|
|
+ (<patterns object>, <application namespace>, <instance namespace>)
|
|
|
|
|
|
-.. 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 ``"/"``.
|
|
|
+This will include the nominated URL patterns into the given application and
|
|
|
+instance namespace. For example, the ``urls`` attribute of Django's
|
|
|
+:class:`~django.contrib.admin.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``.
|
Ramiro Morales