From 6d34512dcdcc1d9286f93f4a5a45e51fe3952559 Mon Sep 17 00:00:00 2001
From: edvatar <88481784+toroleapinc@users.noreply.github.com>
Date: Tue, 3 Mar 2026 00:49:34 -0500
Subject: [PATCH 1/2] docs: document SupportsInt conversion behavior for query
 params

Document that objects implementing SupportsInt (such as uuid.UUID)
are converted to int when used as query parameter values. This can
lead to unexpected results, e.g. a UUID being represented as a large
integer rather than its standard string form.

Added a warning to the with_query documentation with a concrete
uuid.UUID example showing the correct usage pattern.

Closes #1458

Signed-off-by: edvatar <88481784+toroleapinc@users.noreply.github.com>
---
 CHANGES/1458.doc.rst |  4 ++++
 docs/api.rst         | 19 +++++++++++++++++++
 yarl/_query.py       |  7 ++++++-
 3 files changed, 29 insertions(+), 1 deletion(-)
 create mode 100644 CHANGES/1458.doc.rst

diff --git a/CHANGES/1458.doc.rst b/CHANGES/1458.doc.rst
new file mode 100644
index 000000000..81e7f97c9
--- /dev/null
+++ b/CHANGES/1458.doc.rst
@@ -0,0 +1,4 @@
+Documented that objects implementing :class:`~typing.SupportsInt` (such as
+:class:`uuid.UUID`) are converted to :class:`int` when used as query parameter
+values, and that explicit conversion to :class:`str` is needed if the string
+representation is desired -- by :user:`edvatar`.
diff --git a/docs/api.rst b/docs/api.rst
index 69417bdd5..b61936f07 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -696,6 +696,25 @@ section generates a new :class:`URL` instance.
       Please see :ref:`yarl-bools-support` for the reason why :class:`bool` is not
       supported out-of-the-box.
 
+   .. warning::
+
+      Any object implementing :class:`~typing.SupportsInt` (i.e. having an
+      ``__int__`` method) will be converted to :class:`int` before being used
+      as a query parameter value. This includes types such as :class:`uuid.UUID`,
+      which will be converted to their integer representation rather than their
+      string representation. To avoid unexpected results, explicitly convert such
+      values to :class:`str` before passing them as query parameters:
+
+      .. code-block:: python
+
+         import uuid
+
+         my_uuid = uuid.UUID("3199712f-1b78-4420-852b-a73ee09e6a8f")
+         # Wrong: will use int(my_uuid) -> a large integer
+         url = URL("http://example.com/").with_query({"id": my_uuid})
+         # Correct: explicitly convert to string
+         url = URL("http://example.com/").with_query({"id": str(my_uuid)})
+
    .. doctest::
 
       >>> URL('http://example.com/path?a=b').with_query('c=d')
diff --git a/yarl/_query.py b/yarl/_query.py
index 809948d9a..8369ee8c5 100644
--- a/yarl/_query.py
+++ b/yarl/_query.py
@@ -16,7 +16,12 @@
 
 
 def query_var(v: SimpleQuery) -> str:
-    """Convert a query variable to a string."""
+    """Convert a query variable to a string.
+
+    Note: Objects implementing ``SupportsInt`` (e.g. ``uuid.UUID``) will be
+    converted via ``int()`` first. Callers should convert such values to ``str``
+    explicitly if the string representation is desired.
+    """
     cls = type(v)
     if cls is int:  # Fast path for non-subclassed int
         return str(v)

From 53d874cb22c0f08aa37ae176012fa34161afb31f Mon Sep 17 00:00:00 2001
From: Eddie Liang <toroleapinc@gmail.com>
Date: Sat, 7 Mar 2026 20:43:15 -0500
Subject: [PATCH 2/2] Address review: use cross-ref for __int__ method

---
 docs/api.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/api.rst b/docs/api.rst
index b61936f07..4149af995 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -699,7 +699,7 @@ section generates a new :class:`URL` instance.
    .. warning::
 
       Any object implementing :class:`~typing.SupportsInt` (i.e. having an
-      ``__int__`` method) will be converted to :class:`int` before being used
+      :external+python:meth:`~object.__int__` method) will be converted to :class:`int` before being used
       as a query parameter value. This includes types such as :class:`uuid.UUID`,
       which will be converted to their integer representation rather than their
       string representation. To avoid unexpected results, explicitly convert such