gh-121645: Add PyBytes_Join() function (#121646)

* Replace _PyBytes_Join() with PyBytes_Join().
* Keep _PyBytes_Join() as an alias to PyBytes_Join().

2 files changed, 23 insertions, 0 deletions

diff --git a/Doc/c-api/bytes.rst b/Doc/c-api/bytes.rst
index bca78a9..3d0501c 100644
--- a/Doc/c-api/bytes.rst
+++ b/Doc/c-api/bytes.rst
@@ -189,6 +189,24 @@ called with a non-bytes parameter.
    to *newpart* (i.e. decrements its reference count).
 
 
+.. c:function:: PyObject* PyBytes_Join(PyObject *sep, PyObject *iterable)
+
+   Similar to ``sep.join(iterable)`` in Python.
+
+   *sep* must be Python :class:`bytes` object.
+   (Note that :c:func:`PyUnicode_Join` accepts ``NULL`` separator and treats
+   it as a space, whereas :c:func:`PyBytes_Join` doesn't accept ``NULL``
+   separator.)
+
+   *iterable* must be an iterable object yielding objects that implement the
+   :ref:`buffer protocol <bufferobjects>`.
+
+   On success, return a new :class:`bytes` object.
+   On error, set an exception and return ``NULL``.
+
+   .. versionadded: 3.14
+
+
 .. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
 
    Resize a bytes object. *newsize* will be the new length of the bytes object.
diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index 44b373a..975af42 100644
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -485,6 +485,11 @@ New Features
 
   (Contributed by Victor Stinner in :gh:`120389`.)
 
+* Add :c:func:`PyBytes_Join(sep, iterable) <PyBytes_Join>` function,
+  similar to ``sep.join(iterable)`` in Python.
+  (Contributed by Victor Stinner in :gh:`121645`.)
+
+
 Porting to Python 3.14
 ----------------------