From 445c621b146a72dfd473ec274a8896b53ef3c102 Mon Sep 17 00:00:00 2001
From: siddus <dcsid10@gmail.com>
Date: Wed, 27 May 2026 16:49:54 -0400
Subject: [PATCH] Fixed #22226 -- Clarified quoting when reversing admin URLs.

---
 docs/ref/contrib/admin/index.txt | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt
index b3c7c2c42699..41075dfee156 100644
--- a/docs/ref/contrib/admin/index.txt
+++ b/docs/ref/contrib/admin/index.txt
@@ -3440,8 +3440,14 @@ call:
 .. code-block:: pycon
 
     >>> from django.urls import reverse
+    >>> from django.contrib.admin.utils import quote
     >>> c = Choice.objects.get(...)
-    >>> change_url = reverse("admin:polls_choice_change", args=(c.id,))
+    >>> change_url = reverse("admin:polls_choice_change", args=(quote(c.pk),))
+
+Admin URLs that take an ``object_id`` expect the primary key to be escaped with
+``django.contrib.admin.utils.quote()``; otherwise reversing can produce URLs
+that the admin fails to resolve when the key contains characters such as ``_``,
+``/``, or ``:``.
 
 This will find the first registered instance of the admin application
 (whatever the instance name), and resolve to the view for changing
@@ -3454,7 +3460,9 @@ if you specifically wanted the admin view from the admin instance named
 
 .. code-block:: pycon
 
-    >>> change_url = reverse("admin:polls_choice_change", args=(c.id,), current_app="custom")
+    >>> change_url = reverse(
+    ...     "admin:polls_choice_change", args=(quote(c.pk),), current_app="custom"
+    ... )
 
 For more details, see the documentation on :ref:`reversing namespaced URLs
 <topics-http-reversing-url-namespaces>`.
@@ -3466,12 +3474,14 @@ To allow easier reversing of the admin urls in templates, Django provides an
 
     {% load admin_urls %}
     <a href="{% url opts|admin_urlname:'add' %}">Add user</a>
-    <a href="{% url opts|admin_urlname:'delete' user.pk %}">Delete this user</a>
+    <a href="{% url opts|admin_urlname:'delete' user.pk|admin_urlquote %}">Delete this user</a>
 
 The action in the examples above match the last part of the URL names for
 :class:`ModelAdmin` instances described above. The ``opts`` variable can be any
 object which has an ``app_label`` and ``model_name`` attributes and is usually
-supplied by the admin views for the current model.
+supplied by the admin views for the current model. The ``admin_urlquote``
+filter is the template equivalent of ``quote()`` above and must be applied to
+primary key values used as ``object_id``.
 
 The ``display`` decorator
 =========================