[Python-checkins] GH-102833: Mention the key function in the docstrings (GH-103009)

[rhettinger]

https://github.com/python/cpython/commit/1fd603fad20187496619930e5b74aa7690425926
commit: 1fd603fad20187496619930e5b74aa7690425926
branch: main
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2023-03-25T02:19:20-05:00
summary:

GH-102833: Mention the key function in the docstrings (GH-103009)

files:
M Lib/bisect.py
M Modules/_bisectmodule.c
M Modules/clinic/_bisectmodule.c.h

diff --git a/Lib/bisect.py b/Lib/bisect.py
index d37da74f7b40..ca6ca7240840 100644
--- a/Lib/bisect.py
+++ b/Lib/bisect.py
@@ -8,6 +8,8 @@ def insort_right(a, x, lo=0, hi=None, *, key=None):
 
     Optional args lo (default 0) and hi (default len(a)) bound the
     slice of a to be searched.
+
+    A custom key function can be supplied to customize the sort order.
     """
     if key is None:
         lo = bisect_right(a, x, lo, hi)
@@ -25,6 +27,8 @@ def bisect_right(a, x, lo=0, hi=None, *, key=None):
 
     Optional args lo (default 0) and hi (default len(a)) bound the
     slice of a to be searched.
+
+    A custom key function can be supplied to customize the sort order.
     """
 
     if lo < 0:
@@ -57,6 +61,8 @@ def insort_left(a, x, lo=0, hi=None, *, key=None):
 
     Optional args lo (default 0) and hi (default len(a)) bound the
     slice of a to be searched.
+
+    A custom key function can be supplied to customize the sort order.
     """
 
     if key is None:
@@ -74,6 +80,8 @@ def bisect_left(a, x, lo=0, hi=None, *, key=None):
 
     Optional args lo (default 0) and hi (default len(a)) bound the
     slice of a to be searched.
+
+    A custom key function can be supplied to customize the sort order.
     """
 
     if lo < 0:
diff --git a/Modules/_bisectmodule.c b/Modules/_bisectmodule.c
index d3bec535ee51..30801c2f87ee 100644
--- a/Modules/_bisectmodule.c
+++ b/Modules/_bisectmodule.c
@@ -162,12 +162,14 @@ insert just after the rightmost x already there.
 
 Optional args lo (default 0) and hi (default len(a)) bound the
 slice of a to be searched.
+
+A custom key function can be supplied to customize the sort order.
 [clinic start generated code]*/
 
 static Py_ssize_t
 _bisect_bisect_right_impl(PyObject *module, PyObject *a, PyObject *x,
                           Py_ssize_t lo, Py_ssize_t hi, PyObject *key)
-/*[clinic end generated code: output=3a4bc09cc7c8a73d input=40fcc5afa06ae593]*/
+/*[clinic end generated code: output=3a4bc09cc7c8a73d input=43071869772dd53a]*/
 {
     return internal_bisect_right(a, x, lo, hi, key);
 }
@@ -188,12 +190,14 @@ If x is already in a, insert it to the right of the rightmost x.
 
 Optional args lo (default 0) and hi (default len(a)) bound the
 slice of a to be searched.
+
+A custom key function can be supplied to customize the sort order.
 [clinic start generated code]*/
 
 static PyObject *
 _bisect_insort_right_impl(PyObject *module, PyObject *a, PyObject *x,
                           Py_ssize_t lo, Py_ssize_t hi, PyObject *key)
-/*[clinic end generated code: output=ac3bf26d07aedda2 input=44e1708e26b7b802]*/
+/*[clinic end generated code: output=ac3bf26d07aedda2 input=f60777d2b6ddb239]*/
 {
     PyObject *result, *key_x;
     Py_ssize_t index;
@@ -343,12 +347,14 @@ insert just before the leftmost x already there.
 
 Optional args lo (default 0) and hi (default len(a)) bound the
 slice of a to be searched.
+
+A custom key function can be supplied to customize the sort order.
 [clinic start generated code]*/
 
 static Py_ssize_t
 _bisect_bisect_left_impl(PyObject *module, PyObject *a, PyObject *x,
                          Py_ssize_t lo, Py_ssize_t hi, PyObject *key)
-/*[clinic end generated code: output=70749d6e5cae9284 input=90dd35b50ceb05e3]*/
+/*[clinic end generated code: output=70749d6e5cae9284 input=f29c4fe7f9b797c7]*/
 {
     return internal_bisect_left(a, x, lo, hi, key);
 }
@@ -370,12 +376,14 @@ If x is already in a, insert it to the left of the leftmost x.
 
 Optional args lo (default 0) and hi (default len(a)) bound the
 slice of a to be searched.
+
+A custom key function can be supplied to customize the sort order.
 [clinic start generated code]*/
 
 static PyObject *
 _bisect_insort_left_impl(PyObject *module, PyObject *a, PyObject *x,
                          Py_ssize_t lo, Py_ssize_t hi, PyObject *key)
-/*[clinic end generated code: output=b1d33e5e7ffff11e input=3ab65d8784f585b1]*/
+/*[clinic end generated code: output=b1d33e5e7ffff11e input=0a700a82edbd472c]*/
 {
     PyObject *result, *key_x;
     Py_ssize_t index;
diff --git a/Modules/clinic/_bisectmodule.c.h b/Modules/clinic/_bisectmodule.c.h
index bbf456e4b0f4..7944f5219b02 100644
--- a/Modules/clinic/_bisectmodule.c.h
+++ b/Modules/clinic/_bisectmodule.c.h
@@ -19,7 +19,9 @@ PyDoc_STRVAR(_bisect_bisect_right__doc__,
 "insert just after the rightmost x already there.\n"
 "\n"
 "Optional args lo (default 0) and hi (default len(a)) bound the\n"
-"slice of a to be searched.");
+"slice of a to be searched.\n"
+"\n"
+"A custom key function can be supplied to customize the sort order.");
 
 #define _BISECT_BISECT_RIGHT_METHODDEF    \
     {"bisect_right", _PyCFunction_CAST(_bisect_bisect_right), METH_FASTCALL|METH_KEYWORDS, _bisect_bisect_right__doc__},
@@ -125,7 +127,9 @@ PyDoc_STRVAR(_bisect_insort_right__doc__,
 "If x is already in a, insert it to the right of the rightmost x.\n"
 "\n"
 "Optional args lo (default 0) and hi (default len(a)) bound the\n"
-"slice of a to be searched.");
+"slice of a to be searched.\n"
+"\n"
+"A custom key function can be supplied to customize the sort order.");
 
 #define _BISECT_INSORT_RIGHT_METHODDEF    \
     {"insort_right", _PyCFunction_CAST(_bisect_insort_right), METH_FASTCALL|METH_KEYWORDS, _bisect_insort_right__doc__},
@@ -228,7 +232,9 @@ PyDoc_STRVAR(_bisect_bisect_left__doc__,
 "insert just before the leftmost x already there.\n"
 "\n"
 "Optional args lo (default 0) and hi (default len(a)) bound the\n"
-"slice of a to be searched.");
+"slice of a to be searched.\n"
+"\n"
+"A custom key function can be supplied to customize the sort order.");
 
 #define _BISECT_BISECT_LEFT_METHODDEF    \
     {"bisect_left", _PyCFunction_CAST(_bisect_bisect_left), METH_FASTCALL|METH_KEYWORDS, _bisect_bisect_left__doc__},
@@ -334,7 +340,9 @@ PyDoc_STRVAR(_bisect_insort_left__doc__,
 "If x is already in a, insert it to the left of the leftmost x.\n"
 "\n"
 "Optional args lo (default 0) and hi (default len(a)) bound the\n"
-"slice of a to be searched.");
+"slice of a to be searched.\n"
+"\n"
+"A custom key function can be supplied to customize the sort order.");
 
 #define _BISECT_INSORT_LEFT_METHODDEF    \
     {"insort_left", _PyCFunction_CAST(_bisect_insort_left), METH_FASTCALL|METH_KEYWORDS, _bisect_insort_left__doc__},
@@ -425,4 +433,4 @@ _bisect_insort_left(PyObject *module, PyObject *const *args, Py_ssize_t nargs, P
 exit:
     return return_value;
 }
-/*[clinic end generated code: output=7dc87f7af75275a1 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=5a7fa64bf9b262f3 input=a9049054013a1b77]*/