mirror of https://github.com/django/django.git
216 lines
7.3 KiB
Plaintext
216 lines
7.3 KiB
Plaintext
=================================
|
|
``django.urls`` utility functions
|
|
=================================
|
|
|
|
.. module:: django.urls
|
|
|
|
.. deprecated:: 1.10
|
|
|
|
In older versions, these functions are located in
|
|
``django.core.urlresolvers``. Importing from the old location will continue
|
|
to work until Django 2.0.
|
|
|
|
``reverse()``
|
|
=============
|
|
|
|
If you need to use something similar to the :ttag:`url` template tag in
|
|
your code, Django provides the following function:
|
|
|
|
.. function:: reverse(viewname, urlconf=None, args=None, kwargs=None, current_app=None)
|
|
|
|
``viewname`` can be a :ref:`URL pattern name <naming-url-patterns>` or the
|
|
callable view object. For example, given the following ``url``::
|
|
|
|
from news import views
|
|
|
|
url(r'^archive/$', views.archive, name='news-archive')
|
|
|
|
you can use any of the following to reverse the URL::
|
|
|
|
# using the named URL
|
|
reverse('news-archive')
|
|
|
|
# passing a callable object
|
|
# (This is discouraged because you can't reverse namespaced views this way.)
|
|
from news import views
|
|
reverse(views.archive)
|
|
|
|
If the URL accepts arguments, you may pass them in ``args``. For example::
|
|
|
|
from django.urls import reverse
|
|
|
|
def myview(request):
|
|
return HttpResponseRedirect(reverse('arch-summary', args=[1945]))
|
|
|
|
You can also pass ``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.
|
|
|
|
If no match can be made, ``reverse()`` raises a
|
|
:class:`~django.urls.NoReverseMatch` exception.
|
|
|
|
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>`.
|
|
|
|
The ``urlconf`` argument is the URLconf module containing the url patterns to
|
|
use for reversing. By default, the root URLconf for the current thread is used.
|
|
|
|
.. note::
|
|
|
|
The string returned by ``reverse()`` is already
|
|
:ref:`urlquoted <uri-and-iri-handling>`. For example::
|
|
|
|
>>> reverse('cities', args=['Orléans'])
|
|
'.../Orl%C3%A9ans/'
|
|
|
|
Applying further encoding (such as :meth:`~django.utils.http.urlquote` or
|
|
``urllib.quote``) to the output of ``reverse()`` may produce undesirable
|
|
results.
|
|
|
|
``reverse_lazy()``
|
|
==================
|
|
|
|
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 ``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.urls.reverse`, you don't need to worry about the ``urlconf``
|
|
parameter. The function returns a :class:`ResolverMatch` object that allows you
|
|
to access various metadata about the resolved URL.
|
|
|
|
If the URL does not resolve, the function raises a
|
|
:exc:`~django.urls.Resolver404` exception (a subclass of
|
|
:class:`~django.http.Http404`) .
|
|
|
|
.. 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.app_names
|
|
|
|
The list of individual namespace components in the full
|
|
application namespace for the URL pattern that matches the URL.
|
|
For example, if the ``app_name`` is ``'foo:bar'``, then ``app_names``
|
|
will be ``['foo', 'bar']``.
|
|
|
|
.. 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']``.
|
|
|
|
.. attribute:: ResolverMatch.view_name
|
|
|
|
The name of the view that matches the URL, including the namespace if
|
|
there is one.
|
|
|
|
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.urls.resolve` would be to test whether a
|
|
view would raise a ``Http404`` error before redirecting to it::
|
|
|
|
from django.urls import resolve
|
|
from django.http import HttpResponseRedirect, Http404
|
|
from django.utils.six.moves.urllib.parse import urlparse
|
|
|
|
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
|
|
|
|
``get_script_prefix()``
|
|
=======================
|
|
|
|
.. function:: get_script_prefix()
|
|
|
|
Normally, you should always use :func:`~django.urls.reverse` 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.urls.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 ``"/"``.
|