forked from django/django
/
urls.txt
204 lines (143 loc) · 6.88 KB
/
urls.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
======================================
``django.conf.urls`` utility functions
======================================
.. module:: django.conf.urls
patterns()
----------
.. function:: patterns(prefix, pattern_description, ...)
.. deprecated:: 1.8
``urlpatterns`` should be a plain list of :func:`django.conf.urls.url`
instances instead.
A function that takes a prefix, and an arbitrary number of URL patterns, and
returns a list of URL patterns in the format Django needs.
The first argument to ``patterns()`` is a string ``prefix``. Here's the example
URLconf from the :doc:`Django overview </intro/overview>`::
from django.conf.urls import patterns, url
urlpatterns = patterns('',
url(r'^articles/([0-9]{4})/$', 'news.views.year_archive'),
url(r'^articles/([0-9]{4})/([0-9]{2})/$', 'news.views.month_archive'),
url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', 'news.views.article_detail'),
)
In this example, each view has a common prefix -- ``'news.views'``.
Instead of typing that out for each entry in ``urlpatterns``, you can use the
first argument to the ``patterns()`` function to specify a prefix to apply to
each view function.
With this in mind, the above example can be written more concisely as::
from django.conf.urls import patterns, url
urlpatterns = patterns('news.views',
url(r'^articles/([0-9]{4})/$', 'year_archive'),
url(r'^articles/([0-9]{4})/([0-9]{2})/$', 'month_archive'),
url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$', 'article_detail'),
)
Note that you don't put a trailing dot (``"."``) in the prefix. Django puts
that in automatically.
The remaining arguments should be tuples in this format::
(regular expression, Python callback function [, optional_dictionary [, optional_name]])
The ``optional_dictionary`` and ``optional_name`` parameters are described in
:ref:`Passing extra options to view functions <views-extra-options>`.
.. note::
Because ``patterns()`` is a function call, it accepts a maximum of 255
arguments (URL patterns, in this case). This is a limit for all Python
function calls. This is rarely a problem in practice, because you'll
typically structure your URL patterns modularly by using ``include()``
sections. However, on the off-chance you do hit the 255-argument limit,
realize that ``patterns()`` returns a Python list, so you can split up the
construction of the list.
::
urlpatterns = patterns('',
...
)
urlpatterns += patterns('',
...
)
Python lists have unlimited size, so there's no limit to how many URL
patterns you can construct. The only limit is that you can only create 254
at a time (the 255th argument is the initial prefix argument).
static()
--------
.. function:: static.static(prefix, view='django.views.static.serve', **kwargs)
Helper function to return a URL pattern for serving files in debug mode::
from django.conf import settings
from django.conf.urls.static import static
urlpatterns = [
# ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
url()
-----
.. function:: url(regex, view, kwargs=None, name=None, prefix='')
``urlpatterns`` should be a list of ``url()`` instances. For example::
urlpatterns = [
url(r'^index/$', index_view, name="main-view"),
...
]
This function takes five arguments, most of which are optional::
url(regex, view, kwargs=None, name=None, prefix='')
The ``kwargs`` parameter allows you to pass additional arguments to the view
function or method. See :ref:`views-extra-options` for an example.
See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name``
parameter is useful.
The ``prefix`` parameter has the same meaning as the first argument to
``patterns()`` and is only relevant when you're passing a string as the
``view`` parameter.
include()
---------
.. function:: include(module[, namespace=None, app_name=None])
include(pattern_list)
include((pattern_list, app_namespace, instance_namespace))
A function that takes a full Python import path to another URLconf module
that should be "included" in this place. Optionally, the :term:`application
namespace` and :term:`instance namespace` where the entries will be included
into can also be specified.
``include()`` also accepts as an argument either an iterable that returns
URL patterns or a 3-tuple containing such iterable plus the names of the
application and instance namespaces.
:arg module: URLconf module (or module name)
:arg namespace: Instance namespace for the URL entries being included
:type namespace: string
:arg app_name: Application namespace for the URL entries being included
:type app_name: string
:arg pattern_list: Iterable of :func:`django.conf.urls.url` instances
:arg app_namespace: Application namespace for the URL entries being included
:type app_namespace: string
:arg instance_namespace: Instance namespace for the URL entries being included
:type instance_namespace: string
See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`.
handler400
----------
.. data:: handler400
A callable, or a string representing the full Python import path to the view
that should be called if the HTTP client has sent a request that caused an error
condition and a response with a status code of 400.
By default, this is ``'django.views.defaults.bad_request'``. That default
value should suffice.
See the documentation about :ref:`the 400 (bad request) view
<http_bad_request_view>` for more information.
handler403
----------
.. data:: handler403
A callable, or a string representing the full Python import path to the view
that should be called if the user doesn't have the permissions required to
access a resource.
By default, this is ``'django.views.defaults.permission_denied'``. That default
value should suffice.
See the documentation about :ref:`the 403 (HTTP Forbidden) view
<http_forbidden_view>` for more information.
handler404
----------
.. data:: handler404
A callable, or a string representing the full Python import path to the view
that should be called if none of the URL patterns match.
By default, this is ``'django.views.defaults.page_not_found'``. That default
value should suffice.
See the documentation about :ref:`the 404 (HTTP Not Found) view
<http_not_found_view>` for more information.
handler500
----------
.. data:: handler500
A callable, or a string representing the full Python import path to the view
that should be called in case of server errors. Server errors happen when you
have runtime errors in view code.
By default, this is ``'django.views.defaults.server_error'``. That default
value should suffice.
See the documentation about :ref:`the 500 (HTTP Internal Server Error) view
<http_internal_server_error_view>` for more information.