Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

gh-92780: Improve sqlite3.Connection.create_collation docs #92790

Merged
merged 3 commits into from
May 18, 2022
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 7 additions & 12 deletions Doc/library/sqlite3.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved
Create a collation named *name* using the collating function *callable*.
*callable* is passed two :class:`string <str>` 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.
erlend-aasland marked this conversation as resolved.
Show resolved Hide resolved

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
Expand Down