Add HPyList_Insert

docs/api-reference/function-index.rst

@@ -54,6 +54,7 @@ HPy Core API Function Index
 * :c:func:`HPyListBuilder_Set`
 * :c:func:`HPyList_Append`
 * :c:func:`HPyList_Check`
+* :c:func:`HPyList_Insert`
 * :c:func:`HPyList_New`
 * :c:func:`HPyLong_AsDouble`
 * :c:func:`HPyLong_AsInt32_t`

docs/porting-guide.rst

@@ -192,6 +192,7 @@ with the code for the :term:`CPython ABI` mode, so it is guaranteed to be correc
     `PyImport_ImportModule <https://docs.python.org/3/c-api/import.html#c.PyImport_ImportModule>`_                                     :c:func:`HPyImport_ImportModule`
     `PyList_Append <https://docs.python.org/3/c-api/list.html#c.PyList_Append>`_                                                       :c:func:`HPyList_Append`
     `PyList_Check <https://docs.python.org/3/c-api/list.html#c.PyList_Check>`_                                                         :c:func:`HPyList_Check`
+    `PyList_Insert <https://docs.python.org/3/c-api/list.html#c.PyList_Insert>`_                                                       :c:func:`HPyList_Insert`
     `PyList_New <https://docs.python.org/3/c-api/list.html#c.PyList_New>`_                                                             :c:func:`HPyList_New`
     `PyLong_AsDouble <https://docs.python.org/3/c-api/long.html#c.PyLong_AsDouble>`_                                                   :c:func:`HPyLong_AsDouble`
     `PyLong_AsLong <https://docs.python.org/3/c-api/long.html#c.PyLong_AsLong>`_                                                       :c:func:`HPyLong_AsLong`

docs/requirements.txt

@@ -1,8 +1,8 @@
 # Requirements for building the documentation
-Jinja2<3.1
-sphinx==3.3.1
-sphinx-rtd-theme==0.5.0
-sphinx-autobuild==0.7.1
-sphinx-c-autodoc==0.3.1
+Jinja2==3.1.3
+sphinx==5.0.2
+sphinx-rtd-theme==2.0.0
+sphinx-autobuild==2021.3.14
+sphinx-c-autodoc==1.3.0
 clang==11.0
 docutils==0.16  # docutils >= 0.17 fails to render bullet lists :/

hpy/tools/autogen/public_api.h

@@ -673,6 +673,30 @@ HPy HPyList_New(HPyContext *ctx, HPy_ssize_t len);
 HPy_ID(200)
 int HPyList_Append(HPyContext *ctx, HPy h_list, HPy h_item);
 
+/**
+ * Insert the item ``h_item`` into list ``h_list`` in front of index ``index``.
+ *
+ * :param ctx:
+ *     The execution context.
+ * :param h_list:
+ *     A Python list object (must not be ``HPy_NULL``). Otherwise, a
+ *     ``SystemError`` will be raised.
+ * :param index:
+ *     The index where the element should be inserted before. A negative index
+ *     is allowed and is then interpreted to be relative to the end of sequence.
+ *     E.g. ``index == -1`` is the last element.
+ *     If ``index < -n`` (where ``n`` is the length of the list), it will be
+ *     replaced by ``0``. If ``index > n``, it will be replaced by ``n``.
+ * :param h_item:
+ *    The item to insert (must not be ``HPy_NULL``).
+ *
+ * :returns:
+ *     Return ``0`` if successful; return ``-1`` and set an exception if
+ *     unsuccessful.
+ */
+HPy_ID(265)
+int HPyList_Insert(HPyContext *ctx, HPy h_list, HPy_ssize_t index, HPy h_item);
+
 /* dictobject.h */
 
 /**

test/test_hpylist.py

@@ -75,3 +75,38 @@ def test_ListBuilder(self):
             @INIT
         """)
         assert mod.f("xy") == ["xy", True, -42]
+
+    def test_Insert(self):
+        import pytest
+        mod = self.make_module("""
+            HPyDef_METH(f, "f", HPyFunc_VARARGS)
+            static HPy f_impl(HPyContext *ctx, HPy self, const HPy *args, size_t nargs)
+            {
+                HPy_ssize_t index;
+                if (nargs != 3) {
+                    HPyErr_SetString(ctx, ctx->h_ValueError, "expected exactly three arguments");
+                    return HPy_NULL;
+                }
+                index = HPyLong_AsSsize_t(ctx, args[1]);
+                if (index == -1 && HPyErr_Occurred(ctx)) {
+                    return HPy_NULL;
+                }
+                if (HPyList_Insert(ctx, args[0], index, args[2]) == -1)
+                    return HPy_NULL;
+                return HPy_Dup(ctx, args[0]);
+            }
+            @EXPORT(f)
+            @INIT
+        """)
+        l = []
+        assert mod.f(l, 0, 0) == [0]
+        l = []
+        assert mod.f(l, -1, 0) == [0]
+        l = [1, 2, 4]
+        assert mod.f(l, 0, 0) == [0, 1, 2, 4]
+        assert mod.f(l, -1, 3) == [0, 1, 2, 3, 4]
+        assert mod.f(l, -3, 1.5) == [0, 1, 1.5, 2, 3, 4]
+        assert mod.f(l, 1000, 5) == [0, 1, 1.5, 2, 3, 4, 5]
+        assert mod.f(l, -1000, -1) == [-1, 0, 1, 1.5, 2, 3, 4, 5]
+        with pytest.raises(SystemError):
+            mod.f(None, 0, 0)