At any point, your urlpatterns can \u201cinclude\u201d other URLconf modules. This essentially \u201croots\u201d a set of URLs below other ones. For example, here\u2019s an excerpt of the URLconf for the Django Web site itself. It includes a number of other URLconfs:<\/p>\n
from django.conf.urls import include, url<\/p>\n
urlpatterns = [
\n# …
\nurl(r’^community\/’, include(‘django_website.aggregator.urls’)),
\nurl(r’^contact\/’, include(‘django_website.contact.urls’)),
\n# …
\n]\n
Note that the regular expressions in this example don\u2019t have a $ (end-of-string match character) but do include a trailing slash. Whenever Django encounters include(), it chops off whatever part of the URL matched up to that point and sends the remaining string to the included URLconf for further processing. Another possibility is to include additional URL patterns by using a list of url() instances. For example, consider this URLconf:<\/p>\n
from django.conf.urls import include, url
\nfrom apps.main import views as main_views
\nfrom credit import views as credit_views<\/p>\n
extra_patterns = [
\nurl(r’^reports\/(?P<id>[0-9]+)\/$’, credit_views.report),
\nurl(r’^charge\/$’, credit_views.charge),
\n]\n
urlpatterns = [
\nurl(r’^$’, main_views.homepage),
\nurl(r’^help\/’, include(‘apps.help.urls’)),
\nurl(r’^credit\/’, include(extra_patterns)),
\n]\n
In this example, the \/credit\/reports\/ URL will be handled by the credit.views.report() Django view. This can be used to remove redundancy from URLconfs where a single pattern prefix is used repeatedly. For example, consider this URLconf:<\/p>\n
from django.conf.urls import url
\nfrom . import views<\/p>\n
urlpatterns = [
\nurl(r’^(?P<page_slug>\\w+)-(?P<page_id>\\w+)\/history\/$’,
\nviews.history),
\nurl(r’^(?P<page_slug>\\w+)-(?P<page_id>\\w+)\/edit\/$’,
\nviews.edit),
\nurl(r’^(?P<page_slug>\\w+)-(?P<page_id>\\w+)\/discuss\/$’,
\nviews.discuss),
\nurl(r’^(?P<page_slug>\\w+)-(?P<page_id>\\w+)\/permissions\/$’,
\nviews.permissions),
\n]\n
We can improve this by stating the common path prefix only once and grouping the suffixes that differ:<\/p>\n
from django.conf.urls import include, url
\nfrom . import views<\/p>\n
urlpatterns = [
\nurl(r’^(?P<page_slug>\\w+)-(?P<page_id>\\w+)\/’,
\ninclude([
\nurl(r’^history\/$’, views.history),
\nurl(r’^edit\/$’, views.edit),
\nurl(r’^discuss\/$’, views.discuss),
\nurl(r’^permissions\/$’, views.permissions),
\n])),
\n]\n
An included URLconf receives any captured parameters from parent URLconfs, so the fol\\
\nlowing example is valid:<\/p>\n
# In settings\/urls\/main.py
\nfrom django.conf.urls import include, url<\/p>\n
urlpatterns = [
\nurl(r’^(?P<username>\\w+)\/reviews\/’, include(‘foo.urls.reviews’)),
\n]\n
# In foo\/urls\/reviews.py
\nfrom django.conf.urls import url
\nfrom . import views<\/p>\n
urlpatterns = [
\nurl(r’^$’, views.reviews.index),
\nurl(r’^archive\/$’, views.reviews.archive),
\n]\n
In the above example, the captured “username” variable is passed to the included URLconf, as expected.<\/p>\n
URLconfs have a hook that lets you pass extra arguments to your view functions, as a Python dictionary. The django.conf.urls.url() function can take an optional third argument which should be a dictionary of extra keyword arguments to pass to the view function. For example:<\/p>\n
from django.conf.urls import url
\nfrom . import views<\/p>\n
urlpatterns = [
\nurl(r’^reviews\/(?P<year>[0-9]{4})\/$’,
\nviews.year_archive,
\n{‘foo’: ‘bar’}),
\n]\n
In this example, for a request to \/reviews\/2005\/, Django will call views.year_archive(request, year=’2005′, foo=’bar’).<\/p>\n
Similarly, you can pass extra options to include(). When you pass extra options to include(), each line in the included URLconf will be passed the extra options. For example, these two URLconf sets are functionally identical:<\/p>\n
Set one:
\n# main.py
\nfrom django.conf.urls import include, url<\/p>\n
urlpatterns = [
\nurl(r’^reviews\/’, include(‘inner’), {‘reviewid’: 3}),
\n]\n
# inner.py
\nfrom django.conf.urls import url
\nfrom mysite import views<\/p>\n
urlpatterns = [
\nurl(r’^archive\/$’, views.archive),
\nurl(r’^about\/$’, views.about),
\n]\n
Set two:
\n# main.py
\nfrom django.conf.urls import include, url
\nfrom mysite import views<\/p>\n
urlpatterns = [
\nurl(r’^reviews\/’, include(‘inner’)),
\n]\n
# inner.py
\nfrom django.conf.urls import url<\/p>\n
urlpatterns = [
\nurl(r’^archive\/$’, views.archive, {‘reviewid’: 3}),
\nurl(r’^about\/$’, views.about, {‘reviewid’: 3}),
\n]\n
Note that extra options will always be passed to every line in the included URLconf, regardless of whether the line\u2019s view actually accepts those options as valid. For this reason, this technique is only useful if you\u2019re certain that every view in the included URLconf accepts the extra options you\u2019re passing.<\/p>\n
A common need when working on a Django project is the possibility to obtain URLs in their final forms either for embedding in generated content (views and assets URLs, URLs shown to the user, etc.) or for handling of the navigation flow on the server side (redirections, etc.)<\/p>\n
It is strongly desirable to avoid hard-coding these URLs (a laborious, non-scalable and error-prone strategy) or having to devise ad-hoc mechanisms for generating URLs that are parallel to the design described by the URLconf and as such in danger of producing stale URLs at some point. In other words, what\u2019s needed is a DRY mechanism.<\/p>\n
Among other advantages it would allow evolution of the URL design without having to go all over the project source code to search and replace outdated URLs. The piece of information we have available as a starting point to get a URL is an identification (e.g. the name) of the view in charge of handling it, other pieces of information that necessarily must participate in the lookup of the right URL are the types (positional, keyword) and values of the view arguments.<\/p>\n
Django provides a solution such that the URL mapper is the only repository of the URL design. You feed it with your URLconf and then it can be used in both directions:<\/p>\n
The first one is the usage we\u2019ve been discussing in the previous sections. The second one is what is known as reverse resolution of URLs, reverse URL matching, reverse URL lookup, or simply URL reversing.<\/p>\n
Examples<\/strong> from django.conf.urls import url urlpatterns = [ According to this design, the URL for the archive corresponding to year nnnn is \/reviews\/nnnn\/. You can obtain these in template code by using:<\/p>\n <a href=”{% url ‘reviews-year-archive’ 2012 %}”>2012 Archive<\/a> <ul> Or in Python code:<\/p>\n from django.core.urlresolvers import reverse def redirect_to_year(request): If, for some reason, it was decided that the URLs where content for yearly review archives are published at should be changed then you would only need to change the entry in the URLconf. In some scenarios where views are of a generic nature, a many-to-one relationship might exist between URLs and views. For these cases the view name isn\u2019t a good enough identifier for it when comes the time of reversing URLs. Read the next section to know about the solution Django provides for this.<\/p>\n In order to perform URL reversing, you\u2019ll need to use named URL patterns as done in the examples above. The string used for the URL name can contain any characters you like. You are not restricted to valid Python names. When you name your URL patterns, make sure you use names that are unlikely to clash with any other application\u2019s choice of names. If you call your URL pattern comment, and another application does the same thing, there\u2019s no guarantee which URL will be inserted into your template when you use this name. Putting a prefix on your URL names, perhaps derived from the application name, will decrease the chances of collision. We recommend something like myapp-comment instead of comment.<\/p>\n URL namespaces allow you to uniquely reverse named URL patterns even if different applications use the same URL names. It\u2019s a good practice for third-party apps to always use namespaced URLs. Similarly, it also allows you to reverse URLs if multiple instances of an application are deployed. In other words, since multiple instances of a single application will share named URLs, namespaces provide a way to tell these named URLs apart.<\/p>\n Django applications that make proper use of URL namespacing can be deployed more than once for a particular site. For example, Namespaced URLs are specified using the \u201c : \u201c operator. For example, the main index page of the admin application is referenced using \u201cadmin:index\u201d. This indicates a namespace of \u201cadmin\u201d, and a named URL of \u201cindex\u201d.<\/p>\n Namespaces can also be nested. The named URL members:reviews:index would look for a pattern named \u201cindex\u201d in the namespace \u201creviews\u201d that is itself defined within the top-level namespace \u201cmembers\u201d. If there are nested namespaces, these steps are repeated for each part of the namespace until only the view name is unresolved. The view name will then be resolved into a URL in the namespace that has been found. url(r’^reviews\/’, include(‘reviews.urls’, namespace=’author-reviews’, app_name=’revie\\ This will include the URLs defined in reviews.urls into the application namespace ‘reviews’, with the instance namespace ‘author-reviews’. Secondly, you can include an object that contains embedded namespace data. If you include() a list of url() instances, the URLs contained in that object will be added to the global namespace. However, you can also include() a 3-tuple containing:<\/p>\n (<list of url() instances>, <application namespace>, <instance namespace>)<\/p>\n For example:<\/p>\n from django.conf.urls import include, url reviews_patterns = [ url(r’^reviews\/’, include((reviews_patterns, ‘reviews’, ‘author-reviews’))),<\/p>\n This will include the nominated URL patterns into the given application and instance namespace. For example, the Django admin is deployed as instances of AdminSite. AdminSite objects have a urls attribute: A 3-tuple that contains all the patterns in the corresponding admin site, plus the application namespace \u201cadmin\u201d, and the name of the admin instance. It is this urls attribute that you include() into your projects urlpatterns when you deploy an admin instance.<\/p>\n Be sure to pass a tuple to include(). If you simply pass three arguments: include(reviews_patterns, ‘reviews’, ‘author-reviews’), Django won\u2019t throw an error but due to the signature of include(), ‘reviews’ will be the instance namespace and ‘author-reviews’ will be the application namespace instead of vice versa.<\/p>\n\n\n
\nConsider again this URLconf entry:<\/p>\n
\nfrom . import views<\/p>\n
\n#…
\nurl(r’^reviews\/([0-9]{4})\/$’, views.year_archive,
\nname=’reviews-year-archive’),
\n#…
\n]\n
\n{# Or with the year in a template context variable: #}<\/p>\n
\n{% for yearvar in year_list %}
\n<li><a href=”{% url ‘reviews-year-archive’ yearvar %}”>{{
\nyearvar }} Archive<\/a><\/li>
\n{% endfor %}
\n<\/ul><\/p>\n
\nfrom django.http import HttpResponseRedirect<\/p>\n
\n# …
\nyear = 2012
\n# …
\nreturn HttpResponseRedirect(reverse(‘reviews-year-archive’, args=(year,)))<\/p>\nNaming URL Patterns<\/h3>\n
URL Namespaces<\/h3>\n
\ndjango.contrib.admin has an AdminSite class which allows you to easily deploy more than once instance of the admin. A URL namespace comes in two parts, both of which are strings:<\/p>\n\n
\nReversing Namespaced URLs
\nWhen given a namespaced URL (e.g. \u201creviews:index\u201d) to resolve, Django splits the fully qualified name into parts and then tries the following lookup:<\/p>\n\n
\nURL Namespaces and Included URLconfs
\nURL namespaces of included URLconfs can be specified in two ways. Firstly, you can provide the application and instance namespaces as arguments to include() when you construct your URL patterns. For example:<\/p>\n
\nws’)),<\/p>\n
\nfrom . import views<\/p>\n
\nurl(r’^$’, views.IndexView.as_view(), name=’index’),
\nurl(r’^(?P<pk>\\d+)\/$’, views.DetailView.as_view(), name=’detail’),
\n]\n