From ba8993fa42401da97a8e03e2d9bf44aeac70b274 Mon Sep 17 00:00:00 2001 From: Erlend Egeberg Aasland Date: Wed, 18 May 2022 13:44:16 +0200 Subject: [PATCH] gh-92780: Improve sqlite3.Connection.create_collation docs (GH-92790) Co-authored-by: Alex Waygood (cherry picked from commit 7ee19e27150a72eec9e6a076792e3c3ae8bcffbd) Co-authored-by: Erlend Egeberg Aasland --- Doc/library/sqlite3.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst index 69e77e922a9ab7..1843e22640f014 100644 --- a/Doc/library/sqlite3.rst +++ b/Doc/library/sqlite3.rst @@ -518,22 +518,19 @@ 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 an :class:`integer `: - Note that the callable will get its parameters as Python bytestrings, which will - normally be encoded in UTF-8. + * ``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 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