diff options
author | Sjoerd Job Postmus <sjoerdjob@sjec.nl> | 2016-10-20 19:29:04 +0200 |
---|---|---|
committer | Tim Graham <timograham@gmail.com> | 2017-09-20 18:04:42 -0400 |
commit | df41b5a05d4e00e80e73afe629072e37873e767a (patch) | |
tree | baaf71ae695e2d3af604ea0d663284cb406c71e4 /docs/ref | |
parent | c4c128d67c7dc2830631c6859a204c9d259f1fb1 (diff) | |
download | django-df41b5a05d4e00e80e73afe629072e37873e767a.tar.gz |
Fixed #28593 -- Added a simplified URL routing syntax per DEP 0201.
Thanks Aymeric Augustin for shepherding the DEP and patch review.
Thanks Marten Kenbeek and Tim Graham for contributing to the code.
Thanks Tom Christie, Shai Berger, and Tim Graham for the docs.
Diffstat (limited to 'docs/ref')
-rw-r--r-- | docs/ref/checks.txt | 16 | ||||
-rw-r--r-- | docs/ref/class-based-views/base.txt | 16 | ||||
-rw-r--r-- | docs/ref/class-based-views/generic-date-based.txt | 64 | ||||
-rw-r--r-- | docs/ref/class-based-views/generic-display.txt | 8 | ||||
-rw-r--r-- | docs/ref/class-based-views/index.txt | 2 | ||||
-rw-r--r-- | docs/ref/class-based-views/mixins-multiple-object.txt | 2 | ||||
-rw-r--r-- | docs/ref/contrib/admin/admindocs.txt | 4 | ||||
-rw-r--r-- | docs/ref/contrib/admin/index.txt | 44 | ||||
-rw-r--r-- | docs/ref/contrib/flatpages.txt | 14 | ||||
-rw-r--r-- | docs/ref/contrib/gis/tutorial.txt | 4 | ||||
-rw-r--r-- | docs/ref/contrib/sitemaps.txt | 46 | ||||
-rw-r--r-- | docs/ref/contrib/staticfiles.txt | 3 | ||||
-rw-r--r-- | docs/ref/contrib/syndication.txt | 12 | ||||
-rw-r--r-- | docs/ref/templates/builtins.txt | 18 | ||||
-rw-r--r-- | docs/ref/urlresolvers.txt | 2 | ||||
-rw-r--r-- | docs/ref/urls.txt | 118 | ||||
-rw-r--r-- | docs/ref/utils.txt | 4 | ||||
-rw-r--r-- | docs/ref/views.txt | 3 |
18 files changed, 224 insertions, 156 deletions
diff --git a/docs/ref/checks.txt b/docs/ref/checks.txt index 0ca1d176f4..45bef40688 100644 --- a/docs/ref/checks.txt +++ b/docs/ref/checks.txt @@ -444,18 +444,18 @@ URLs The following checks are performed on your URL configuration: * **urls.W001**: Your URL pattern ``<pattern>`` uses - :func:`~django.conf.urls.include` with a ``regex`` ending with a - ``$``. Remove the dollar from the ``regex`` to avoid problems - including URLs. -* **urls.W002**: Your URL pattern ``<pattern>`` has a ``regex`` - beginning with a ``/``. Remove this slash as it is unnecessary. - If this pattern is targeted in an :func:`~django.conf.urls.include`, ensure - the :func:`~django.conf.urls.include` pattern has a trailing ``/``. + :func:`~django.urls.include` with a ``route`` ending with a ``$``. Remove the + dollar from the ``route`` to avoid problems including URLs. +* **urls.W002**: Your URL pattern ``<pattern>`` has a ``route`` beginning with + a ``/``. Remove this slash as it is unnecessary. If this pattern is targeted + in an :func:`~django.urls.include`, ensure the :func:`~django.urls.include` + pattern has a trailing ``/``. * **urls.W003**: Your URL pattern ``<pattern>`` has a ``name`` including a ``:``. Remove the colon, to avoid ambiguous namespace references. * **urls.E004**: Your URL pattern ``<pattern>`` is invalid. Ensure that - ``urlpatterns`` is a list of :func:`~django.conf.urls.url()` instances. + ``urlpatterns`` is a list of :func:`~django.urls.path` and/or + :func:`~django.urls.re_path` instances. * **urls.W005**: URL namespace ``<namespace>`` isn't unique. You may not be able to reverse all URLs in this namespace. * **urls.E006**: The :setting:`MEDIA_URL`/ :setting:`STATIC_URL` setting must diff --git a/docs/ref/class-based-views/base.txt b/docs/ref/class-based-views/base.txt index 6230f1181e..6ef72176c3 100644 --- a/docs/ref/class-based-views/base.txt +++ b/docs/ref/class-based-views/base.txt @@ -40,12 +40,12 @@ MRO is an acronym for Method Resolution Order. **Example urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import MyView urlpatterns = [ - url(r'^mine/$', MyView.as_view(), name='my-view'), + path('mine/', MyView.as_view(), name='my-view'), ] **Attributes** @@ -144,12 +144,12 @@ MRO is an acronym for Method Resolution Order. **Example urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import HomePageView urlpatterns = [ - url(r'^$', HomePageView.as_view(), name='home'), + path('', HomePageView.as_view(), name='home'), ] **Context** @@ -208,15 +208,15 @@ MRO is an acronym for Method Resolution Order. **Example urls.py**:: - from django.conf.urls import url + from django.urls import path from django.views.generic.base import RedirectView from article.views import ArticleCounterRedirectView, ArticleDetail urlpatterns = [ - url(r'^counter/(?P<pk>[0-9]+)/$', ArticleCounterRedirectView.as_view(), name='article-counter'), - url(r'^details/(?P<pk>[0-9]+)/$', ArticleDetail.as_view(), name='article-detail'), - url(r'^go-to-django/$', RedirectView.as_view(url='https://djangoproject.com'), name='go-to-django'), + path('counter/<int:pk>/', ArticleCounterRedirectView.as_view(), name='article-counter'), + path('details/<int:pk>/', ArticleDetail.as_view(), name='article-detail'), + path('go-to-django/', RedirectView.as_view(url='https://djangoproject.com'), name='go-to-django'), ] **Attributes** diff --git a/docs/ref/class-based-views/generic-date-based.txt b/docs/ref/class-based-views/generic-date-based.txt index 7b50d099ba..a42896c058 100644 --- a/docs/ref/class-based-views/generic-date-based.txt +++ b/docs/ref/class-based-views/generic-date-based.txt @@ -63,15 +63,15 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from django.views.generic.dates import ArchiveIndexView from myapp.models import Article urlpatterns = [ - url(r'^archive/$', - ArchiveIndexView.as_view(model=Article, date_field="pub_date"), - name="article_archive"), + path('archive/', + ArchiveIndexView.as_view(model=Article, date_field="pub_date"), + name="article_archive"), ] **Example myapp/article_archive.html**: @@ -162,14 +162,14 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import ArticleYearArchiveView urlpatterns = [ - url(r'^(?P<year>[0-9]{4})/$', - ArticleYearArchiveView.as_view(), - name="article_year_archive"), + path('<int:year>/', + ArticleYearArchiveView.as_view(), + name="article_year_archive"), ] **Example myapp/article_archive_year.html**: @@ -254,19 +254,19 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import ArticleMonthArchiveView urlpatterns = [ - # Example: /2012/aug/ - url(r'^(?P<year>[0-9]{4})/(?P<month>[-\w]+)/$', - ArticleMonthArchiveView.as_view(), - name="archive_month"), # Example: /2012/08/ - url(r'^(?P<year>[0-9]{4})/(?P<month>[0-9]+)/$', - ArticleMonthArchiveView.as_view(month_format='%m'), - name="archive_month_numeric"), + path('<int:year>/<int:month>/', + ArticleMonthArchiveView.as_view(month_format='%m'), + name="archive_month_numeric"), + # Example: /2012/aug/ + path('<int:year>/<str:month>/', + ArticleMonthArchiveView.as_view(), + name="archive_month"), ] **Example myapp/article_archive_month.html**: @@ -356,15 +356,15 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import ArticleWeekArchiveView urlpatterns = [ # Example: /2012/week/23/ - url(r'^(?P<year>[0-9]{4})/week/(?P<week>[0-9]+)/$', - ArticleWeekArchiveView.as_view(), - name="archive_week"), + path('<int:year>/week/<int:week>/', + ArticleWeekArchiveView.as_view(), + name="archive_week"), ] **Example myapp/article_archive_week.html**: @@ -468,15 +468,15 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import ArticleDayArchiveView urlpatterns = [ # Example: /2012/nov/10/ - url(r'^(?P<year>[0-9]{4})/(?P<month>[-\w]+)/(?P<day>[0-9]+)/$', - ArticleDayArchiveView.as_view(), - name="archive_day"), + path('<int:year>/<str:month>/<int:day>/', + ArticleDayArchiveView.as_view(), + name="archive_day"), ] **Example myapp/article_archive_day.html**: @@ -541,14 +541,14 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from myapp.views import ArticleTodayArchiveView urlpatterns = [ - url(r'^today/$', - ArticleTodayArchiveView.as_view(), - name="archive_today"), + path('today/', + ArticleTodayArchiveView.as_view(), + name="archive_today"), ] .. admonition:: Where is the example template for ``TodayArchiveView``? @@ -591,13 +591,13 @@ views for displaying drilldown pages for date-based data. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from django.views.generic.dates import DateDetailView urlpatterns = [ - url(r'^(?P<year>[0-9]{4})/(?P<month>[-\w]+)/(?P<day>[0-9]+)/(?P<pk>[0-9]+)/$', - DateDetailView.as_view(model=Article, date_field="pub_date"), - name="archive_date_detail"), + path('<int:year>/<str:month>/<int:day>/<int:pk>/', + DateDetailView.as_view(model=Article, date_field="pub_date"), + name="archive_date_detail"), ] **Example myapp/article_detail.html**: diff --git a/docs/ref/class-based-views/generic-display.txt b/docs/ref/class-based-views/generic-display.txt index 70da1803d6..16975bdbea 100644 --- a/docs/ref/class-based-views/generic-display.txt +++ b/docs/ref/class-based-views/generic-display.txt @@ -54,12 +54,12 @@ many projects they are typically the most commonly used views. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from article.views import ArticleDetailView urlpatterns = [ - url(r'^(?P<slug>[-\w]+)/$', ArticleDetailView.as_view(), name='article-detail'), + path('<slug>/', ArticleDetailView.as_view(), name='article-detail'), ] **Example myapp/article_detail.html**: @@ -123,12 +123,12 @@ many projects they are typically the most commonly used views. **Example myapp/urls.py**:: - from django.conf.urls import url + from django.urls import path from article.views import ArticleListView urlpatterns = [ - url(r'^$', ArticleListView.as_view(), name='article-list'), + path('', ArticleListView.as_view(), name='article-list'), ] **Example myapp/article_list.html**: diff --git a/docs/ref/class-based-views/index.txt b/docs/ref/class-based-views/index.txt index 17bd5315ff..5187000385 100644 --- a/docs/ref/class-based-views/index.txt +++ b/docs/ref/class-based-views/index.txt @@ -26,7 +26,7 @@ A class-based view is deployed into a URL pattern using the :meth:`~django.views.generic.base.View.as_view()` classmethod:: urlpatterns = [ - url(r'^view/$', MyView.as_view(size=42)), + path('view/', MyView.as_view(size=42)), ] .. admonition:: Thread safety with view arguments diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt index 58260391a8..8f6fcb8d48 100644 --- a/docs/ref/class-based-views/mixins-multiple-object.txt +++ b/docs/ref/class-based-views/mixins-multiple-object.txt @@ -15,7 +15,7 @@ Multiple object mixins * Use the ``page`` parameter in the URLconf. For example, this is what your URLconf might look like:: - url(r'^objects/page(?P<page>[0-9]+)/$', PaginatedView.as_view()), + path('objects/page<int:page>/', PaginatedView.as_view()), * Pass the page number via the ``page`` query-string parameter. For example, a URL would look like this:: diff --git a/docs/ref/contrib/admin/admindocs.txt b/docs/ref/contrib/admin/admindocs.txt index 461813f985..e519bd8ed1 100644 --- a/docs/ref/contrib/admin/admindocs.txt +++ b/docs/ref/contrib/admin/admindocs.txt @@ -19,9 +19,9 @@ To activate the :mod:`~django.contrib.admindocs`, you will need to do the following: * Add :mod:`django.contrib.admindocs` to your :setting:`INSTALLED_APPS`. -* Add ``url(r'^admin/doc/', include('django.contrib.admindocs.urls'))`` to +* Add ``path('admin/doc/', include('django.contrib.admindocs.urls'))`` to your ``urlpatterns``. Make sure it's included *before* the - ``r'^admin/'`` entry, so that requests to ``/admin/doc/`` don't get + ``'admin/'`` entry, so that requests to ``/admin/doc/`` don't get handled by the latter entry. * Install the docutils Python module (http://docutils.sf.net/). * **Optional:** Using the admindocs bookmarklets requires diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 2541bc9aa1..adbd18ef74 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -1587,11 +1587,15 @@ templates used by the :class:`ModelAdmin` views: that ModelAdmin in the same way as a URLconf. Therefore you can extend them as documented in :doc:`/topics/http/urls`:: + from django.contrib import admin + from django.template.response import TemplateResponse + from django.urls import path + class MyModelAdmin(admin.ModelAdmin): def get_urls(self): urls = super().get_urls() my_urls = [ - url(r'^my_view/$', self.my_view), + path('my_view/', self.my_view), ] return my_urls + urls @@ -1643,13 +1647,13 @@ templates used by the :class:`ModelAdmin` views: def get_urls(self): urls = super().get_urls() my_urls = [ - url(r'^my_view/$', self.admin_site.admin_view(self.my_view)) + path('my_view/', self.admin_site.admin_view(self.my_view)) ] return my_urls + urls Notice the wrapped view in the fifth line above:: - url(r'^my_view/$', self.admin_site.admin_view(self.my_view)) + path('my_view/', self.admin_site.admin_view(self.my_view)) This wrapping will protect ``self.my_view`` from unauthorized access and will apply the :func:`django.views.decorators.cache.never_cache` decorator to @@ -1659,7 +1663,7 @@ templates used by the :class:`ModelAdmin` views: performed, you can pass a ``cacheable=True`` argument to ``AdminSite.admin_view()``:: - url(r'^my_view/$', self.admin_site.admin_view(self.my_view, cacheable=True)) + path('my_view/', self.admin_site.admin_view(self.my_view, cacheable=True)) ``ModelAdmin`` views have ``model_admin`` attributes. Other ``AdminSite`` views have ``admin_site`` attributes. @@ -2767,17 +2771,17 @@ Hooking ``AdminSite`` instances into your URLconf The last step in setting up the Django admin is to hook your ``AdminSite`` instance into your URLconf. Do this by pointing a given URL at the ``AdminSite.urls`` method. It is not necessary to use -:func:`~django.conf.urls.include()`. +:func:`~django.urls.include()`. In this example, we register the default ``AdminSite`` instance ``django.contrib.admin.site`` at the URL ``/admin/`` :: # urls.py - from django.conf.urls import url from django.contrib import admin + from django.urls import path urlpatterns = [ - url(r'^admin/', admin.site.urls), + path('admin/', admin.site.urls), ] .. _customizing-adminsite: @@ -2809,12 +2813,12 @@ update :file:`myproject/urls.py` to reference your :class:`AdminSite` subclass. .. snippet:: :filename: myproject/urls.py - from django.conf.urls import url + from django.urls import path from myapp.admin import admin_site urlpatterns = [ - url(r'^myadmin/', admin_site.urls), + path('myadmin/', admin_site.urls), ] Note that you may not want autodiscovery of ``admin`` modules when using your @@ -2838,12 +2842,12 @@ separate versions of the admin site -- using the ``AdminSite`` instances respectively:: # urls.py - from django.conf.urls import url + from django.urls import path from myproject.admin import basic_site, advanced_site urlpatterns = [ - url(r'^basic-admin/', basic_site.urls), - url(r'^advanced-admin/', advanced_site.urls), + path('basic-admin/', basic_site.urls), + path('advanced-admin/', advanced_site.urls), ] ``AdminSite`` instances take a single argument to their constructor, their @@ -2879,23 +2883,23 @@ your URLconf. Specifically, add these four patterns:: from django.contrib.auth import views as auth_views - url( - r'^admin/password_reset/$', + path( + 'admin/password_reset/', auth_views.PasswordResetView.as_view(), name='admin_password_reset', ), - url( - r'^admin/password_reset/done/$', + path( + 'admin/password_reset/done/', auth_views.PasswordResetDoneView.as_view(), name='password_reset_done', ), - url( - r'^reset/(?P<uidb64>[0-9A-Za-z_\-]+)/(?P<token>.+)/$', + path( + 'reset/<uidb64>/<token>/', auth_views.PasswordResetConfirmView.as_view(), name='password_reset_confirm', ), - url( - r'^reset/done/$', + path( + 'reset/done/', auth_views.PasswordResetCompleteView.as_view(), name='password_reset_complete', ), diff --git a/docs/ref/contrib/flatpages.txt b/docs/ref/contrib/flatpages.txt index 4dcd4b9a5a..5d34ad6bea 100644 --- a/docs/ref/contrib/flatpages.txt +++ b/docs/ref/contrib/flatpages.txt @@ -47,7 +47,7 @@ Then either: 3. Add an entry in your URLconf. For example:: urlpatterns = [ - url(r'^pages/', include('django.contrib.flatpages.urls')), + path('pages/', include('django.contrib.flatpages.urls')), ] or: @@ -74,7 +74,7 @@ There are several ways to include the flat pages in your URLconf. You can dedicate a particular path to flat pages:: urlpatterns = [ - url(r'^pages/', include('django.contrib.flatpages.urls')), + path('pages/', include('django.contrib.flatpages.urls')), ] You can also set it up as a "catchall" pattern. In this case, it is important @@ -84,7 +84,7 @@ to place the pattern at the end of the other urlpatterns:: # Your other patterns here urlpatterns += [ - url(r'^(?P<url>.*/)$', views.flatpage), + path('<path:url>', views.flatpage), ] .. warning:: @@ -100,8 +100,8 @@ tag:: from django.contrib.flatpages import views urlpatterns += [ - url(r'^about-us/$', views.flatpage, {'url': '/about-us/'}, name='about'), - url(r'^license/$', views.flatpage, {'url': '/license/'}, name='license'), + path('about-us/', views.flatpage, {'url': '/about-us/'}, name='about'), + path('license/', views.flatpage, {'url': '/license/'}, name='license'), ] Using the middleware @@ -345,15 +345,15 @@ Example Here's an example of a URLconf using :class:`FlatPageSitemap`:: - from django.conf.urls import url from django.contrib.flatpages.sitemaps import FlatPageSitemap from django.contrib.sitemaps.views import sitemap + from django.urls import path urlpatterns = [ # ... # the sitemap - url(r'^sitemap\.xml$', sitemap, + path('sitemap.xml', sitemap, {'sitemaps': {'flatpages': FlatPageSitemap}}, name='django.contrib.sitemaps.views.sitemap'), ] diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index 7ab3c81415..10f97333cc 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -716,11 +716,11 @@ Let's dive right in. Create a file called ``admin.py`` inside the Next, edit your ``urls.py`` in the ``geodjango`` application folder as follows:: - from django.conf.urls import url, include from django.contrib.gis import admin + from django.urls import path, include urlpatterns = [ - url(r'^admin/', admin.site.urls), + path('admin/', admin.site.urls), ] Create an admin user: diff --git a/docs/ref/contrib/sitemaps.txt b/docs/ref/contrib/sitemaps.txt index 9196bc2a5f..dd720a8bb0 100644 --- a/docs/ref/contrib/sitemaps.txt +++ b/docs/ref/contrib/sitemaps.txt @@ -56,8 +56,8 @@ To activate sitemap generation on your Django site, add this line to your from django.contrib.sitemaps.views import sitemap - url(r'^sitemap\.xml$', sitemap, {'sitemaps': sitemaps}, - name='django.contrib.sitemaps.views.sitemap') + path('sitemap.xml', sitemap, {'sitemaps': sitemaps}, + name='django.contrib.sitemaps.views.sitemap') This tells Django to build a sitemap when a client accesses :file:`/sitemap.xml`. @@ -283,9 +283,9 @@ Example Here's an example of a :doc:`URLconf </topics/http/urls>` using :class:`GenericSitemap`:: - from django.conf.urls import url from django.contrib.sitemaps import GenericSitemap from django.contrib.sitemaps.views import sitemap + from django.urls import path from blog.models import Entry info_dict = { @@ -298,9 +298,9 @@ Here's an example of a :doc:`URLconf </topics/http/urls>` using # ... # the sitemap - url(r'^sitemap\.xml$', sitemap, - {'sitemaps': {'blog': GenericSitemap(info_dict, priority=0.6)}}, - name='django.contrib.sitemaps.views.sitemap'), + path('sitemap.xml', sitemap, + {'sitemaps': {'blog': GenericSitemap(info_dict, priority=0.6)}}, + name='django.contrib.sitemaps.views.sitemap'), ] .. _URLconf: ../url_dispatch/ @@ -328,8 +328,8 @@ the ``location`` method of the sitemap. For example:: return reverse(item) # urls.py - from django.conf.urls import url from django.contrib.sitemaps.views import sitemap + from django.urls import path from .sitemaps import StaticViewSitemap from . import views @@ -339,12 +339,12 @@ the ``location`` method of the sitemap. For example:: } urlpatterns = [ - url(r'^$', views.main, name='main'), - url(r'^about/$', views.about, name='about'), - url(r'^license/$', views.license, name='license'), + path('', views.main, name='main'), + path('about/', views.about, name='about'), + path('license/', views.license, name='license'), # ... - url(r'^sitemap\.xml$', sitemap, {'sitemaps': sitemaps}, - name='django.contrib.sitemaps.views.sitemap') + path('sitemap.xml', sitemap, {'sitemaps': sitemaps}, + name='django.contrib.sitemaps.views.sitemap') ] @@ -367,9 +367,9 @@ Here's what the relevant URLconf lines would look like for the example above:: from django.contrib.sitemaps import views urlpatterns = [ - url(r'^sitemap\.xml$', views.index, {'sitemaps': sitemaps}), - url(r'^sitemap-(?P<section>.+)\.xml$', views.sitemap, {'sitemaps': sitemaps}, - name='django.contrib.sitemaps.views.sitemap'), + path('sitemap.xml', views.index, {'sitemaps': sitemaps}), + path('sitemap-<section>.xml', views.sitemap, {'sitemaps': sitemaps}, + name='django.contrib.sitemaps.views.sitemap'), ] This will automatically generate a :file:`sitemap.xml` file that references @@ -389,12 +389,12 @@ with a caching decorator -- you must name your sitemap view and pass from django.views.decorators.cache import cache_page urlpatterns = [ - url(r'^sitemap\.xml$', - cache_page(86400)(sitemaps_views.index), - {'sitemaps': sitemaps, 'sitemap_url_name': 'sitemaps'}), - url(r'^sitemap-(?P<section>.+)\.xml$', - cache_page(86400)(sitemaps_views.sitemap), - {'sitemaps': sitemaps}, name='sitemaps'), + path('sitemap.xml', + cache_page(86400)(sitemaps_views.index), + {'sitemaps': sitemaps, 'sitemap_url_name': 'sitemaps'}), + path('sitemap-<section>.xml', + cache_page(86400)(sitemaps_views.sitemap), + {'sitemaps': sitemaps}, name='sitemaps'), ] @@ -408,11 +408,11 @@ parameter to the ``sitemap`` and ``index`` views via the URLconf:: from django.contrib.sitemaps import views urlpatterns = [ - url(r'^custom-sitemap\.xml$', views.index, { + path('custom-sitemap.xml', views.index, { 'sitemaps': sitemaps, 'template_name': 'custom_sitemap.html' }), - url(r'^custom-sitemap-(?P<section>.+)\.xml$', views.sitemap, { + path('custom-sitemap-<section>.xml', views.sitemap, { 'sitemaps': sitemaps, 'template_name': 'custom_sitemap.html' }, name='django.contrib.sitemaps.views.sitemap'), diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index b8cadb5ec8..389f2edbc8 100644 --- a/docs/ref/contrib/staticfiles.txt +++ b/docs/ref/contrib/staticfiles.txt @@ -462,10 +462,11 @@ primary URL configuration:: from django.conf import settings from django.contrib.staticfiles import views + from django.urls import re_path if settings.DEBUG: urlpatterns += [ - url(r'^static/(?P<path>.*)$', views.serve), + re_path(r'^static/(?P<path>.*)$', views.serve), ] Note, the beginning of the pattern (``r'^static/'``) should be your diff --git a/docs/ref/contrib/syndication.txt b/docs/ref/contrib/syndication.txt index d8e59edc85..8fa5965a72 100644 --- a/docs/ref/contrib/syndication.txt +++ b/docs/ref/contrib/syndication.txt @@ -77,12 +77,12 @@ a feed of the latest five news items:: To connect a URL to this feed, put an instance of the Feed object in your :doc:`URLconf </topics/http/urls>`. For example:: - from django.conf.urls import url + from django.urls import path from myproject.feeds import LatestEntriesFeed urlpatterns = [ # ... - url(r'^latest/feed/$', LatestEntriesFeed()), + path('latest/feed/', LatestEntriesFeed()), # ... ] @@ -217,7 +217,7 @@ The police beat feeds could be accessible via URLs like this: These can be matched with a :doc:`URLconf </topics/http/urls>` line such as:: - url(r'^beats/(?P<beat_id>[0-9]+)/rss/$', BeatFeed()), + path('beats/<int:beat_id>/rss/', BeatFeed()), Like a view, the arguments in the URL are passed to the ``get_object()`` method along with the request object. @@ -366,13 +366,13 @@ Here's a full example:: And the accompanying URLconf:: - from django.conf.urls import url + from django.urls import path from myproject.feeds import RssSiteNewsFeed, AtomSiteNewsFeed urlpatterns = [ # ... - url(r'^sitenews/rss/$', RssSiteNewsFeed()), - url(r'^sitenews/atom/$', AtomSiteNewsFeed()), + path('sitenews/rss/', RssSiteNewsFeed()), + path('sitenews/atom/', AtomSiteNewsFeed()), # ... ] diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt index c4ad02f529..49e07aeec2 100644 --- a/docs/ref/templates/builtins.txt +++ b/docs/ref/templates/builtins.txt @@ -1115,11 +1115,11 @@ hard-code URLs in your templates:: {% url 'some-url-name' v1 v2 %} -The first argument is a :func:`~django.conf.urls.url` ``name``. It can be a -quoted literal or any other context variable. Additional arguments are optional -and should be space-separated values that will be used as arguments in the URL. -The example above shows passing positional arguments. Alternatively you may -use keyword syntax:: +The first argument is a :ref:`URL pattern name <naming-url-patterns>`. It can +be a quoted literal or any other context variable. Additional arguments are +optional and should be space-separated values that will be used as arguments in +the URL. The example above shows passing positional arguments. Alternatively +you may use keyword syntax:: {% url 'some-url-name' arg1=v1 arg2=v2 %} @@ -1132,14 +1132,14 @@ takes a client ID (here, ``client()`` is a method inside the views file .. code-block:: python - ('^client/([0-9]+)/$', app_views.client, name='app-views-client') + path('client/<int:id>/', app_views.client, name='app-views-client') If this app's URLconf is included into the project's URLconf under a path such as this: .. code-block:: python - ('^clients/', include('project_name.app_name.urls')) + path('clients/', include('project_name.app_name.urls')) ...then, in a template, you can create a link to this view like this:: @@ -1179,8 +1179,8 @@ by the context as to the current application. .. warning:: - Don't forget to put quotes around the :func:`~django.conf.urls.url` - ``name``, otherwise the value will be interpreted as a context variable! + Don't forget to put quotes around the URL pattern ``name``, otherwise the + value will be interpreted as a context variable! .. templatetag:: verbatim diff --git a/docs/ref/urlresolvers.txt b/docs/ref/urlresolvers.txt index 2e6bc463dd..aa814a9e40 100644 --- a/docs/ref/urlresolvers.txt +++ b/docs/ref/urlresolvers.txt @@ -17,7 +17,7 @@ callable view object. For example, given the following ``url``:: from news import views - url(r'^archive/$', views.archive, name='news-archive') + path('archive/', views.archive, name='news-archive') you can use any of the following to reverse the URL:: diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index 3b6a66032d..f290276dec 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -5,7 +5,79 @@ .. module:: django.urls.conf :synopsis: Functions for use in URLconfs. -.. currentmodule:: django.conf.urls +.. currentmodule:: django.urls + +``path()`` +========== + +.. function:: path(route, view, kwargs=None, name=None) + +.. versionadded:: 2.0 + +Returns an element for inclusion in ``urlpatterns``. For example:: + + from django.urls import include, path + + urlpatterns = [ + path('index/', views.index, name='main-view'), + path('bio/<username>/', views.bio, name='bio'), + path('articles/<slug:title>/', views.article, name='article-detail'), + path('articles/<slug:title>/<int:section>/', views.section, name='article-section'), + path('weblog/', include('blog.urls')), + ... + ] + +The ``route`` argument should be a string or +:func:`~django.utils.translation.gettext_lazy()` (see +:ref:`translating-urlpatterns`) that contains a URL pattern. The string +may contain angle brackets (like ``<username>`` above) to capture part of the +URL and send it as a keyword argument to the view. The angle brackets may +include a converter specification (like the ``int`` part of ``<int:section>``) +which limits the characters matched and may also change the type of the +variable passed to the view. For example, ``<int:section>`` matches a string +of decimal digits and converts the value to an ``int``. See +:ref:`how-django-processes-a-request` for more details. + +The ``view`` argument is a view function or the result of +:meth:`~django.views.generic.base.View.as_view` for class-based views. It can +also be an :func:`django.urls.include`. + +The ``kwargs`` argument 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`` +argument is useful. + +``re_path()`` +============= + +.. function:: re_path(route, view, kwargs=None, name=None) + +.. versionadded:: 2.0 + +Returns an element for inclusion in ``urlpatterns``. For example:: + + from django.urls import include, re_path + + urlpatterns = [ + re_path(r'^index/$', views.index, name='index'), + re_path(r'^bio/(?P<username>\w+)/$', views.bio, name='bio'), + re_path(r'^weblog/', include('blog.urls')), + ... + ] + +The ``route`` argument should be a string or +:func:`~django.utils.translation.gettext_lazy()` (see +:ref:`translating-urlpatterns`) that contains a regular expression compatible +with Python's :py:mod:`re` module. Strings typically use raw string syntax +(``r''``) so that they can contain sequences like ``\d`` without the need to +escape the backslash with another backslash. When a match is made, captured +groups from the regular expression are passed to the view -- as named arguments +if the groups are named, and as positional arguments otherwise. The values are +passed as strings, without any type conversion. + +The ``view``, ``kwargs`` and ``name`` arguments are the same as for +:func:`~django.urls.path()`. ``include()`` ============= @@ -30,7 +102,7 @@ :arg module: URLconf module (or module name) :arg namespace: Instance namespace for the URL entries being included :type namespace: string - :arg pattern_list: Iterable of :func:`django.conf.urls.url` instances + :arg pattern_list: Iterable of :func:`~django.urls.path` and/or :func:`~django.urls.re_path` 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 @@ -43,6 +115,20 @@ See :ref:`including-other-urlconfs` and :ref:`namespaces-and-include`. In older versions, this function is located in ``django.conf.urls``. The old location still works for backwards compatibility. +``register_converter()`` +======================== + +.. function:: register_converter(converter, type_name) + +.. versionadded:: 2.0 + +The function for registering a converter for use in :func:`~django.urls.path()` +``route``\s. + +The ``converter`` argument is a converter class, and ``type_name`` is the +converter name to use in path patterns. See +:ref:`registering-custom-path-converters` for an example. + ================================================== ``django.conf.urls`` functions for use in URLconfs ================================================== @@ -68,32 +154,8 @@ Helper function to return a URL pattern for serving files in debug mode:: .. function:: url(regex, view, kwargs=None, name=None) -``urlpatterns`` should be a list of ``url()`` instances. For example:: - - from django.conf.urls import include, url - - urlpatterns = [ - url(r'^index/$', index_view, name='main-view'), - url(r'^weblog/', include('blog.urls')), - ... - ] - -The ``regex`` parameter should be a string or -:func:`~django.utils.translation.gettext_lazy()` (see -:ref:`translating-urlpatterns`) that contains a regular expression compatible -with Python's :py:mod:`re` module. Strings typically use raw string syntax -(``r''``) so that they can contain sequences like ``\d`` without the need to -escape the backslash with another backslash. - -The ``view`` parameter is a view function or the result of -:meth:`~django.views.generic.base.View.as_view` for class-based views. It can -also be an :func:`include`. - -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. +This function is an alias to :func:`django.urls.re_path()`. It's likely to be +deprecated in a future release. ``handler400`` ============== diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt index 240cb80485..55a733f376 100644 --- a/docs/ref/utils.txt +++ b/docs/ref/utils.txt @@ -823,8 +823,8 @@ appropriate entities. from django.utils.translation import pgettext_lazy urlpatterns = [ - url(format_lazy(r'{person}/(?P<pk>\d+)/$', person=pgettext_lazy('URL', 'person')), - PersonDetailView.as_view()), + path(format_lazy('{person}/<int:pk>/', person=pgettext_lazy('URL', 'person')), + PersonDetailView.as_view()), ] This example allows translators to translate part of the URL. If "person" diff --git a/docs/ref/views.txt b/docs/ref/views.txt index dd1897c915..37204e2fda 100644 --- a/docs/ref/views.txt +++ b/docs/ref/views.txt @@ -26,13 +26,14 @@ built-in handling for user-uploaded files, but you can have Django serve your :setting:`MEDIA_ROOT` by appending something like this to your URLconf:: from django.conf import settings + from django.urls import re_path from django.views.static import serve # ... the rest of your URLconf goes here ... if settings.DEBUG: urlpatterns += [ - url(r'^media/(?P<path>.*)$', serve, { + re_path(r'^media/(?P<path>.*)$', serve, { 'document_root': settings.MEDIA_ROOT, }), ] |