Debian Codegraph @

docs/ref/urls.txt

raw
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`.