← Back to branch summary

~ubuntu-branches/ubuntu/lucid/python2.6/lucid

« back to all changes in this revision

Viewing changes to Doc/extending/extending.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-04-08 02:29:05 UTC
  • mto: (10.1.3 experimental)
  • mto: This revision was merged to the branch mainline in revision 23.
  • Revision ID: james.westby@ubuntu.com-20090408022905-xa5zbe8821m2o77o
Tags: upstream-2.6.2~rc1
Import upstream version 2.6.2~rc1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/extending/extending.rst
465
465
(but note that *temp* will not be  *NULL* in this context).  More info on them
466
466
in section :ref:`refcounts`.
467
467
 
468
 
.. index:: single: PyEval_CallObject()
 
468
.. index:: single: PyObject_CallObject()
469
469
 
470
470
Later, when it is time to call the function, you call the C function
471
 
:cfunc:`PyEval_CallObject`.  This function has two arguments, both pointers to
 
471
:cfunc:`PyObject_CallObject`.  This function has two arguments, both pointers to
472
472
arbitrary Python objects: the Python function, and the argument list.  The
473
473
argument list must always be a tuple object, whose length is the number of
474
 
arguments.  To call the Python function with no arguments, pass in NULL, or 
 
474
arguments.  To call the Python function with no arguments, pass in NULL, or
475
475
an empty tuple; to call it with one argument, pass a singleton tuple.
476
476
:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
477
477
or more format codes between parentheses.  For example::
484
484
   ...
485
485
   /* Time to call the callback */
486
486
   arglist = Py_BuildValue("(i)", arg);
487
 
   result = PyEval_CallObject(my_callback, arglist);
 
487
   result = PyObject_CallObject(my_callback, arglist);
488
488
   Py_DECREF(arglist);
489
489
 
490
 
:cfunc:`PyEval_CallObject` returns a Python object pointer: this is the return
491
 
value of the Python function.  :cfunc:`PyEval_CallObject` is
 
490
:cfunc:`PyObject_CallObject` returns a Python object pointer: this is the return
 
491
value of the Python function.  :cfunc:`PyObject_CallObject` is
492
492
"reference-count-neutral" with respect to its arguments.  In the example a new
493
493
tuple was created to serve as the argument list, which is :cfunc:`Py_DECREF`\
494
494
-ed immediately after the call.
495
495
 
496
 
The return value of :cfunc:`PyEval_CallObject` is "new": either it is a brand
 
496
The return value of :cfunc:`PyObject_CallObject` is "new": either it is a brand
497
497
new object, or it is an existing object whose reference count has been
498
498
incremented.  So, unless you want to save it in a global variable, you should
499
499
somehow :cfunc:`Py_DECREF` the result, even (especially!) if you are not
501
501
 
502
502
Before you do this, however, it is important to check that the return value
503
503
isn't *NULL*.  If it is, the Python function terminated by raising an exception.
504
 
If the C code that called :cfunc:`PyEval_CallObject` is called from Python, it
 
504
If the C code that called :cfunc:`PyObject_CallObject` is called from Python, it
505
505
should now return an error indication to its Python caller, so the interpreter
506
506
can print a stack trace, or the calling Python code can handle the exception.
507
507
If this is not possible or desirable, the exception should be cleared by calling
510
510
   if (result == NULL)
511
511
       return NULL; /* Pass error back */
512
512
   ...use result...
513
 
   Py_DECREF(result); 
 
513
   Py_DECREF(result);
514
514
 
515
515
Depending on the desired interface to the Python callback function, you may also
516
 
have to provide an argument list to :cfunc:`PyEval_CallObject`.  In some cases
 
516
have to provide an argument list to :cfunc:`PyObject_CallObject`.  In some cases
517
517
the argument list is also provided by the Python program, through the same
518
518
interface that specified the callback function.  It can then be saved and used
519
519
in the same manner as the function object.  In other cases, you may have to
524
524
   PyObject *arglist;
525
525
   ...
526
526
   arglist = Py_BuildValue("(l)", eventcode);
527
 
   result = PyEval_CallObject(my_callback, arglist);
 
527
   result = PyObject_CallObject(my_callback, arglist);
528
528
   Py_DECREF(arglist);
529
529
   if (result == NULL)
530
530
       return NULL; /* Pass error back */
535
535
the error check!  Also note that strictly speaking this code is not complete:
536
536
:cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
537
537
 
538
 
You may also call a function with keyword arguments by using 
539
 
:cfunc:`PyEval_CallObjectWithKeywords`.  As in the above example, we use
540
 
:cfunc:`Py_BuildValue` to construct the dictionary. ::
 
538
You may also call a function with keyword arguments by using
 
539
:cfunc:`PyObject_Call`, which supports arguments and keyword arguments.  As in
 
540
the above example, we use :cfunc:`Py_BuildValue` to construct the dictionary. ::
541
541
 
542
542
   PyObject *dict;
543
543
   ...
544
544
   dict = Py_BuildValue("{s:i}", "name", val);
545
 
   result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
 
545
   result = PyObject_Call(my_callback, NULL, dict);
546
546
   Py_DECREF(dict);
547
547
   if (result == NULL)
548
548
       return NULL; /* Pass error back */
549
549
   /* Here maybe use the result */
550
550
   Py_DECREF(result);
551
551
 
 
552
 
552
553
.. _parsetuple:
553
554
 
554
555
Extracting Parameters in Extension Functions
671
672
 
672
673
   static PyObject *
673
674
   keywdarg_parrot(PyObject *self, PyObject *args, PyObject *keywds)
674
 
   {  
 
675
   {
675
676
       int voltage;
676
677
       char *state = "a stiff";
677
678
       char *action = "voom";
679
680
 
680
681
       static char *kwlist[] = {"voltage", "state", "action", "type", NULL};
681
682
 
682
 
       if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist, 
 
683
       if (!PyArg_ParseTupleAndKeywords(args, keywds, "i|sss", kwlist,
683
684
                                        &voltage, &state, &action, &type))
684
 
           return NULL; 
 
685
           return NULL;
685
686
 
686
 
       printf("-- This parrot wouldn't %s if you put %i Volts through it.\n", 
 
687
       printf("-- This parrot wouldn't %s if you put %i Volts through it.\n",
687
688
              action, voltage);
688
689
       printf("-- Lovely plumage, the %s -- It's %s!\n", type, state);
689
690
 
865
866
The advantage of borrowing over owning a reference is that you don't need to
866
867
take care of disposing of the reference on all possible paths through the code
867
868
--- in other words, with a borrowed reference you don't run the risk of leaking
868
 
when a premature exit is taken.  The disadvantage of borrowing over leaking is
 
869
when a premature exit is taken.  The disadvantage of borrowing over owning is
869
870
that there are some subtle situations where in seemingly correct code a borrowed
870
871
reference can be used after the owner from which it was borrowed has in fact
871
872
disposed of it.