From 28721810926572acf8e74d2b97a5683745d36643 Mon Sep 17 00:00:00 2001 From: Babata Date: Mon, 23 Mar 2026 22:19:26 +0800 Subject: [PATCH] docs: note UUID-to-int coercion in with_query docs (#1458) Types implementing __int__ (e.g. uuid.UUID) are converted to integers by the query parameter API because int is preferred over str for numeric coercion. Add a tip with a doctest showing how to cast to str to get the human-readable representation. --- CHANGES/1645.doc.rst | 4 ++++ docs/api.rst | 14 ++++++++++++++ 2 files changed, 18 insertions(+) create mode 100644 CHANGES/1645.doc.rst diff --git a/CHANGES/1645.doc.rst b/CHANGES/1645.doc.rst new file mode 100644 index 000000000..c093430a2 --- /dev/null +++ b/CHANGES/1645.doc.rst @@ -0,0 +1,4 @@ +Added a note in the :meth:`~yarl.URL.with_query` documentation explaining +that types implementing ``__int__`` (e.g. :class:`~uuid.UUID`) are +converted to integers, and advising users to cast to :class:`str` when the +human-readable representation is needed. diff --git a/docs/api.rst b/docs/api.rst index 69417bdd5..704befb9b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -696,6 +696,20 @@ 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. + .. tip:: + + Types that implement :meth:`~object.__int__` (e.g. :class:`~uuid.UUID`) + are converted to integers because :class:`int` is preferred over + :class:`str` for numeric coercion. If you need the human-readable + representation, cast the value to :class:`str` before passing it: + + .. doctest:: + + >>> import uuid + >>> uid = uuid.UUID('3199712f-1b78-4420-852b-a73ee09e6a8f') + >>> URL('http://example.com/').with_query({'id': str(uid)}) + URL('http://example.com/?id=3199712f-1b78-4420-852b-a73ee09e6a8f') + .. doctest:: >>> URL('http://example.com/path?a=b').with_query('c=d')