#7035: improve docs of the various <method>_errors() functions, and give them docstrings.

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index 072b19c16e9a2fa4019394df01943e6a403ce14a..e842bf8bf6605c02c67c215b2694fe6e9e85265a 100644 (file)
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -54,7 +54,7 @@ It defines the following functions:
    *incrementalencoder* and *incrementaldecoder*: These have to be factory
    functions providing the following interface:
 
-   ``factory(errors='strict')``
+      ``factory(errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`IncrementalEncoder` and :class:`IncrementalDecoder`,
@@ -63,20 +63,24 @@ It defines the following functions:
    *streamreader* and *streamwriter*: These have to be factory functions providing
    the following interface:
 
-   ``factory(stream, errors='strict')``
+      ``factory(stream, errors='strict')``
 
    The factory functions must return objects providing the interfaces defined by
    the base classes :class:`StreamWriter` and :class:`StreamReader`, respectively.
    Stream codecs can maintain state.
 
-   Possible values for errors are ``'strict'`` (raise an exception in case of an
-   encoding error), ``'replace'`` (replace malformed data with a suitable
-   replacement marker, such as ``'?'``), ``'ignore'`` (ignore malformed data and
-   continue without further notice), ``'xmlcharrefreplace'`` (replace with the
-   appropriate XML character reference (for encoding only)) and
-   ``'backslashreplace'`` (replace with backslashed escape sequences (for encoding
-   only)) as well as any other error handling name defined via
-   :func:`register_error`.
+   Possible values for errors are
+
+   * ``'strict'``: raise an exception in case of an encoding error
+   * ``'replace'``: replace malformed data with a suitable replacement marker,
+     such as ``'?'`` or ``'\ufffd'``
+   * ``'ignore'``: ignore malformed data and continue without further notice
+   * ``'xmlcharrefreplace'``: replace with the appropriate XML character
+     reference (for encoding only)
+   * ``'backslashreplace'``: replace with backslashed escape sequences (for
+     encoding only
+
+   as well as any other error handling name defined via :func:`register_error`.
 
    In case a search function cannot find a given encoding, it should return
    ``None``.
@@ -177,27 +181,33 @@ functions which use :func:`lookup` for the codec lookup:
 
 .. function:: strict_errors(exception)
 
-   Implements the ``strict`` error handling.
+   Implements the ``strict`` error handling: each encoding or decoding error
+   raises a :exc:`UnicodeError`.
 
 
 .. function:: replace_errors(exception)
 
-   Implements the ``replace`` error handling.
+   Implements the ``replace`` error handling: malformed data is replaced with a
+   suitable replacement character such as ``'?'`` in bytestrings and
+   ``'\ufffd'`` in Unicode strings.
 
 
 .. function:: ignore_errors(exception)
 
-   Implements the ``ignore`` error handling.
+   Implements the ``ignore`` error handling: malformed data is ignored and
+   encoding or decoding is continued without further notice.
 
 
 .. function:: xmlcharrefreplace_errors(exception)
 
-   Implements the ``xmlcharrefreplace`` error handling.
+   Implements the ``xmlcharrefreplace`` error handling (for encoding only): the
+   unencodable character is replaced by an appropriate XML character reference.
 
 
 .. function:: backslashreplace_errors(exception)
 
-   Implements the ``backslashreplace`` error handling.
+   Implements the ``backslashreplace`` error handling (for encoding only): the
+   unencodable character is replaced by a backslashed escape sequence.
 
 To simplify working with encoded files or stream, the module also defines these
 utility functions:

diff --git a/Python/codecs.c b/Python/codecs.c
index 4b0f4cb0d04f91771d4ee617f2f0a4e380321fe2..3849cf9a8c1c7ca3d93628543f677e5a03bbd5b2 100644 (file)
--- a/Python/codecs.c
+++ b/Python/codecs.c
@@ -774,7 +774,9 @@ static int _PyCodecRegistry_Init(void)
            {
                "strict_errors",
                strict_errors,
-               METH_O
+               METH_O,
+               PyDoc_STR("Implements the 'strict' error handling, which "
+                         "raises a UnicodeError on coding errors.")
            }
        },
 #ifdef Py_USING_UNICODE
@@ -783,7 +785,9 @@ static int _PyCodecRegistry_Init(void)
            {
                "ignore_errors",
                ignore_errors,
-               METH_O
+               METH_O,
+               PyDoc_STR("Implements the 'ignore' error handling, which "
+                         "ignores malformed data and continues.")
            }
        },
        {
@@ -791,7 +795,9 @@ static int _PyCodecRegistry_Init(void)
            {
                "replace_errors",
                replace_errors,
-               METH_O
+               METH_O,
+               PyDoc_STR("Implements the 'replace' error handling, which "
+                         "replaces malformed data with a replacement marker.")
            }
        },
        {
@@ -799,7 +805,10 @@ static int _PyCodecRegistry_Init(void)
            {
                "xmlcharrefreplace_errors",
                xmlcharrefreplace_errors,
-               METH_O
+               METH_O,
+               PyDoc_STR("Implements the 'xmlcharrefreplace' error handling, "
+                         "which replaces an unencodable character with the "
+                         "appropriate XML character reference.")
            }
        },
        {
@@ -807,7 +816,10 @@ static int _PyCodecRegistry_Init(void)
            {
                "backslashreplace_errors",
                backslashreplace_errors,
-               METH_O
+               METH_O,
+               PyDoc_STR("Implements the 'backslashreplace' error handling, "
+                         "which replaces an unencodable character with a "
+                         "backslashed escape sequence.")
            }
        }
 #endif