Soft deprecations

Author: vstinner

peps/pep-0782.rst

@@ -17,9 +17,11 @@ Abstract
 
 Add a new ``PyBytesWriter`` C API to create ``bytes`` objects.
 
-It replaces the ``PyBytes_FromStringAndSize(NULL, size)`` and
-``_PyBytes_Resize()`` APIs which treat an immutable ``bytes`` object as
-a mutable object.
+Soft deprecate ``PyBytes_FromStringAndSize(NULL, size)`` and
+``_PyBytes_Resize()`` APIs. These APIs treat an immutable ``bytes``
+object as a mutable object. They remain available and maintained, don't
+emit deprecation warning, but are no longer recommended when writing new
+code.
 
 
 Rationale
@@ -188,6 +190,18 @@ Thread safety
 The API is not thread safe: a writer should only be used by a single
 thread at the same time.
 
+Soft deprecations
+-----------------
+
+Soft deprecate ``PyBytes_FromStringAndSize(NULL, size)`` and
+``_PyBytes_Resize()`` APIs. These APIs treat an immutable ``bytes``
+object as a mutable object. They remain available and maintained, don't
+emit deprecation warning, but are no longer recommended when writing new
+code.
+
+``PyBytes_FromStringAndSize(str, size)`` is not soft deprecated. Only
+calls with ``NULL`` *str* are soft deprecated.
+
 
 Examples
 ========