django/docs/ref/urls.txt

======================================
``django.conf.urls`` utility functions
======================================

.. module:: django.conf.urls

.. versionchanged:: 1.4
    Starting with Django 1.4 functions ``patterns``, ``url``, ``include`` plus
    the ``handler*`` symbols described below live in the ``django.conf.urls``
    module.

    Until Django 1.3 they were located in ``django.conf.urls.defaults``. You
    still can import them from there but it will be removed in Django 1.6.

patterns()
----------

.. function:: patterns(prefix, pattern_description, ...)

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``. See
:ref:`The view prefix <urlpatterns-view-prefix>`.

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).

url()
-----

.. function:: url(regex, view, kwargs=None, name=None, prefix='')

You can use the ``url()`` function, instead of a tuple, as an argument to
``patterns()``. This is convenient if you want to specify a name without the
optional extra arguments dictionary. For example::

    urlpatterns = patterns('',
        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='')

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 or pattern_list>)

A function that takes a full Python import path to another URLconf module that
should be "included" in this place.

:func:`include` also accepts as an argument an iterable that returns URL
patterns.

See :ref:`Including other URLconfs <including-other-urlconfs>`.

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.

.. versionadded:: 1.4
    ``handler403`` is new in Django 1.4.

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.