mirror of
https://github.com/django/django.git
synced 2024-12-22 17:16:24 +00:00
265 lines
8.6 KiB
Plaintext
265 lines
8.6 KiB
Plaintext
=================================
|
|
``django.urls`` utility functions
|
|
=================================
|
|
|
|
.. module:: django.urls
|
|
|
|
``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 used in the URLconf. For example, given the following
|
|
``url``::
|
|
|
|
from news import views
|
|
|
|
path("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:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> 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:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> reverse("cities", args=["Orléans"])
|
|
'.../Orl%C3%A9ans/'
|
|
|
|
Applying further encoding (such as :func:`urllib.parse.quote`) to the output
|
|
of ``reverse()`` may produce undesirable results.
|
|
|
|
.. admonition:: Reversing class-based views by view object
|
|
|
|
The view object can also be the result of calling
|
|
:meth:`~django.views.generic.base.View.as_view` if the same view object is
|
|
used in the URLConf. Following the original example, the view object could
|
|
be defined as:
|
|
|
|
.. code-block:: python
|
|
:caption: ``news/views.py``
|
|
|
|
from django.views import View
|
|
|
|
|
|
class ArchiveView(View): ...
|
|
|
|
|
|
archive = ArchiveView.as_view()
|
|
|
|
However, remember that namespaced views cannot be reversed by view object.
|
|
|
|
``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
|
|
|
|
All keyword arguments that would be passed to the view function, i.e.
|
|
:attr:`~ResolverMatch.captured_kwargs` and
|
|
:attr:`~ResolverMatch.extra_kwargs`.
|
|
|
|
.. attribute:: ResolverMatch.captured_kwargs
|
|
|
|
The captured keyword arguments that would be passed to the view
|
|
function, as parsed from the URL.
|
|
|
|
.. attribute:: ResolverMatch.extra_kwargs
|
|
|
|
The additional keyword arguments that would be passed to the view
|
|
function.
|
|
|
|
.. attribute:: ResolverMatch.url_name
|
|
|
|
The name of the URL pattern that matches the URL.
|
|
|
|
.. attribute:: ResolverMatch.route
|
|
|
|
The route of the matching URL pattern.
|
|
|
|
For example, if ``path('users/<id>/', ...)`` is the matching pattern,
|
|
``route`` will contain ``'users/<id>/'``.
|
|
|
|
.. attribute:: ResolverMatch.tried
|
|
|
|
The list of URL patterns tried before the URL either matched one or
|
|
exhausted available patterns.
|
|
|
|
.. 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 urllib.parse import urlsplit
|
|
from django.urls import resolve
|
|
from django.http import Http404, HttpResponseRedirect
|
|
|
|
|
|
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(urlsplit(next).path)
|
|
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 ``"/"``.
|
|
|
|
.. warning::
|
|
|
|
This function **cannot** be used outside of the request-response cycle
|
|
since it relies on values initialized during that cycle.
|