[Python-checkins] gh-92780: Improve sqlite3.Connection.create_collation docs (GH-92790)

miss-islington webhook-mailer at python.org
Wed May 18 08:05:28 EDT 2022


https://github.com/python/cpython/commit/94e21cf2299c7a2b6fdb4ddc6f1f2a879a83d21f
commit: 94e21cf2299c7a2b6fdb4ddc6f1f2a879a83d21f
branch: 3.10
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2022-05-18T05:05:24-07:00
summary:

gh-92780: Improve sqlite3.Connection.create_collation docs (GH-92790)


Co-authored-by: Alex Waygood <Alex.Waygood at Gmail.com>
(cherry picked from commit 7ee19e27150a72eec9e6a076792e3c3ae8bcffbd)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland at protonmail.com>

files:
M Doc/library/sqlite3.rst

diff --git a/Doc/library/sqlite3.rst b/Doc/library/sqlite3.rst
index 3fac2db174c33..a430144bd5e75 100644
--- a/Doc/library/sqlite3.rst
+++ b/Doc/library/sqlite3.rst
@@ -436,22 +436,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 <str>` arguments,
+      and it should return an :class:`integer <int>`:
 
-      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`.
 
 
    .. method:: interrupt()



More information about the Python-checkins mailing list