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

1 files changed, 9 insertions, 0 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 1add30072f..03f0228476 100644
--- 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: