summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorGeorg Brandl <georg@python.org>2010-11-23 07:54:19 (GMT)
committerGeorg Brandl <georg@python.org>2010-11-23 07:54:19 (GMT)
commit5a9326502d3e728158116940212eb08198f53ee8 (patch)
tree9941f4eaa5b76665dba43e5de2605f2254ae8014 /Doc
parent5e438570cb8d7b64d71f1cb356df12edfec09dfe (diff)
downloadcpython-5a9326502d3e728158116940212eb08198f53ee8.zip
cpython-5a9326502d3e728158116940212eb08198f53ee8.tar.gz
cpython-5a9326502d3e728158116940212eb08198f53ee8.tar.bz2
#10468: document Unicode exception creation and access functions.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/c-api/codec.rst6
-rw-r--r--Doc/c-api/exceptions.rst77
2 files changed, 79 insertions, 4 deletions
diff --git a/Doc/c-api/codec.rst b/Doc/c-api/codec.rst
index 31a6bde..8207ae0 100644
--- a/Doc/c-api/codec.rst
+++ b/Doc/c-api/codec.rst
@@ -80,15 +80,13 @@ Registry API for Unicode encoding error handlers
The callback gets a single argument, an instance of
:exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
:exc:`UnicodeTranslateError` that holds information about the problematic
- sequence of characters or bytes and their offset in the original string. The
+ sequence of characters or bytes and their offset in the original string (see
+ :ref:`unicodeexceptions` for functions to extract this information). The
callback must either raise the given exception, or return a two-item tuple
containing the replacement for the problematic sequence, and an integer
giving the offset in the original string at which encoding/decoding should be
resumed.
- .. XXX once they are documented, link to PyUnicode*Error access functions
- to show how to get at the exception properties
-
Return ``0`` on success, ``-1`` on error.
.. c:function:: PyObject* PyCodec_LookupError(const char *name)
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index 0094af3..fdd24da 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -496,6 +496,83 @@ Exception Objects
This steals a reference to *ctx*.
+.. _unicodeexceptions:
+
+Unicode Exception Objects
+=========================
+
+The following functions are used to create and modify Unicode exceptions from C.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
+ *object*, *length*, *start*, *end* and *reason*.
+
+.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
+ *object*, *length*, *start*, *end* and *reason*.
+
+.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
+
+ Create a :class:`UnicodeTranslateError` object with the attributes *object*,
+ *length*, *start*, *end* and *reason*.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)
+
+ Return the *encoding* attribute of the given exception object.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc)
+ PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc)
+
+ Return the *object* attribute of the given exception object.
+
+.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+ int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)
+ int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)
+
+ Get the *start* attribute of the given exception object and place it into
+ *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on
+ failure.
+
+.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)
+ int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)
+ int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)
+
+ Set the *start* attribute of the given exception object to *start*. Return
+ ``0`` on success, ``-1`` on failure.
+
+.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+ int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)
+ int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)
+
+ Get the *end* attribute of the given exception object and place it into
+ *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on
+ failure.
+
+.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+ int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)
+ int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)
+
+ Set the *end* attribute of the given exception object to *end*. Return ``0``
+ on success, ``-1`` on failure.
+
+.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc)
+ PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc)
+ PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc)
+
+ Return the *reason* attribute of the given exception object.
+
+.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)
+ int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)
+ int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)
+
+ Set the *reason* attribute of the given exception object to *reason*. Return
+ ``0`` on success, ``-1`` on failure.
+
+
Recursion Control
=================