Document path converter regexes and limitation

README.rst

@@ -241,11 +241,6 @@ Rewrites imports of ``include()`` and ``url()`` from ``django.conf.urls`` to ``d
 .. |new path() syntax| replace:: new ``path()`` syntax
 __ https://docs.djangoproject.com/en/2.0/releases/2.0/#simplified-url-routing-syntax
 
-For some cases, this change alters the type of the arguments passed to the view, from ``str`` to the converted type (e.g. ``int``).
-This is not guaranteed backwards compatible: there is a chance that the view expects a string, rather than the converted type.
-But, pragmatically, it seems 99.9% of views do not require strings, and instead work with either strings or the converted type.
-Thus, you should test affected paths after this fixer makes any changes.
-
 .. code-block:: diff
 
     -from django.conf.urls import include, url
@@ -272,9 +267,27 @@ Existing ``re_path()`` calls are also rewritten to the ``path()`` syntax when el
      urlpatterns = [
     -    re_path(r'^about/$', views.about, name='about'),
     +    path('about/', views.about, name='about'),
-         re_path(r'^post/(?P<slug>[w-]+)/$', views.post, name='post'),
+         re_path(r'^post/(?P<slug>[\w-]+)/$', views.post, name='post'),
      ]
 
+The compatible regexes that will be converted to use `path converters <https://docs.djangoproject.com/en/stable/topics/http/urls/#path-converters>`__ are the following:
+
+* ``[^/]+`` → ``str``
+* ``[0-9]+`` → ``int``
+* ``[-a-zA-Z0-9_]+`` → ``slug``
+* ``[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}`` → ``uuid``
+* ``.+`` → ``path``
+
+These are taken from the path converter classes.
+
+For some cases, this change alters the type of the arguments passed to the view, from ``str`` to the converted type (e.g. ``int``).
+This is not guaranteed backwards compatible: there is a chance that the view expects a string, rather than the converted type.
+But, pragmatically, it seems 99.9% of views do not require strings, and instead work with either strings or the converted type.
+Thus, you should test affected paths after this fixer makes any changes.
+
+Note that ``[\w-]`` is sometimes used for slugs, but is not converted because it might be incompatible.
+That pattern matches all Unicode word characters, such as “α”, unlike Django's ``slug`` converter, which only matches Latin characters.
+
 ``lru_cache``
 ~~~~~~~~~~~~~
 
@@ -294,7 +307,7 @@ In practice, most display functions that return HTML already use |format_html()|
 This only applies in files that use ``from django.contrib import admin`` or ``from django.contrib.gis import admin``.
 
 .. |format_html()| replace:: ``format_html()``
-__ https://docs.djangoproject.com/en/tsable/ref/utils/#django.utils.html.format_html
+__ https://docs.djangoproject.com/en/stable/ref/utils/#django.utils.html.format_html
 
 .. code-block:: diff
 

tests/fixers/test_django_urls.py

@@ -398,7 +398,7 @@ def test_complete():
             url(r'^$', views.index, name='index'),
             url(r'^about/$', views.about, name='about'),
             url(r'^post/(?P<slug>[-a-zA-Z0-9_]+)/$', views.post, name='post'),
-            url(r'^post/(?P<slug>[w-]+)/$', views.post, name='post'),
+            url(r'^post/(?P<slug>[\\w-]+)/$', views.post, name='post'),
             url(r'^weblog/', include('blog.urls')),
         ]
         """,
@@ -409,7 +409,7 @@ def test_complete():
             path('', views.index, name='index'),
             path('about/', views.about, name='about'),
             path('post/<slug:slug>/', views.post, name='post'),
-            re_path(r'^post/(?P<slug>[w-]+)/$', views.post, name='post'),
+            re_path(r'^post/(?P<slug>[\\w-]+)/$', views.post, name='post'),
             re_path(r'^weblog/', include('blog.urls')),
         ]
         """,