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.

7 files changed, 66 insertions, 61 deletions

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()),
         # ...
     ]