docs

Author: dg-pb

Doc/library/stdtypes.rst

@@ -1394,7 +1394,7 @@ application).
    :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
    following additional method:
 
-   .. method:: list.sort(*, key=None, reverse=False)
+   .. method:: list.sort(*, key=None, keylist=None, reverse=False)
 
       This method sorts the list in place, using only ``<`` comparisons
       between items. Exceptions are not suppressed - if any comparison operations
@@ -1414,6 +1414,9 @@ application).
       The :func:`functools.cmp_to_key` utility is available to convert a 2.x
       style *cmp* function to a *key* function.
 
+      Alternative to key function is supplying a list to *keylist* argument,
+      which will determine sort order and will be modified in place.
+
       *reverse* is a boolean value.  If set to ``True``, then the list elements
       are sorted as if each comparison were reversed.
 
@@ -1436,6 +1439,11 @@ application).
          list appear empty for the duration, and raises :exc:`ValueError` if it can
          detect that the list has been mutated during a sort.
 
+         The same applies to *keylist* argument.
+
+      .. versionchanged:: 3.15
+
+         Added *keylist* argument.
 
 .. _typesseq-tuple:
 

Objects/listobject.c

@@ -2935,7 +2935,7 @@ order of two equal elements is maintained).
 If a key function is given, apply it once to each list item and sort them,
 ascending or descending, according to their function values.
 
-Alternative to key function is supplying list to keylist argument,
+Alternative to key function is supplying a list to keylist argument,
 which will determine sort order and will be modified in place.
 
 The reverse flag can be set to sort in descending order.

Python/bltinmodule.c

@@ -2644,7 +2644,8 @@ sorted as builtin_sorted
 Return a new list containing all items from the iterable in ascending order.
 
 A custom key function can be supplied to customize the sort order.
-Alternatively, keylist argument accepts a list on which sort order is based.
+Alternative to key function is supplying a list to keylist argument,
+which will determine sort order and will be modified in place.
 The reverse flag can be set to request the result in descending order.
 Both key and keylist can not be used at the same time.
 [end disabled clinic input]*/
@@ -2656,7 +2657,8 @@ PyDoc_STRVAR(builtin_sorted__doc__,
 "Return a new list containing all items from the iterable in ascending order.\n"
 "\n"
 "A custom key function can be supplied to customize the sort order.\n"
-"Alternatively, keylist argument accepts a list on which sort order is based.\n"
+"Alternative to key function is supplying a list to keylist argument,\n"
+"which will determine sort order and will be modified in place.\n"
 "The reverse flag can be set to request the result in descending order.\n"
 "Both key and keylist can not be used at the same time.");