Issue #23231: Document codecs.iterencode(), iterdecode() shortcomings

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 1add30072f45816d69e12a68df18efd0a18f3e75..03f0228476913a8c4c090713a936d35e941d72f7 100644 (file)
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -224,6 +224,10 @@ wider range of codecs when working with binary files:
    The *errors* argument (as well as any
    other keyword argument) is passed through to the incremental encoder.
 
+   This function requires that the codec accept text :class:`str` objects
+   to encode. Therefore it does not support bytes-to-bytes encoders such as
+   ``base64_codec``.
+
 
 .. function:: iterdecode(iterator, encoding, errors='strict', **kwargs)
 
@@ -232,6 +236,11 @@ wider range of codecs when working with binary files:
    The *errors* argument (as well as any
    other keyword argument) is passed through to the incremental decoder.
 
+   This function requires that the codec accept :class:`bytes` objects
+   to decode. Therefore it does not support text-to-text encoders such as
+   ``rot_13``, although ``rot_13`` may be used equivalently with
+   :func:`iterencode`.
+
 
 The module also provides the following constants which are useful for reading
 and writing to platform dependent files: