mirror of
https://github.com/django/django.git
synced 2024-11-30 07:06:18 +01:00
235 lines
8.1 KiB
Plaintext
235 lines
8.1 KiB
Plaintext
======================================
|
|
``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)
|
|
|
|
.. versionchanged:: 1.8
|
|
|
|
The ``view`` argument changed from a string
|
|
(``'django.views.static.serve'``) to the function.
|
|
|
|
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.
|
|
|
|
.. deprecated:: 1.8
|
|
|
|
Support for string ``view`` arguments is deprecated and will be removed in
|
|
Django 1.10. Pass the callable instead.
|
|
|
|
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), namespace=None)
|
|
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.
|
|
|
|
Usually, the application namespace should be specified by the included
|
|
module. If an application namespace is set, the ``namespace`` argument
|
|
can be used to set a different instance namespace.
|
|
|
|
``include()`` also accepts as an argument either an iterable that returns
|
|
URL patterns, a 2-tuple containing such iterable plus the names of the
|
|
application namespaces, or a 3-tuple containing the iterable and the names
|
|
of both the application and instance namespace.
|
|
|
|
: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`.
|
|
|
|
.. deprecated:: 1.9
|
|
|
|
Support for the ``app_name`` argument is deprecated and will be removed in
|
|
Django 2.0. Specify the ``app_name`` as explained in
|
|
:ref:`namespaces-and-include` instead.
|
|
|
|
Support for passing a 3-tuple is also deprecated and will be removed in
|
|
Django 2.0. Pass a 2-tuple containing the pattern list and application
|
|
namespace, and use the ``namespace`` argument instead.
|
|
|
|
Lastly, support for an instance namespace without an application namespace
|
|
has been deprecated and will be removed in Django 2.0. Specify the
|
|
application namespace or remove the instance namespace.
|
|
|
|
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.
|