Merged revisions 59259-59274 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines

  Issue #1531: Read fileobj from the current offset, do not seek to
  the start.

  (will backport to 2.5)
........
  r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines

  Document PyEval_* functions from ceval.c.

  Credits to Michael Sloan from GHOP.
........
  r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines

  Add a few refcount data entries.
........
  r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines

  Add test suite for cmd module.

  Written by Michael Schneider for GHOP.
........
  r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines

  Add examples to the ElementTree documentation.
  Written by h4wk.cz for GHOP.
........
  r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add "Using Python on Windows" document, by Robert Lehmann.
  Written for GHOP.
........
  r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines

  Add example to mmap docs.
  Written for GHOP by Rafal Rawicki.
........
  r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines

  Convert bdb.rst line endings to Unix style.
........
  r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines

  Add more entries to the glossary.

  Written by Jeff Wheeler for GHOP.
........

1 files changed, 18 insertions, 5 deletions

diff --git a/Doc/extending/extending.rst b/Doc/extending/extending.rst
index 74d3f28..e9a3aaa 100644
--- a/Doc/extending/extending.rst
+++ b/Doc/extending/extending.rst
@@ -466,10 +466,10 @@ Later, when it is time to call the function, you call the C function
 :cfunc:`PyEval_CallObject`.  This function has two arguments, both pointers to
 arbitrary Python objects: the Python function, and the argument list.  The
 argument list must always be a tuple object, whose length is the number of
-arguments.  To call the Python function with no arguments, pass an empty tuple;
-to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
-returns a tuple when its format string consists of zero or more format codes
-between parentheses.  For example::
+arguments.  To call the Python function with no arguments, pass in NULL, or 
+an empty tuple; to call it with one argument, pass a singleton tuple.
+:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
+or more format codes between parentheses.  For example::
 
    int arg;
    PyObject *arglist;
@@ -527,9 +527,22 @@ event code, you might use the following code::
    Py_DECREF(result);
 
 Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check!  Also note that strictly spoken this code is not complete:
+the error check!  Also note that strictly speaking this code is not complete:
 :cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
 
+You may also call a function with keyword arguments by using 
+:cfunc:`PyEval_CallObjectWithKeywords`.  As in the above example, we use
+:cfunc:`Py_BuildValue` to construct the dictionary. ::
+
+   PyObject *dict;
+   ...
+   dict = Py_BuildValue("{s:i}", "name", val);
+   result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
+   Py_DECREF(dict);
+   if (result == NULL)
+       return NULL; /* Pass error back */
+   /* Here maybe use the result */
+   Py_DECREF(result);
 
 .. _parsetuple: