bpo-27867: Add a porting guide for PySlice_GetIndicesEx(). (#1973)

2 files changed, 30 insertions, 1 deletions

diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst
index f8395ec..8ad9a29 100644
--- a/Doc/c-api/slice.rst
+++ b/Doc/c-api/slice.rst
@@ -53,6 +53,22 @@ Slice Objects
 
    Returns ``0`` on success and ``-1`` on error with exception set.
 
+   .. note::
+      This function is considered not safe for resizable sequences.
+      Its invocation should be replaced by a combination of
+      :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices` where ::
+
+         if (PySlice_GetIndicesEx(slice, length, &start, &stop, &step, &slicelength) < 0) {
+             // return error
+         }
+
+      is replaced by ::
+
+         if (PySlice_Unpack(slice, &start, &stop, &step) < 0) {
+             // return error
+         }
+         slicelength = PySlice_AdjustIndices(length, &start, &stop, step);
+
    .. versionchanged:: 3.2
       The parameter type for the *slice* parameter was ``PySliceObject*``
       before.
@@ -61,7 +77,7 @@ Slice Objects
       If ``Py_LIMITED_API`` is not set or set to the value between ``0x03050400``
       and ``0x03060000`` (not including) or ``0x03060100`` or higher
       :c:func:`!PySlice_GetIndicesEx` is implemented as a macro using
-      :c:func:`PySlice_Unpack` and :c:func:`PySlice_AdjustIndices`.
+      :c:func:`!PySlice_Unpack` and :c:func:`!PySlice_AdjustIndices`.
       Arguments *start*, *stop* and *step* are evaluated more than once.
 
    .. deprecated:: 3.6.1
diff --git a/Doc/whatsnew/3.7.rst b/Doc/whatsnew/3.7.rst
index 24a1dc4..a0c20a0 100644
--- a/Doc/whatsnew/3.7.rst
+++ b/Doc/whatsnew/3.7.rst
@@ -581,6 +581,19 @@ Changes in the Python API
   in the output. (Contributed by Utkarsh Upadhyay in :issue:`30302`.)
 
 
+Changes in the C API
+--------------------
+
+* The function :c:func:`PySlice_GetIndicesEx` is considered not safe for
+  resizable sequences.  If the slice indices are not instances of :class:`int`,
+  but objects that implement the :meth:`!__index__` method, the sequence can be
+  resized after passing its length to :c:func:`!PySlice_GetIndicesEx`.  This
+  can lead to returning indices out of the length of the sequence.  For
+  avoiding possible problems use new functions :c:func:`PySlice_Unpack` and
+  :c:func:`PySlice_AdjustIndices`.
+  (Contributed by Serhiy Storchaka in :issue:`27867`.)
+
+
 CPython bytecode changes
 ------------------------