Extension Doc bug

[Michael P. Reilly]

I just spent the morning trying to find a very obscure bug related to
the passing keyword arguments to a builtin method/function.

I have a method that I defined with METH_VARARGS|METH_KEYWORDS, and
found when I called the method with a single argument it worked fine,
but after calling it a second time I would get a SystemError exception
with the string "bad argument to internal function".

It turns out that if no keywords are given in the call, then the third
argument passed to the C function is NULL, not an empty PyDictObject.
This causes havok with PyArg_ParseTupleAndKeywords() and other
functions.  The exception is a side-effect of this havok (since my
function was returning Py_None, not NULL).

The workaround for users of PyArg_ParseTupleAndKeywords() is to check
the third argument first.

  static int
  my_func(PyObject *self, PyObject *args, PyObject *keywds)
    {
      if (keywds == NULL) {
        if (PyArg_ParseTuple(args, ...)) { ... }
      } else {
        if (PyArg_ParseTuple(args, keywds, ...)) { ... }
      }
      ...
    }

There should be a note in section 1.8 of _Extending and Embedding the
Python Interpreter_ stating that "keywds" might be passed NULL instead
of a dictionary.

Thanks,
  -Arcege