mirror of https://github.com/django/django.git
Refactored URL mapping documentation.
Reorganized topic document so it introduces concepts form simple to more complex. Moved reference parts to their own documents.
This commit is contained in:
Ramiro Morales
parent
8a2216648f
commit
b6b8a3f66b
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 ``"/"``.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
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.
|
||||
|
||||
See the documentation on :ref:`customizing error views
|
||||
<customizing-error-views>` for more details.
|
||||
<customizing-error-views>` for the full details.
|
||||
|
||||
handler403
|
||||
----------
|
||||
Such values can be set in your root URLconf. Setting these variables in any
|
||||
other URLconf will have no effect.
|
||||
|
||||
.. data:: handler403
|
||||
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.
|
||||
|
||||
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.
|
||||
The variables are:
|
||||
|
||||
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.
|
||||
* ``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
|
||||
==============================================
|
||||
URL namespaces of included URLconfs can be specified in two ways.
|
||||
|
||||
.. currentmodule:: django.core.urlresolvers
|
||||
Firstly, you can provide the application and instance namespace as arguments
|
||||
to ``include()`` when you construct your URL patterns. For example,::
|
||||
|
||||
reverse()
|
||||
---------
|
||||
(r'^help/', include('apps.help.urls', namespace='foo', app_name='bar')),
|
||||
|
||||
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):
|
||||
This will include the URLs defined in ``apps.help.urls`` into the application
|
||||
namespace ``bar``, with the instance namespace ``foo``.
|
||||
|
||||
.. function:: reverse(viewname, [urlconf=None, args=None, kwargs=None, current_app=None])
|
||||
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::
|
||||
|
||||
``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::
|
||||
(<patterns object>, <application namespace>, <instance namespace>)
|
||||
|
||||
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()
|
||||
---------
|
||||
|
||||
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 ``"/"``.
|
||||
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``.
|
||||
|
|
|
|||
Loading…
Reference in New Issue