[Python-checkins] r75611 - in python/trunk: Doc/library/codecs.rst Python/codecs.c
georg.brandl
python-checkins at python.org
Thu Oct 22 17:42:32 CEST 2009
Author: georg.brandl
Date: Thu Oct 22 17:42:32 2009
New Revision: 75611
Log:
#7035: improve docs of the various <method>_errors() functions, and give them docstrings.
Modified:
python/trunk/Doc/library/codecs.rst
python/trunk/Python/codecs.c
Modified: python/trunk/Doc/library/codecs.rst
==============================================================================
--- python/trunk/Doc/library/codecs.rst (original)
+++ python/trunk/Doc/library/codecs.rst Thu Oct 22 17:42:32 2009
@@ -54,7 +54,7 @@
*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 @@
*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 @@
.. 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:
Modified: python/trunk/Python/codecs.c
==============================================================================
--- python/trunk/Python/codecs.c (original)
+++ python/trunk/Python/codecs.c Thu Oct 22 17:42:32 2009
@@ -774,7 +774,9 @@
{
"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 @@
{
"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 @@
{
"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 @@
{
"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 @@
{
"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
More information about the Python-checkins
mailing list