Overview¶

To design URLs for an app, you create a Python module informally called aURLconf (URL configuration). This module is pure Python code and is asimple mapping between URL patterns (simple regular expressions) to Pythonfunctions (your views).

This mapping can be as short or as long as needed. It can reference othermappings. And, because it’s pure Python code, it can be constructeddynamically.

Django also provides a way to translate URLs according to the activelanguage. See theinternationalization documentation for more information.

How Django processes a request¶

When a user requests a page from your Django-powered site, this is thealgorithm the system follows to determine which Python code to execute:

1. Django determines the root URLconf module to use. Ordinarily,this is the value of theROOT_URLCONF setting, but if the incomingHttpRequest object has aurlconfattribute (set by middleware), its value will be used in place of theROOT_URLCONF setting.
2. Django loads that Python module and looks for the variableurlpatterns. This should be a Python list ofdjango.conf.urls.url()instances.
3. Django runs through each URL pattern, in order, and stops at the firstone that matches the requested URL.
4. Once one of the regexes matches, Django imports and calls the given view,which is a simple Python function (or aclass-based view). The view gets passed the followingarguments:
   • An instance ofHttpRequest.
   • If the matched regular expression returned no named groups, then thematches from the regular expression are provided as positional arguments.
   • The keyword arguments are made up of any named groups matched by theregular expression, overridden by any arguments specified in the optionalkwargs argument todjango.conf.urls.url().
5. If no regex matches, or if an exception is raised during anypoint in this process, Django invokes an appropriateerror-handling view. SeeError handling below.

Example¶

Here’s a sample URLconf:

fromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^articles/2003/$',views.special_case_2003),url(r'^articles/([0-9]{4})/$',views.year_archive),url(r'^articles/([0-9]{4})/([0-9]{2})/$',views.month_archive),url(r'^articles/([0-9]{4})/([0-9]{2})/([0-9]+)/$',views.article_detail),]

Notes:

• To capture a value from the URL, just put parenthesis around it.
• There’s no need to add a leading slash, because every URL has that. Forexample, it’s^articles, not^/articles.
• The'r' in front of each regular expression string is optional butrecommended. It tells Python that a string is “raw” – that nothing inthe string should be escaped. SeeDive Into Python’s explanation.

Example requests:

• A request to/articles/2005/03/ would match the third entry in thelist. Django would call the functionviews.month_archive(request,'2005','03').
• /articles/2005/3/ would not match any URL patterns, because thethird entry in the list requires two digits for the month.
• /articles/2003/ would match the first pattern in the list, not thesecond one, because the patterns are tested in order, and the first oneis the first test to pass. Feel free to exploit the ordering to insertspecial cases like this. Here, Django would call the functionviews.special_case_2003(request)
• /articles/2003 would not match any of these patterns, because eachpattern requires that the URL end with a slash.
• /articles/2003/03/03/ would match the final pattern. Django would callthe functionviews.article_detail(request,'2003','03','03').

Named groups¶

The above example used simple,non-named regular-expression groups (viaparenthesis) to capture bits of the URL and pass them aspositional argumentsto a view. In more advanced usage, it’s possible to usenamedregular-expression groups to capture URL bits and pass them askeywordarguments to a view.

In Python regular expressions, the syntax for named regular-expression groupsis(?P<name>pattern), wherename is the name of the group andpattern is some pattern to match.

Here’s the above example URLconf, rewritten to use named groups:

fromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^articles/2003/$',views.special_case_2003),url(r'^articles/(?P<year>[0-9]{4})/$',views.year_archive),url(r'^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/$',views.month_archive),url(r'^articles/(?P<year>[0-9]{4})/(?P<month>[0-9]{2})/(?P<day>[0-9]{2})/$',views.article_detail),]

This accomplishes exactly the same thing as the previous example, with onesubtle difference: The captured values are passed to view functions as keywordarguments rather than positional arguments. For example:

• A request to/articles/2005/03/ would call the functionviews.month_archive(request,year='2005',month='03'), insteadofviews.month_archive(request,'2005','03').
• A request to/articles/2003/03/03/ would call the functionviews.article_detail(request,year='2003',month='03',day='03').

In practice, this means your URLconfs are slightly more explicit and less proneto argument-order bugs – and you can reorder the arguments in your views’function definitions. Of course, these benefits come at the cost of brevity;some developers find the named-group syntax ugly and too verbose.

What the URLconf searches against¶

The URLconf searches against the requested URL, as a normal Python string. Thisdoes not include GET or POST parameters, or the domain name.

For example, in a request tohttps://www.example.com/myapp/, the URLconfwill look formyapp/.

In a request tohttps://www.example.com/myapp/?page=3, the URLconf will lookformyapp/.

The URLconf doesn’t look at the request method. In other words, all requestmethods –POST,GET,HEAD, etc. – will be routed to the samefunction for the same URL.

Captured arguments are always strings¶

Each captured argument is sent to the view as a plain Python string, regardlessof what sort of match the regular expression makes. For example, in thisURLconf line:

url(r'^articles/(?P<year>[0-9]{4})/$',views.year_archive),

…theyear argument passed toviews.year_archive() will be a string,

not an integer, even though the[0-9]{4} will only match integer strings.

Specifying defaults for view arguments¶

A convenient trick is to specify default parameters for your views’ arguments.Here’s an example URLconf and view:

# URLconffromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^blog/$',views.page),url(r'^blog/page(?P<num>[0-9]+)/$',views.page),]# View (in blog/views.py)defpage(request,num="1"):# Output the appropriate page of blog entries, according to num....

In the above example, both URL patterns point to the same view –views.page – but the first pattern doesn’t capture anything from theURL. If the first pattern matches, thepage() function will use itsdefault argument fornum,"1". If the second pattern matches,page() will use whatevernum value was captured by the regex.

Performance¶

Each regular expression in aurlpatterns is compiled the first time it’saccessed. This makes the system blazingly fast.

Syntax of theurlpatterns variable¶

urlpatterns should be a Python list ofurl()instances.

Error handling¶

When Django can’t find a regex matching the requested URL, or when anexception is raised, Django will invoke an error-handling view.

The views to use for these cases are specified by four variables. Theirdefault values should suffice for most projects, but further customization ispossible by overriding their default values.

See the documentation oncustomizing error views for the full details.

Such values can be set in your root URLconf. Setting these variables in anyother URLconf will have no effect.

Values must be callables, or strings representing the full Python import pathto the view that should be called to handle the error condition at hand.

The variables are:

• handler400 – Seedjango.conf.urls.handler400.
• handler403 – Seedjango.conf.urls.handler403.
• handler404 – Seedjango.conf.urls.handler404.
• handler500 – Seedjango.conf.urls.handler500.

Including other URLconfs¶

At any point, yoururlpatterns can “include” other URLconf modules. Thisessentially “roots” a set of URLs below other ones.

For example, here’s an excerpt of the URLconf for theDjango websiteitself. It includes a number of other URLconfs:

fromdjango.conf.urlsimportinclude,urlurlpatterns=[# ... snip ...url(r'^community/',include('django_website.aggregator.urls')),url(r'^contact/',include('django_website.contact.urls')),# ... snip ...]

Note that the regular expressions in this example don’t have a$(end-of-string match character) but do include a trailing slash. WheneverDjango encountersinclude() (django.conf.urls.include()), it chopsoff whatever part of the URL matched up to that point and sends the remainingstring to the included URLconf for further processing.

Another possibility is to include additional URL patterns by using a list ofurl() instances. For example, consider this URLconf:

fromdjango.conf.urlsimportinclude,urlfromapps.mainimportviewsasmain_viewsfromcreditimportviewsascredit_viewsextra_patterns=[url(r'^reports/$',credit_views.report),url(r'^reports/(?P<id>[0-9]+)/$',credit_views.report),url(r'^charge/$',credit_views.charge),]urlpatterns=[url(r'^$',main_views.homepage),url(r'^help/',include('apps.help.urls')),url(r'^credit/',include(extra_patterns)),]

In this example, the/credit/reports/ URL will be handled by thecredit_views.report() Django view.

This can be used to remove redundancy from URLconfs where a single patternprefix is used repeatedly. For example, consider this URLconf:

fromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^(?P<page_slug>[\w-]+)-(?P<page_id>\w+)/history/$',views.history),url(r'^(?P<page_slug>[\w-]+)-(?P<page_id>\w+)/edit/$',views.edit),url(r'^(?P<page_slug>[\w-]+)-(?P<page_id>\w+)/discuss/$',views.discuss),url(r'^(?P<page_slug>[\w-]+)-(?P<page_id>\w+)/permissions/$',views.permissions),]

We can improve this by stating the common path prefix only once and groupingthe suffixes that differ:

fromdjango.conf.urlsimportinclude,urlfrom.importviewsurlpatterns=[url(r'^(?P<page_slug>[\w-]+)-(?P<page_id>\w+)/',include([url(r'^history/$',views.history),url(r'^edit/$',views.edit),url(r'^discuss/$',views.discuss),url(r'^permissions/$',views.permissions),])),]

# In settings/urls/main.pyfromdjango.conf.urlsimportinclude,urlurlpatterns=[url(r'^(?P<username>\w+)/blog/',include('foo.urls.blog')),]# In foo/urls/blog.pyfromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^$',views.blog.index),url(r'^archive/$',views.blog.archive),]

Nested arguments¶

Regular expressions allow nested arguments, and Django will resolve them andpass them to the view. When reversing, Django will try to fill in all outercaptured arguments, ignoring any nested captured arguments. Consider thefollowing URL patterns which optionally take a page argument:

fromdjango.conf.urlsimporturlurlpatterns=[url(r'blog/(page-(\d+)/)?$',blog_articles),# badurl(r'comments/(?:page-(?P<page_number>\d+)/)?$',comments),# good]

Both patterns use nested arguments and will resolve: for example,blog/page-2/ will result in a match toblog_articles with twopositional arguments:page-2/ and2. The second pattern forcomments will matchcomments/page-2/ with keyword argumentpage_number set to 2. The outer argument in this case is a non-capturingargument(?:...).

Theblog_articles view needs the outermost captured argument to be reversed,page-2/ or no arguments in this case, whilecomments can be reversedwith either no arguments or a value forpage_number.

Nested captured arguments create a strong coupling between the view argumentsand the URL as illustrated byblog_articles: the view receives part of theURL (page-2/) instead of only the value the view is interested in. Thiscoupling is even more pronounced when reversing, since to reverse the view weneed to pass the piece of URL instead of the page number.

As a rule of thumb, only capture the values the view needs to work with anduse non-capturing arguments when the regular expression needs an argument butthe view ignores it.

Passing extra options to view functions¶

URLconfs have a hook that lets you pass extra arguments to your view functions,as a Python dictionary.

Thedjango.conf.urls.url() function can take an optional third argumentwhich should be a dictionary of extra keyword arguments to pass to the viewfunction.

For example:

fromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[url(r'^blog/(?P<year>[0-9]{4})/$',views.year_archive,{'foo':'bar'}),]

In this example, for a request to/blog/2005/, Django will callviews.year_archive(request,year='2005',foo='bar').

This technique is used in thesyndication framework to pass metadata andoptions to views.

# main.pyfromdjango.conf.urlsimportinclude,urlurlpatterns=[url(r'^blog/',include('inner'),{'blogid':3}),]# inner.pyfromdjango.conf.urlsimporturlfrommysiteimportviewsurlpatterns=[url(r'^archive/$',views.archive),url(r'^about/$',views.about),]

# main.pyfromdjango.conf.urlsimportinclude,urlfrommysiteimportviewsurlpatterns=[url(r'^blog/',include('inner')),]# inner.pyfromdjango.conf.urlsimporturlurlpatterns=[url(r'^archive/$',views.archive,{'blogid':3}),url(r'^about/$',views.about,{'blogid':3}),]

Reverse resolution of URLs¶

A common need when working on a Django project is the possibility to obtain URLsin their final forms either for embedding in generated content (views and assetsURLs, URLs shown to the user, etc.) or for handling of the navigation flow onthe server side (redirections, etc.)

It is strongly desirable to avoid hard-coding these URLs (a laborious,non-scalable and error-prone strategy). Equally dangerous is devising ad-hocmechanisms to generate URLs that are parallel to the design described by theURLconf, which can result in the production of URLs that become stale over time.

In other words, what’s needed is a DRY mechanism. Among other advantages itwould allow evolution of the URL design without having to go over all theproject source code to search and replace outdated URLs.

The primary piece of information we have available to get a URL is anidentification (e.g. the name) of the view in charge of handling it. Otherpieces of information that necessarily must participate in the lookup of theright URL are the types (positional, keyword) and values of the view arguments.

Django provides a solution such that the URL mapper is the only repository ofthe URL design. You feed it with your URLconf and then it can be used in bothdirections:

• Starting with a URL requested by the user/browser, it calls the right Djangoview providing any arguments it might need with their values as extracted fromthe URL.
• Starting with the identification of the corresponding Django view plus thevalues of arguments that would be passed to it, obtain the associated URL.

The first one is the usage we’ve been discussing in the previous sections. Thesecond one is what is known asreverse resolution of URLs,reverse URLmatching,reverse URL lookup, or simplyURL reversing.

Django provides tools for performing URL reversing that match the differentlayers where URLs are needed:

• In templates: Using theurl template tag.
• In Python code: Using thereverse() function.
• In higher level code related to handling of URLs of Django model instances:Theget_absolute_url() method.

fromdjango.conf.urlsimporturlfrom.importviewsurlpatterns=[#...url(r'^articles/([0-9]{4})/$',views.year_archive,name='news-year-archive'),#...]

<ahref="{%url'news-year-archive'2012%}">2012 Archive</a>{# Or with the year in a template context variable: #}<ul>{%foryearvarinyear_list%}<li><ahref="{%url'news-year-archive'yearvar%}">{{yearvar}} Archive</a></li>{%endfor%}</ul>

fromdjango.urlsimportreversefromdjango.httpimportHttpResponseRedirectdefredirect_to_year(request):# ...year=2006# ...returnHttpResponseRedirect(reverse('news-year-archive',args=(year,)))

Naming URL patterns¶

In order to perform URL reversing, you’ll need to usenamed URL patternsas done in the examples above. The string used for the URL name can contain anycharacters you like. You are not restricted to valid Python names.

When you name your URL patterns, make sure you use names that are unlikelyto clash with any other application’s choice of names. If you call your URLpatterncomment, and another application does the same thing, there’sno guarantee which URL will be inserted into your template when you usethis name.

Putting a prefix on your URL names, perhaps derived from the applicationname, will decrease the chances of collision. We recommend something likemyapp-comment instead ofcomment.

URL namespaces¶

fromdjango.conf.urlsimportinclude,urlurlpatterns=[url(r'^author-polls/',include('polls.urls',namespace='author-polls')),url(r'^publisher-polls/',include('polls.urls',namespace='publisher-polls')),]

fromdjango.conf.urlsimporturlfrom.importviewsapp_name='polls'urlpatterns=[url(r'^$',views.IndexView.as_view(),name='index'),url(r'^(?P<pk>\d+)/$',views.DetailView.as_view(),name='detail'),...]

fromdjango.conf.urlsimporturlfrom.importviewsapp_name='polls'urlpatterns=[url(r'^$',views.IndexView.as_view(),name='index'),url(r'^(?P<pk>\d+)/$',views.DetailView.as_view(),name='detail'),...]

fromdjango.conf.urlsimportinclude,urlurlpatterns=[url(r'^polls/',include('polls.urls')),]

(<listofurl()instances>,<applicationnamespace>)

fromdjango.conf.urlsimportinclude,urlfrom.importviewspolls_patterns=([url(r'^$',views.IndexView.as_view(),name='index'),url(r'^(?P<pk>\d+)/$',views.DetailView.as_view(),name='detail'),],'polls')urlpatterns=[url(r'^polls/',include(polls_patterns)),]