From b0a5cf43a00000ac9c604fede0dddce1d7f6a53d Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Fri, 13 May 2022 23:37:05 +0200 Subject: [PATCH 1/3] gh-92780: Improve sqlite3.Connection.create_collation docs --- Doc/library/sqlite3.rst | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 69e77e922a9ab7..2a4d989df6b046 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -518,22 +518,17 @@ Connection Objects .. method:: create_collation(name, callable) - Creates a collation with the specified *name* and *callable*. The callable will - be passed two string arguments. It should return -1 if the first is ordered - lower than the second, 0 if they are ordered equal and 1 if the first is ordered - higher than the second. Note that this controls sorting (ORDER BY in SQL) so - your comparisons don't affect other SQL operations. + Create a collation named *name* using the collating function *callable*. + *callable* is passed two :class:`string ` arguments, + and it should return 1 if the first is ordered higher than the second, + -1 if the first is ordered lower than the second, + and 0 if they are ordered equal. - Note that the callable will get its parameters as Python bytestrings, which will - normally be encoded in UTF-8. - - The following example shows a custom collation that sorts "the wrong way": + The following example shows a reverse sorting collation: .. literalinclude:: ../includes/sqlite3/collation_reverse.py - To remove a collation, call ``create_collation`` with ``None`` as callable:: - - con.create_collation("reverse", None) + Remove a collation function by setting *callable* to :const:`None`. .. versionchanged:: 3.11 The collation name can contain any Unicode character. Earlier, only From eb5ee5dd85c509d3eb9d25495dbb2196459d917f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Sun, 15 May 2022 22:22:06 +0200 Subject: [PATCH 2/3] Address Alex' review: improve wording --- Doc/library/sqlite3.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 2a4d989df6b046..f2901e8540a372 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -520,9 +520,11 @@ Connection Objects Create a collation named *name* using the collating function *callable*. *callable* is passed two :class:`string ` arguments, - and it should return 1 if the first is ordered higher than the second, - -1 if the first is ordered lower than the second, - and 0 if they are ordered equal. + and it should return an :class:`int `: + + * ``1`` if the first is ordered higher than the second + * ``-1`` if the first is ordered lower than the second + * ``0`` if they are ordered equal The following example shows a reverse sorting collation: From 8d788dae9b3051aff88f0064de7ce942a839724c Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Mon, 16 May 2022 06:41:04 +0200 Subject: [PATCH 3/3] Update Doc/library/sqlite3.rst Co-authored-by: Alex Waygood --- Doc/library/sqlite3.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index f2901e8540a372..1843e22640f014 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -520,7 +520,7 @@ Connection Objects Create a collation named *name* using the collating function *callable*. *callable* is passed two :class:`string ` arguments, - and it should return an :class:`int `: + and it should return an :class:`integer `: * ``1`` if the first is ordered higher than the second * ``-1`` if the first is ordered lower than the second