Documentation issue.

help(bisect.bisect_left)
says: "... if x already appears in the list, i points just before the leftmost x already there."
but in fact, it actually points *to* the leftmost x already there

I there is a misunderstanding here.  The bisect functions never point *to* a value.  Instead, they are documented to return "insertion points".  Those always occur just before or after a specific value:

values:              10   20   30   30   30   40   50
insertion points:   |   |    |    |    |    |    |    |
                    0   1    2    3    4    5    6    7
bisect_left(30) -------------^
bisect_right(30) ---------------------------^

As you can see, bisect_left() does in fact point JUST BEFORE the 30.

Note this is also how slicing works.  Here's an example:

    >>> from bisect import bisect_left, bisect_right
    >>> s = [10, 20, 30, 30, 30, 40, 50]
    >>> i = bisect_left(s, 30)
    >>> j = bisect_right(s, 30)
    >>> s[i : j]
    [30, 30, 30]

Conceptually, yes, but the function does return an index, and values are
stored at these indices. The index it returns holds the leftmost occurrence
of the target (should the target exist)
>>> bisect.bisect_left([1,2,2,3],2)
1
If we insert at this index, it will push the current value right, so
conceptually, sure, it can help to think of the insertion point as being
just before the leftmost target value.

But while bisect_right does in fact return value i that "points just beyond
the rightmost x already there" ("just beyond" gets interpreted as "the next
one", because only whole indices are used), making the statement "i points
just before the leftmost x already there" for the return value of
bisect_left definitely appears incorrect.

On Mon, May 24, 2021 at 6:30 PM Raymond Hettinger <report@bugs.python.org>
wrote:

>
> Raymond Hettinger <raymond.hettinger@gmail.com> added the comment:
>
> I there is a misunderstanding here.  The bisect functions never point *to*
> a value.  Instead, they are documented to return "insertion points".  Those
> always occur just before or after a specific value:
>
> values:              10   20   30   30   30   40   50
> insertion points:   |   |    |    |    |    |    |    |
>                     0   1    2    3    4    5    6    7
> bisect_left(30) -------------^
> bisect_right(30) ---------------------------^
>
> As you can see, bisect_left() does in fact point JUST BEFORE the 30.
>
> Note this is also how slicing works.  Here's an example:
>
>     >>> from bisect import bisect_left, bisect_right
>     >>> s = [10, 20, 30, 30, 30, 40, 50]
>     >>> i = bisect_left(s, 30)
>     >>> j = bisect_right(s, 30)
>     >>> s[i : j]
>     [30, 30, 30]
>
> ----------
>
> _______________________________________
> Python tracker <report@bugs.python.org>
> <https://bugs.python.org/issue44227>
> _______________________________________
>

> Conceptually, yes, but the function does return an index,

The function does not return an index.  It returns an integer that represents an insertion point.  The documentation is clear about this:

    Locate the insertion point for x in a to maintain sorted order.
    ...
    return value is suitable for use as the first
    parameter to list.insert()

Likewise, the documented and precise invariants are stated in terms of slice points:

   The returned insertion point i partitions the array ``a ``
   into two halves so that ``all(val < x for val in a[lo : i])``
   for the left side and ``all(val >= x for val in a[i : hi])``
   for the right side.


> and values are stored at these indices.

That isn't true:

    >>> bisect([], 5)
    0

There is no value at 0.

The bisect functions are all about insertion points and ranges.  They aren't expressed in terms of an index and value.  The underlying algorithm never checks for equality.  Instead, it only uses __lt__(), so it is never aware of having "found" a value at all.

For people with use cases expressed in terms of index and value, there is a separate section of the docs showing show how to bridge between what they want and what the module actually does:

    https://docs.python.org/3.10/library/bisect.html#searching-sorted-lists

New changeset b5cedd098043dc58ecf9c2f33774cd7646506a92 by Miss Islington (bot) in branch '3.10':
bpo-44227: Update bisect docstrings (GH-26548) (GH-26563)
https://github.com/python/cpython/commit/b5cedd098043dc58ecf9c2f33774cd7646506a92