#9037: add example how to raise custom exceptions from C code.

diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index d5f55c7b0c9e97cd1f54850ab9ee68775b2166c3..567fcf80a3c5138152343ab76d9b88d63302611c 100644 (file)
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -226,9 +226,28 @@ needed to ensure that it will not be discarded, causing :cdata:`SpamError` to
 become a dangling pointer. Should it become a dangling pointer, C code which
 raises the exception could cause a core dump or other unintended side effects.
 
-We discuss the use of PyMODINIT_FUNC as a function return type later in this
+We discuss the use of ``PyMODINIT_FUNC`` as a function return type later in this
 sample.
 
+The :exc:`spam.error` exception can be raised in your extension module using a
+call to :cfunc:`PyErr_SetString` as shown below::
+
+   static PyObject *
+   spam_system(PyObject *self, PyObject *args)
+   {
+       const char *command;
+       int sts;
+
+       if (!PyArg_ParseTuple(args, "s", &command))
+           return NULL;
+       sts = system(command);
+       if (sts < 0) {
+           PyErr_SetString(SpamError, "System command failed");
+           return NULL;
+       }
+       return PyLong_FromLong(sts);
+   }
+
 
 .. _backtoexample: