Issue #17827: document codecs.encode and codecs.decode

- Merge from 3.3
- Added to What's New since these are more important in 3.x,
  as the bytes<->bytes and str<->str codecs don't fit the
  text model convenience methods in 3.x the way they did the
  basestring<->basestring methods in the 2.x text model
- Included under Library in Misc/NEWS for the same reason

3 files changed, 35 insertions, 0 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index b412038..b6d4f08 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -22,6 +22,25 @@ manages the codec and error handling lookup process.
 
 It defines the following functions:
 
+.. function:: encode(obj, encoding='utf-8', errors='strict')
+
+   Encodes *obj* using the codec registered for *encoding*.
+
+   *Errors* may be given to set the desired error handling scheme. The
+   default error handler is ``strict`` meaning that encoding errors raise
+   :exc:`ValueError` (or a more codec specific subclass, such as
+   :exc:`UnicodeEncodeError`). Refer to :ref:`codec-base-classes` for more
+   information on codec error handling.
+
+.. function:: decode(obj, encoding='utf-8', errors='strict')
+
+   Decodes *obj* using the codec registered for *encoding*.
+
+   *Errors* may be given to set the desired error handling scheme. The
+   default error handler is ``strict`` meaning that decoding errors raise
+   :exc:`ValueError` (or a more codec specific subclass, such as
+   :exc:`UnicodeDecodeError`). Refer to :ref:`codec-base-classes` for more
+   information on codec error handling.
 
 .. function:: register(search_function)
 
diff --git a/Doc/whatsnew/3.4.rst b/Doc/whatsnew/3.4.rst
index 4927b66..5e26630 100644
--- a/Doc/whatsnew/3.4.rst
+++ b/Doc/whatsnew/3.4.rst
@@ -197,6 +197,19 @@ The :meth:`~aifc.getparams` method now returns a namedtuple rather than a
 plain tuple.  (Contributed by Claudiu Popa in :issue:`17818`.)
 
 
+codecs
+------
+
+The :meth:`codecs.encode` and :meth:`codecs.decode` convenience functions are
+now properly documented. These functions have existed in the :mod:`codecs`
+module since ~2004, but were previously only discoverable through runtime
+introspection.
+
+Unlike the convenience methods on :class:`str`, :class:`bytes` and
+:class:`bytearray`, these convenience functions support arbitrary codecs,
+rather than being limited to Unicode text encodings.
+
+
 colorsys
 --------
 
diff --git a/Misc/NEWS b/Misc/NEWS
index ded3bb4..9975f5a 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -42,6 +42,9 @@ Core and Builtins
 Library
 -------
 
+- Issue #17827: Add the missing documentation for ``codecs.encode`` and
+  ``codecs.decode``.
+
 - Issue #19218: Rename collections.abc to _collections_abc in order to
   speed up interpreter start.