[issue28754] Argument Clinic for bisect.bisect_left

[STINNER Victor]

STINNER Victor added the comment:

Martin: "Victor, what changes to the doc strings are you talking about?"

See attached check_bisect_doc.py script.

Before:
---
=== bisect_right ===
bisect_right(a, x[, lo[, hi]]) -> index

Return the index where to insert item x in list a, assuming a is sorted.

The return value i is such that all e in a[:i] have e <= x, and all e in
a[i:] have e > x.  So if x already appears in the list, i points just
beyond the rightmost x already there

Optional args lo (default 0) and hi (default len(a)) bound the
slice of a to be searched.

=== insort_right ===
insort_right(a, x[, lo[, hi]])

Insert item x in list a, and keep it sorted assuming a is sorted.

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.

=== bisect_left ===
bisect_left(a, x[, lo[, hi]]) -> index

Return the index where to insert item x in list a, assuming a is sorted.

The return value i is such that all e in a[:i] have e < x, and all e in
a[i:] have e >= x.  So if x already appears in the list, i points 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.

=== insort_left ===
insort_left(a, x[, lo[, hi]])

Insert item x in list a, and keep it sorted assuming a is sorted.

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.

---

After:
---
=== bisect_right ===
Return the index where to insert item x in list a, assuming a is sorted.

  a
    The list in which x is to be inserted.
  x
    The value to be inserted.
  lo
    Lower bound, defaults to 0.
  hi
    Upper bound, defaults to -1 (meaning len(a)).

The return value i is such that all e in a[:i] have e <= x, and all e in
a[i:] have e > x.  So if x already appears in the list, i points just
beyond the rightmost x already there.

Optional args lo and hi bound the slice of a to be searched.
=== insort_right ===
Insert item x in list a, and keep it sorted assuming a is sorted.

  a
    The list in which x will be inserted.
  x
    The value to insert.
  lo
    Lower bound, defaults to 0.
  hi
    Upper bound, defaults to -1 (meaning len(a)).

If x is already in a, insert it to the right of the rightmost x.

Optional args lo and hi bound the slice of a to be searched.
=== bisect_left ===
Return the index where to insert item x in list a, assuming a is sorted.

  a
    The list in which x is to be inserted.
  x
    The value to be inserted.
  lo
    Lower bound, defaults to 0.
  hi
    Upper bound, defaults to -1 (meaning len(a)).

The return value i is such that all e in a[:i] have e < x, and all e in
a[i:] have e >= x.  So if x already appears in the list, i points just
before the leftmost x already there.

Optional args lo and hi bound the slice of a to be searched.
=== insort_left ===
Insert item x in list a, and keep it sorted assuming a is sorted.

  a
    The list in which x will be inserted.
  x
    The value to insert.
  lo
    Lower bound, defaults to 0.
  hi
    Upper bound, defaults to -1 (meaning len(a)).

If x is already in a, insert it to the left of the leftmost x.

Optional args lo and hi bound the slice of a to be searched.

---

The output is different. I suggest to not touch the docstring in the patch upgrading _bisect.c to Argument Clinic to ease the review.

----------
Added file: http://bugs.python.org/file45642/check_bisect_doc.py

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28754>
_______________________________________