urls.txt 8.1 KB

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