[Python-checkins] Improve docstring of list.sort (GH-8516)

Raymond Hettinger webhook-mailer at python.org
Sat Jun 1 00:10:07 EDT 2019


https://github.com/python/cpython/commit/5c22476c01622f11b7745ee693f8b296a9d6a761
commit: 5c22476c01622f11b7745ee693f8b296a9d6a761
branch: master
author: Tim Hoffmann <2836374+timhoffm at users.noreply.github.com>
committer: Raymond Hettinger <rhettinger at users.noreply.github.com>
date: 2019-05-31T21:10:02-07:00
summary:

Improve docstring of list.sort (GH-8516)

files:
M Objects/clinic/listobject.c.h
M Objects/listobject.c

diff --git a/Objects/clinic/listobject.c.h b/Objects/clinic/listobject.c.h
index 7b8e2d9905f9..57f0a48eb083 100644
--- a/Objects/clinic/listobject.c.h
+++ b/Objects/clinic/listobject.c.h
@@ -156,7 +156,15 @@ PyDoc_STRVAR(list_sort__doc__,
 "sort($self, /, *, key=None, reverse=False)\n"
 "--\n"
 "\n"
-"Stable sort *IN PLACE*.");
+"Sort the list in ascending order and return None.\n"
+"\n"
+"The sort is in-place (i.e. the list itself is modified) and stable (i.e. the\n"
+"order of two equal elements is maintained).\n"
+"\n"
+"If a key function is given, apply it once to each list item and sort them,\n"
+"ascending or descending, according to their function values.\n"
+"\n"
+"The reverse flag can be set to sort in descending order.");
 
 #define LIST_SORT_METHODDEF    \
     {"sort", (PyCFunction)(void(*)(void))list_sort, METH_FASTCALL|METH_KEYWORDS, list_sort__doc__},
@@ -359,4 +367,4 @@ list___reversed__(PyListObject *self, PyObject *Py_UNUSED(ignored))
 {
     return list___reversed___impl(self);
 }
-/*[clinic end generated code: output=d1d5078edb7d3cf4 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=73718c0c33798c62 input=a9049054013a1b77]*/
diff --git a/Objects/listobject.c b/Objects/listobject.c
index 233f13dbab0e..f8bf45e5f8cd 100644
--- a/Objects/listobject.c
+++ b/Objects/listobject.c
@@ -2197,12 +2197,20 @@ list.sort
     key as keyfunc: object = None
     reverse: bool(accept={int}) = False
 
-Stable sort *IN PLACE*.
+Sort the list in ascending order and return None.
+
+The sort is in-place (i.e. the list itself is modified) and stable (i.e. the
+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.
+
+The reverse flag can be set to sort in descending order.
 [clinic start generated code]*/
 
 static PyObject *
 list_sort_impl(PyListObject *self, PyObject *keyfunc, int reverse)
-/*[clinic end generated code: output=57b9f9c5e23fbe42 input=b0fcf743982c5b90]*/
+/*[clinic end generated code: output=57b9f9c5e23fbe42 input=cb56cd179a713060]*/
 {
     MergeState ms;
     Py_ssize_t nremaining;



More information about the Python-checkins mailing list