diff options
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, }), ] |