| 1 |
============================================= |
| 2 |
``django.urls`` functions for use in URLconfs |
| 3 |
============================================= |
| 4 |
|
| 5 |
.. module:: django.urls.conf |
| 6 |
:synopsis: Functions for use in URLconfs. |
| 7 |
|
| 8 |
.. currentmodule:: django.urls |
| 9 |
|
| 10 |
``path()`` |
| 11 |
========== |
| 12 |
|
| 13 |
.. function:: path(route, view, kwargs=None, name=None) |
| 14 |
|
| 15 |
Returns an element for inclusion in ``urlpatterns``. For example:: |
| 16 |
|
| 17 |
from django.urls import include, path |
| 18 |
|
| 19 |
urlpatterns = [ |
| 20 |
path("index/", views.index, name="main-view"), |
| 21 |
path("bio/<username>/", views.bio, name="bio"), |
| 22 |
path("articles/<slug:title>/", views.article, name="article-detail"), |
| 23 |
path("articles/<slug:title>/<int:section>/", views.section, name="article-section"), |
| 24 |
path("blog/", include("blog.urls")), |
| 25 |
..., |
| 26 |
] |
| 27 |
|
| 28 |
``route`` |
| 29 |
--------- |
| 30 |
|
| 31 |
The ``route`` argument should be a string or |
| 32 |
:func:`~django.utils.translation.gettext_lazy()` (see |
| 33 |
:ref:`translating-urlpatterns`) that contains a URL pattern. The string |
| 34 |
may contain angle brackets (like ``<username>`` above) to capture part of the |
| 35 |
URL and send it as a keyword argument to the view. The angle brackets may |
| 36 |
include a converter specification (like the ``int`` part of ``<int:section>``) |
| 37 |
which limits the characters matched and may also change the type of the |
| 38 |
variable passed to the view. For example, ``<int:section>`` matches a string |
| 39 |
of decimal digits and converts the value to an ``int``. |
| 40 |
|
| 41 |
When processing a request, Django starts at the first pattern in |
| 42 |
``urlpatterns`` and makes its way down the list, comparing the requested URL |
| 43 |
against each pattern until it finds one that matches. See |
| 44 |
:ref:`how-django-processes-a-request` for more details. |
| 45 |
|
| 46 |
Patterns don't match GET and POST parameters, or the domain name. For example, |
| 47 |
in a request to ``https://www.example.com/myapp/``, the URLconf will look for |
| 48 |
``myapp/``. In a request to ``https://www.example.com/myapp/?page=3``, the |
| 49 |
URLconf will also look for ``myapp/``. |
| 50 |
|
| 51 |
``view`` |
| 52 |
-------- |
| 53 |
|
| 54 |
The ``view`` argument is a view function or the result of |
| 55 |
:meth:`~django.views.generic.base.View.as_view` for class-based views. It can |
| 56 |
also be a :func:`django.urls.include`. |
| 57 |
|
| 58 |
When Django finds a matching pattern, it calls the specified view function with |
| 59 |
an :class:`~django.http.HttpRequest` object as the first argument and any |
| 60 |
"captured" values from the route as keyword arguments. |
| 61 |
|
| 62 |
``kwargs`` |
| 63 |
---------- |
| 64 |
|
| 65 |
The ``kwargs`` argument allows you to pass additional arguments to the view |
| 66 |
function or method. See :ref:`views-extra-options` for an example. |
| 67 |
|
| 68 |
``name`` |
| 69 |
-------- |
| 70 |
|
| 71 |
Naming your URL lets you refer to it unambiguously from elsewhere in Django, |
| 72 |
especially from within templates. This powerful feature allows you to make |
| 73 |
global changes to the URL patterns of your project while only touching a single |
| 74 |
file. |
| 75 |
|
| 76 |
See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name`` |
| 77 |
argument is useful. |
| 78 |
|
| 79 |
``re_path()`` |
| 80 |
============= |
| 81 |
|
| 82 |
.. function:: re_path(route, view, kwargs=None, name=None) |
| 83 |
|
| 84 |
Returns an element for inclusion in ``urlpatterns``. For example:: |
| 85 |
|
| 86 |
from django.urls import include, re_path |
| 87 |
|
| 88 |
urlpatterns = [ |
| 89 |
re_path(r"^index/$", views.index, name="index"), |
| 90 |
re_path(r"^bio/(?P<username>\w+)/$", views.bio, name="bio"), |
| 91 |
re_path(r"^blog/", include("blog.urls")), |
| 92 |
..., |
| 93 |
] |
| 94 |
|
| 95 |
The ``route`` argument should be a string or |
| 96 |
:func:`~django.utils.translation.gettext_lazy()` (see |
| 97 |
:ref:`translating-urlpatterns`) that contains a regular expression compatible |
| 98 |
with Python's :py:mod:`re` module. Strings typically use raw string syntax |
| 99 |
(``r''``) so that they can contain sequences like ``\d`` without the need to |
| 100 |
escape the backslash with another backslash. When a match is made, captured |
| 101 |
groups from the regular expression are passed to the view -- as named arguments |
| 102 |
if the groups are named, and as positional arguments otherwise. The values are |
| 103 |
passed as strings, without any type conversion. |
| 104 |
|
| 105 |
When a ``route`` ends with ``$`` the whole requested URL, matching against |
| 106 |
:attr:`~django.http.HttpRequest.path_info`, must match the regular expression |
| 107 |
pattern (:py:func:`re.fullmatch` is used). |
| 108 |
|
| 109 |
The ``view``, ``kwargs`` and ``name`` arguments are the same as for |
| 110 |
:func:`~django.urls.path()`. |
| 111 |
|
| 112 |
``include()`` |
| 113 |
============= |
| 114 |
|
| 115 |
.. function:: include(module, namespace=None) |
| 116 |
include(pattern_list) |
| 117 |
include((pattern_list, app_namespace), namespace=None) |
| 118 |
|
| 119 |
A function that takes a full Python import path to another URLconf module |
| 120 |
that should be "included" in this place. Optionally, the :term:`application |
| 121 |
namespace` and :term:`instance namespace` where the entries will be included |
| 122 |
into can also be specified. |
| 123 |
|
| 124 |
Usually, the application namespace should be specified by the included |
| 125 |
module. If an application namespace is set, the ``namespace`` argument |
| 126 |
can be used to set a different instance namespace. |
| 127 |
|
| 128 |
``include()`` also accepts as an argument either an iterable that returns |
| 129 |
URL patterns or a 2-tuple containing such iterable plus the names of the |
| 130 |
application namespaces. |
| 131 |
|
| 132 |
:arg module: URLconf module (or module name) |
| 133 |
:arg namespace: Instance namespace for the URL entries being included |
| 134 |
:type namespace: str |
| 135 |
:arg pattern_list: Iterable of :func:`~django.urls.path` and/or :func:`~django.urls.re_path` instances. |
| 136 |
:arg app_namespace: Application namespace for the URL entries being included |
| 137 |
:type app_namespace: str |
| 138 |
|
| 139 |
See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`. |
| 140 |
|
| 141 |
``register_converter()`` |
| 142 |
======================== |
| 143 |
|
| 144 |
.. function:: register_converter(converter, type_name) |
| 145 |
|
| 146 |
The function for registering a converter for use in :func:`~django.urls.path()` |
| 147 |
``route``\s. |
| 148 |
|
| 149 |
The ``converter`` argument is a converter class, and ``type_name`` is the |
| 150 |
converter name to use in path patterns. See |
| 151 |
:ref:`registering-custom-path-converters` for an example. |
| 152 |
|
| 153 |
.. deprecated:: 5.1 |
| 154 |
|
| 155 |
Overriding existing converters is deprecated. |
| 156 |
|
| 157 |
================================================== |
| 158 |
``django.conf.urls`` functions for use in URLconfs |
| 159 |
================================================== |
| 160 |
|
| 161 |
.. module:: django.conf.urls |
| 162 |
|
| 163 |
``static()`` |
| 164 |
============ |
| 165 |
|
| 166 |
.. function:: static.static(prefix, view=django.views.static.serve, **kwargs) |
| 167 |
|
| 168 |
Helper function to return a URL pattern for serving files in debug mode:: |
| 169 |
|
| 170 |
from django.conf import settings |
| 171 |
from django.conf.urls.static import static |
| 172 |
|
| 173 |
urlpatterns = [ |
| 174 |
# ... the rest of your URLconf goes here ... |
| 175 |
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) |
| 176 |
|
| 177 |
``handler400`` |
| 178 |
============== |
| 179 |
|
| 180 |
.. data:: handler400 |
| 181 |
|
| 182 |
A callable, or a string representing the full Python import path to the view |
| 183 |
that should be called if the HTTP client has sent a request that caused an error |
| 184 |
condition and a response with a status code of 400. |
| 185 |
|
| 186 |
By default, this is :func:`django.views.defaults.bad_request`. If you |
| 187 |
implement a custom view, be sure it accepts ``request`` and ``exception`` |
| 188 |
arguments and returns an :class:`~django.http.HttpResponseBadRequest`. |
| 189 |
|
| 190 |
``handler403`` |
| 191 |
============== |
| 192 |
|
| 193 |
.. data:: handler403 |
| 194 |
|
| 195 |
A callable, or a string representing the full Python import path to the view |
| 196 |
that should be called if the user doesn't have the permissions required to |
| 197 |
access a resource. |
| 198 |
|
| 199 |
By default, this is :func:`django.views.defaults.permission_denied`. If you |
| 200 |
implement a custom view, be sure it accepts ``request`` and ``exception`` |
| 201 |
arguments and returns an :class:`~django.http.HttpResponseForbidden`. |
| 202 |
|
| 203 |
``handler404`` |
| 204 |
============== |
| 205 |
|
| 206 |
.. data:: handler404 |
| 207 |
|
| 208 |
A callable, or a string representing the full Python import path to the view |
| 209 |
that should be called if none of the URL patterns match. |
| 210 |
|
| 211 |
By default, this is :func:`django.views.defaults.page_not_found`. If you |
| 212 |
implement a custom view, be sure it accepts ``request`` and ``exception`` |
| 213 |
arguments and returns an :class:`~django.http.HttpResponseNotFound`. |
| 214 |
|
| 215 |
``handler500`` |
| 216 |
============== |
| 217 |
|
| 218 |
.. data:: handler500 |
| 219 |
|
| 220 |
A callable, or a string representing the full Python import path to the view |
| 221 |
that should be called in case of server errors. Server errors happen when you |
| 222 |
have runtime errors in view code. |
| 223 |
|
| 224 |
By default, this is :func:`django.views.defaults.server_error`. If you |
| 225 |
implement a custom view, be sure it accepts a ``request`` argument and returns |
| 226 |
an :class:`~django.http.HttpResponseServerError`. |