Lots of new text and example code on embedding Python in C, contributed

by Albert Hofkamp.  Some editing has been done for style and markup
consistency.

This also supplies an example of importing modules and calling a function
defined in the module, so this closes SF bug #440037 as well.

(The long example code was moved to a separate file so that it would
format properly.)

Doc/ext/run-func.c

@@ -0,0 +1,66 @@
+#include <stdio.h>
+#include <Python.h>
+
+int
+main(int argc, char *argv[])
+{
+    PyObject *pName, *pModule, *pDict, *pFunc;
+    PyObject *pArgs, *pValue;
+    int i, result;
+
+    if (argc < 3) {
+        fprintf(stderr,"Usage: call pythonfile funcname [args]\n");
+        return 1;
+    }
+
+    Py_Initialize();
+    pName = PyString_FromString(argv[1]);
+    /* Error checking of pName left out */
+
+    pModule = PyImport_Import(pName);
+    if (pModule != NULL) {
+        pDict = PyModule_GetDict(pModule);
+        /* pDict is a borrowed reference */
+
+        pFunc = PyDict_GetItemString(pDict, argv[2]);
+        /* pFun: Borrowed reference */
+
+        if (pFunc && PyCallable_Check(pFunc)) {
+            pArgs = PyTuple_New(argc - 3);
+            for (i = 0; i < argc - 3; ++i) {
+                pValue = PyInt_FromLong(atoi(argv[i + 3]));
+                if (!pValue) {
+                    fprintf(stderr, "Cannot convert argument\n");
+                    return 1;
+                }
+                /* pValue reference stolen here: */
+                PyTuple_SetItem(pArgs, i, pValue);
+            }
+            pValue = PyObject_CallObject(pFunc, pArgs);
+            if (pValue != NULL) {
+                printf("Result of call: %ld\n", PyInt_AsLong(pValue));
+                Py_DECREF(pValue);
+            }
+            else {
+                PyErr_Print();
+                fprintf(stderr,"Call failed\n");
+                return 1;
+            }
+            Py_DECREF(pArgs);
+            /* pDict and pFunc are borrowed and must not be Py_DECREF-ed */
+        }
+        else {
+            PyErr_Print();
+            fprintf(stderr, "Cannot find function \"%s\"\n", argv[2]);
+        }
+        Py_DECREF(pModule);
+    }
+    else {
+        PyErr_Print();
+        fprintf(stderr, "Failed to load \"%s\"\n", argv[1]);
+        return 1;
+    }
+    Py_DECREF(pName);
+    Py_Finalize();
+    return 0;
+}