From e4463486a1e8bd1cc67ac176d0b2189569a358e9 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 4 May 2023 15:25:32 +0100 Subject: [PATCH 1/4] Use 'refspecific' cross reference type for the bisect function --- Doc/library/bisect.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index e3c8c801904b61..f4dd6e7722cef6 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -140,7 +140,7 @@ thoughts in mind: Searching Sorted Lists ---------------------- -The above :func:`bisect` functions are useful for finding insertion points but +The above :func:`.bisect` functions are useful for finding insertion points but can be tricky or awkward to use for common searching tasks. The following five functions show how to transform them into the standard lookups for sorted lists:: @@ -186,8 +186,8 @@ Examples .. _bisect-example: -The :func:`bisect` function can be useful for numeric table lookups. This -example uses :func:`bisect` to look up a letter grade for an exam score (say) +The :func:`.bisect` function can be useful for numeric table lookups. This +example uses :func:`.bisect` to look up a letter grade for an exam score (say) based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is a 'B', and so on:: @@ -198,7 +198,7 @@ a 'B', and so on:: >>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]] ['F', 'A', 'C', 'C', 'B', 'A', 'A'] -The :func:`bisect` and :func:`insort` functions also work with lists of +The :func:`.bisect` and :func:`insort` functions also work with lists of tuples. The *key* argument can serve to extract the field used for ordering records in a table:: From e3ff8e9b11e469885dc165712fd7a2a2be0407df Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 4 May 2023 18:47:47 +0100 Subject: [PATCH 2/4] Alter target --- Doc/library/bisect.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index f4dd6e7722cef6..f969d0f6814d3a 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -140,10 +140,10 @@ thoughts in mind: Searching Sorted Lists ---------------------- -The above :func:`.bisect` functions are useful for finding insertion points but -can be tricky or awkward to use for common searching tasks. The following five -functions show how to transform them into the standard lookups for sorted -lists:: +The above :py:mod:`bisect functions ` are useful for finding insertion +points but can be tricky or awkward to use for common searching tasks. The +following five functions show how to transform them into the standard lookups +for sorted lists:: def index(a, x): 'Locate the leftmost value exactly equal to x' From 7fd3523f462aa99e0555f0b51f00a59033b9df3d Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 4 May 2023 18:51:51 +0100 Subject: [PATCH 3/4] Use fully-qualified version of the py:func role --- Doc/library/bisect.rst | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index f969d0f6814d3a..f11a8c4ff3395b 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -55,8 +55,8 @@ The following functions are provided: .. function:: bisect_right(a, x, lo=0, hi=len(a), *, key=None) bisect(a, x, lo=0, hi=len(a), *, key=None) - Similar to :func:`bisect_left`, but returns an insertion point which comes - after (to the right of) any existing entries of *x* in *a*. + Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point + which comes after (to the right of) any existing entries of *x* in *a*. The returned insertion point *ip* partitions the array *a* into two slices such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left slice and @@ -70,7 +70,8 @@ The following functions are provided: Insert *x* in *a* in sorted order. - This function first runs :func:`bisect_left` to locate an insertion point. + This function first runs :py:func:`~bisect.bisect_left` to locate an + insertion point. Next, it runs the :meth:`insert` method on *a* to insert *x* at the appropriate position to maintain sort order. @@ -87,10 +88,11 @@ The following functions are provided: .. function:: insort_right(a, x, lo=0, hi=len(a), *, key=None) insort(a, x, lo=0, hi=len(a), *, key=None) - Similar to :func:`insort_left`, but inserting *x* in *a* after any existing - entries of *x*. + Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* afte + any existing entries of *x*. - This function first runs :func:`bisect_right` to locate an insertion point. + This function first runs :py:func:`~bisect.bisect_right` to locate an + insertion point. Next, it runs the :meth:`insert` method on *a* to insert *x* at the appropriate position to maintain sort order. @@ -120,7 +122,7 @@ thoughts in mind: they are used. Consequently, if the search functions are used in a loop, the key function may be called again and again on the same array elements. If the key function isn't fast, consider wrapping it with - :func:`functools.cache` to avoid duplicate computations. Alternatively, + :py:func:`functools.cache` to avoid duplicate computations. Alternatively, consider searching an array of precomputed keys to locate the insertion point (as shown in the examples section below). @@ -186,10 +188,10 @@ Examples .. _bisect-example: -The :func:`.bisect` function can be useful for numeric table lookups. This -example uses :func:`.bisect` to look up a letter grade for an exam score (say) -based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is -a 'B', and so on:: +The :py:func:`~bisect.bisect` function can be useful for numeric table lookups. +This example uses :py:func:`~bisect.bisect` to look up a letter grade for +an exam score (say) based on a set of ordered numeric breakpoints: +90 and up is an 'A', 80 to 89 is a 'B', and so on:: >>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'): ... i = bisect(breakpoints, score) @@ -198,9 +200,9 @@ a 'B', and so on:: >>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]] ['F', 'A', 'C', 'C', 'B', 'A', 'A'] -The :func:`.bisect` and :func:`insort` functions also work with lists of -tuples. The *key* argument can serve to extract the field used for ordering -records in a table:: +The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also work +with lists of tuples. The *key* argument can serve to extract the field used +for ordering records in a table:: >>> from collections import namedtuple >>> from operator import attrgetter From 93027f4c0de4c98d39edd0013d16891cf5447500 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Mon, 8 May 2023 16:23:19 +0100 Subject: [PATCH 4/4] Minimise ``git diff`` --- Doc/library/bisect.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/Doc/library/bisect.rst b/Doc/library/bisect.rst index f11a8c4ff3395b..8022c596f0af97 100644 --- a/Doc/library/bisect.rst +++ b/Doc/library/bisect.rst @@ -24,6 +24,8 @@ method to determine whether a value has been found. Instead, the functions only call the :meth:`__lt__` method and will return an insertion point between values in an array. +.. _bisect functions: + The following functions are provided: @@ -55,8 +57,8 @@ The following functions are provided: .. function:: bisect_right(a, x, lo=0, hi=len(a), *, key=None) bisect(a, x, lo=0, hi=len(a), *, key=None) - Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point - which comes after (to the right of) any existing entries of *x* in *a*. + Similar to :py:func:`~bisect.bisect_left`, but returns an insertion point which comes + after (to the right of) any existing entries of *x* in *a*. The returned insertion point *ip* partitions the array *a* into two slices such that ``all(elem <= x for elem in a[lo : ip])`` is true for the left slice and @@ -70,8 +72,7 @@ The following functions are provided: Insert *x* in *a* in sorted order. - This function first runs :py:func:`~bisect.bisect_left` to locate an - insertion point. + This function first runs :py:func:`~bisect.bisect_left` to locate an insertion point. Next, it runs the :meth:`insert` method on *a* to insert *x* at the appropriate position to maintain sort order. @@ -88,11 +89,10 @@ The following functions are provided: .. function:: insort_right(a, x, lo=0, hi=len(a), *, key=None) insort(a, x, lo=0, hi=len(a), *, key=None) - Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* afte - any existing entries of *x*. + Similar to :py:func:`~bisect.insort_left`, but inserting *x* in *a* after any existing + entries of *x*. - This function first runs :py:func:`~bisect.bisect_right` to locate an - insertion point. + This function first runs :py:func:`~bisect.bisect_right` to locate an insertion point. Next, it runs the :meth:`insert` method on *a* to insert *x* at the appropriate position to maintain sort order. @@ -142,10 +142,10 @@ thoughts in mind: Searching Sorted Lists ---------------------- -The above :py:mod:`bisect functions ` are useful for finding insertion -points but can be tricky or awkward to use for common searching tasks. The -following five functions show how to transform them into the standard lookups -for sorted lists:: +The above `bisect functions`_ are useful for finding insertion points but +can be tricky or awkward to use for common searching tasks. The following five +functions show how to transform them into the standard lookups for sorted +lists:: def index(a, x): 'Locate the leftmost value exactly equal to x' @@ -188,10 +188,10 @@ Examples .. _bisect-example: -The :py:func:`~bisect.bisect` function can be useful for numeric table lookups. -This example uses :py:func:`~bisect.bisect` to look up a letter grade for -an exam score (say) based on a set of ordered numeric breakpoints: -90 and up is an 'A', 80 to 89 is a 'B', and so on:: +The :py:func:`~bisect.bisect` function can be useful for numeric table lookups. This +example uses :py:func:`~bisect.bisect` to look up a letter grade for an exam score (say) +based on a set of ordered numeric breakpoints: 90 and up is an 'A', 80 to 89 is +a 'B', and so on:: >>> def grade(score, breakpoints=[60, 70, 80, 90], grades='FDCBA'): ... i = bisect(breakpoints, score) @@ -200,9 +200,9 @@ an exam score (say) based on a set of ordered numeric breakpoints: >>> [grade(score) for score in [33, 99, 77, 70, 89, 90, 100]] ['F', 'A', 'C', 'C', 'B', 'A', 'A'] -The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also work -with lists of tuples. The *key* argument can serve to extract the field used -for ordering records in a table:: +The :py:func:`~bisect.bisect` and :py:func:`~bisect.insort` functions also work with +lists of tuples. The *key* argument can serve to extract the field used for ordering +records in a table:: >>> from collections import namedtuple >>> from operator import attrgetter