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

1 files changed, 17 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