1.8 Parametry słownikowe dla funkcji rozszerzeń

Parametry arg oraz format są identyczne z analogicznymi parametrami funkcji PyArg_ParseTuple(). Parametr kwdict jest słownikiem słów kluczowych otrzymanych jako trzeci parametr z interpretera Pythona. Parametr kwlist jest listą napisów zakończoną znakiem NULLidentyfikującą parametry. Nazwy są dopasowywane z informacją o typie uzyskaną ze zmiennej format w kolejności od lewej do prawej. W przypadku powodzenia, funkcja PyArg_ParseTupleAndKeywords() zwraca wartość prawdziwą, w przeciwnym wypadku zwraca wartość fałszywą oraz wywołuje odpowiedni wyjątek.

Notka: Podczas wykorzystania argumentów kluczowych nie można używać zagnieżdżonych krotek! Jeśli funkcji zostaną przekazane parametry kluczowe, które nie zostaną umieszczone w kwlist, zostanie wywołany wyjątek TypeError.

Przedstawiamy przykładowy moduł wykorzystujący parametry kluczowe oparty na przykładzie autorstwa Geoffa Philbricka (philbrick@hks.com):

#include "Python.h"

static PyObject *
keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
{  
    int voltage;
    char *state = "a stiff";
    char *action = "voom";
    char *type = "Norwegian Blue";

    static char *kwlist[] = {"voltage", "state", "action", "type", NULL};

    if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
                                     &voltage, &state, &action, &type))
        return NULL; 
  
    printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
           action, voltage);
    printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);

    Py_INCREF(Py_None);

    return Py_None;
}

static PyMethodDef keywdarg_methods[] = {
    /* Rzutowanie funkcji jest niezbędne z powodu przyjmowania tylko
     * dwóch parametrów PyObject* przez PyCFunction, podczas, gdy
     * keywdarg_parrot() przyjmuje trzy.
    */
    {"parrot", (PyCFunction)keywdarg_parrot, METH_VARARGS | METH_KEYWORDS},
     "Wypisuje fragment świetnego skeczu na standardowym wyjściu."},
    {NULL, NULL, 0, NULL}   /* wartownik */
};

void
initkeywdarg()
{
  /* Utworzenie modułu i funkcji */
  Py_InitModule("keywdarg", keywdarg_methods);
}