PyObject* Py_InitModule3(char*


name


,PyMethodDef*


methods


,char*


doc


)

name is the C string name of the module you are initializing (e.g., " name "). methods is an array of PyMethodDef structures, covered next in this chapter. doc is the C string that becomes the docstring of the module. Py_InitModule3 returns a PyObject* that is a borrowed reference to the new module object, as covered in Section 24.1.5 later in this chapter. In practice, this means that you can ignore the return value if you need to perform no more initialization operations on this module. Otherwise , assign the return value to a C variable of type PyObject* and continue initialization.

Py_InitModule3 initializes the module object to contain the functions described in table methods . Further initialization, if any, may add other module attributes, and is generally best performed with calls to the following convenience functions.

int PyModule_AddIntConstant(PyObject*


module


,char*


name


,int


value


)

Adds to module module an attribute named name with integer value value .

int PyModule_AddObject(PyObject*


module


,char*


name


,PyObject*


value


)

Adds to module module an attribute named name with value value and steals a reference to value, as covered in Section 24.1.5.

int PyModule_AddStringConstant(PyObject*


module


,char*


name


,char*


value


)

Adds to module module an attribute named name with string value value .

Some module initialization operations may be conveniently performed by executing Python code with PyRun_String , covered later in Section 24.3.4, with the module's dictionary as both the globals and locals argument. If you find yourself using PyRun_String extensively, rather than just as an occasional convenience, consider the possibility of splitting your extension module in two: a C-coded extension module offering raw, fast functionality, and a Python module wrapping the C-coded extension to provide further convenience and handy utilities.

When you do need to get a module's dictionary, use the PyModule_GetDict function.

PyObject* PyModule_GetDict(PyObject*


module


)

Returns a borrowed reference to the dictionary of module module . You should not use PyModule_GetDict for the specific tasks supported by the PyModule_Add functions covered earlier in this section; I suggest using PyModule_GetDict only for such purposes as supporting the use of PyRun_String .

If you need to access another module, you can import it by calling the PyImport_Import function.

PyObject* PyImport_Import(PyObject*


name


)

Imports the module named in Python string object name and returns a new reference to the module object, like Python's _ _import_ _( name ) . PyImport_Import is the highest-level, simplest, and most often used way to import a module.

Beware, in particular, of using function PyImport_ImportModule , which may often look more convenient because it accepts a char* argument. PyImport_ImportModule operates on a lower level, bypassing any import hooks that may be in force, so extensions that use it will be far harder to incorporate in packages such as those built by tools py2exe and Installer , covered in Chapter 26. Therefore, always do your importing by calling PyImport_Import , unless you have very specific needs and know exactly what you're doing.

To add functions to a module (or non-special methods to new types, as covered later in Section 24.1.12), you must describe the functions or methods in an array of PyMethodDef structures, and terminate the array with a sentinel (i.e., a structure whose fields are all or NULL ). PyMethodDef is defined as follows :

typedef struct {
    char*


ml_name


;        /* Python name of function or method */
    PyCFunction


ml_meth


;  /* pointer to C function impl */
    int


ml_flags


;         /* flag describing how to pass arguments */
    char*


ml_doc


;         /* docstring for the function or method */
} PyMethodDef

You must cast the second field to (PyCFunction) unless the C function's signature is exactly PyObject* function (PyObject* self , PyObject* args ) , which is the typedef for PyCFunction . This signature is correct when ml_flags is METH_O , meaning a function that accepts a single argument, or METH_VARARGS , meaning a function that accepts positional arguments. For METH_O , args is the only argument. For METH_VARARGS , args is a tuple of all arguments, to be parsed with the C API function PyArg_ParseTuple . However, ml_flags can also be METH_NOARGS , meaning a function that accepts no arguments, or METH_KEYWORDS , meaning a function that accepts both positional and named arguments. For METH_NOARGS , the signature is PyObject* function (PyObject* self ) , without arguments. For METH_KEYWORDS , the signature is:

PyObject*


function


(PyObject*


self


, PyObject*


args


, PyObject*


kwds


)

args is the tuple of positional arguments, and kwds the dictionary of named arguments. args and kwds are parsed together with the C API function PyArg_ParseTupleAndKeywords .

When a C-coded function implements a module's function, the self parameter of the C function is always NULL for any value of the ml_flags field. When a C-coded function implements a non-special method of an extension type, the self parameter points to the instance on which the method is being called.

24.1.5 Reference Counting

Python objects live on the heap, and C code sees them via PyObject* . Each PyObject counts how many references to itself are outstanding, and destroys itself when the number of references goes down to . To make this possible, your code must use Python-supplied macros: Py_INCREF to add a reference to a Python object, and Py_DECREF to abandon a reference to a Python object. The Py_XINCREF and Py_XDECREF macros are like Py_INCREF and Py_DECREF , but you may also use them innocuously on a null pointer. The test for a non-null pointer is implicitly performed inside the Py_XINCREF and Py_XDECREF macros, which saves you from needing to write out that test explicitly.

A PyObject* p , which your code receives by calling or being called by other functions, is known as a new reference if the code that supplies p has already called Py_INCREF on your behalf . Otherwise, it is called a borrowed reference . Your code is said to own new references it holds, but not borrowed ones. You can call Py_INCREF on a borrowed reference to make it into a reference that you own; you must do this if you need to use the reference across calls to code that might cause the count of the reference you borrowed to be decremented. You must always call Py_DECREF before abandoning or overwriting references that you own, but never on references you don't own. Therefore, understanding which interactions transfer reference ownership and which ones rely on reference borrowing is absolutely crucial. For most functions in the C API, and for all functions that you write and Python calls, the following general rules apply:

1. PyObject* arguments are borrowed references

2. A PyObject* returned as the function's result transfers ownership

For each of the two rules, there are occasional exceptions. PyList_SetItem and PyTuple_SetItem steal a reference to the item they are setting (but not to the list or tuple object into which they're setting it). So do the faster versions of these two functions that exist as C preprocessor macros, PyList_SET_ITEM and PyTuple_SET_ITEM . So does PyModule_AddObject , covered earlier in this chapter. There are no other exceptions to the first rule. The rationale for these exceptions, which may help you remember them, is that the object you're setting is most often one you created for the purpose, so the reference-stealing semantics save you from having to call Py_DECREF immediately afterward.

The second rule has more exceptions than the first one: there are several cases in which the returned PyObject* is a borrowed reference rather than a new reference. The abstract functions, whose names begin with PyObject_ , PySequence_ , PyMapping_ , and PyNumber_ , return new references. This is because you can call them on objects of many types, and there might not be any other reference to the resulting object that they return (i.e., the returned object might be created on the fly). The concrete functions, whose names begin with PyList_ , PyTuple_ , PyDict_ , and so on, return a borrowed reference when the semantics of the object they return ensure that there must be some other reference to the returned object somewhere.

In this chapter, I indicate all cases of exceptions to these rules (i.e., the return of borrowed references and the rare cases of reference stealing from arguments) regarding all functions that I cover. When I don't explicitly mention a function as being an exception, it means that the function follows the rules: its PyObject* arguments, if any, are borrowed references, and its PyObject* result, if any, is a new reference.

24.1.6 Accessing Arguments

A function that has ml_flags in its PyMethodDef set to METH_NOARGS is called from Python with no arguments. The corresponding C function has a signature with only one argument, self . When ml_flags is METH_O , Python code must call the function with one argument. The C function's second argument is a borrowed reference to the object that the Python caller passes as the argument's value.

When ml_flags is METH_VARARGS , Python code can call the function with any number of positional arguments, which are collected as a tuple. The C function's second argument is a borrowed reference to the tuple. Your C code can then call the PyArg_ParseTuple function.

int PyArg_ParseTuple(PyObject*


tuple


,char*


format


,...)

Returns for errors, a value not equal to for success. tuple is the PyObject* that was the C function's second argument. format is a C string that describes mandatory and optional arguments. The following arguments of PyArg_ParseTuple are the addresses of the C variables in which to put the values extracted from the tuple. Any PyObject* variables among the C variables are borrowed references. Table 24-1 lists the commonly used code strings, of which zero or more are joined to form string format .

Table 24-1. Format codes for PyArg_ParseTuple

c

char

d

double

d

Py_Complex

f

float

i

int

l

long

l

long long

O

PyObject*

O!

type + PyObject*

O&

convert + void*

s

char*

s#

char* + int

t#

char* + int

u

Py_UNICODE*

u#

Py_UNICODE* + int

w#

char* + int

z

char*

z#

char* + int

(...)

:

;

Code formats d to L accept numeric arguments from Python. Python coerces the corresponding values. For example, a code of i can correspond to a Python float —the fractional part gets truncated, as if built-in function int had been called. Py_Complex is a C struct with two fields named real and imag , both of type double .

O is the most general format code and accepts any argument, which you can later check and/or convert as needed. Variant O! corresponds to two arguments in the variable arguments: first the address of a Python type object, then the address of a PyObject* . O! checks that the corresponding value belongs to the given type (or any subtype of that type) before setting the PyObject* to point to the value. Variant O& also corresponds to two arguments in the variable arguments: first the address of a converter function you coded, then a void* (i.e., any address at all). The converter function must have signature int convert (PyObject* , void*) . Python calls your conversion function with the value passed from Python as the first argument and the void* from the variable arguments as the second argument. The conversion function must either return and raise an exception (as covered in Section 24.1.8 later in this chapter) to indicate an error, or return 1 and store whatever is appropriate via the void* it gets.

Code format s accepts a string from Python and the address of a char* (i.e., a char** ) among the variable arguments. It changes the char* to point at the string's buffer, which your C code must then treat as a read-only, null- terminated array of char s (i.e., a typical C string; however, your code must not modify it). The Python string must contain no embedded null characters . s# is similar, but corresponds to two arguments among the variable arguments: first the address of a char* , then the address of an int to set to the string's length. The Python string can contain embedded nulls, and therefore so can the buffer to which the char* is set to point. u and u# are similar, but accept any Unicode string, and the C-side pointers must be Py_UNICODE* rather than char* . Py_UNICODE is a macro defined in Python.h , and corresponds to the type of a Python Unicode character in the implementation (this is often, but not always, the same as a wchar_t in C).

t# and w# are similar to s# , but the corresponding Python argument can be any object of a type that respects the buffer protocol, respectively read-only and read-write. Strings are a typical example of read-only buffers. mmap and array instances are typical examples of read-write buffers, and they are also acceptable where a read-only buffer is required (i.e., for a t# ).

When one of the arguments is a Python sequence of known length, you can use format codes for each of its items, and corresponding C addresses among the variable arguments, by grouping the format codes in parentheses. For example, code (ii) corresponds to a Python sequence of two numbers , and, among the remaining arguments, corresponds to two addresses of int s.

The format string may include a vertical bar ( ) to indicate that all following arguments are optional. You must initialize the C variables, whose addresses you pass among the variable arguments for later arguments, to suitable default values before you call PyArg_ParseTuple . PyArg_ParseTuple does not change the C variables corresponding to optional arguments that were not passed in a given call from Python to your C-coded function.

The format string may optionally end with : name to indicate that name must be used as the function name if any error messages are needed. Alternatively, the format string may end with ; text to indicate that text must be used as the entire error message if PyArg_ParseTuple detects errors (this is rarely used).

A function that has ml_flags in its PyMethodDef set to METH_KEYWORDS accepts positional and keyword arguments. Python code calls the function with any number of positional arguments, which get collected as a tuple, and keyword arguments, which get collected as a dictionary. The C function's second argument is a borrowed reference to the tuple, and the third one is a borrowed reference to the dictionary. Your C code then calls the PyArg_ParseTupleAndKeywords function.

int PyArg_ParseTupleAndKeywords(PyObject*


tuple


,PyObject*


dict


, 
char*


format


,char**


kwlist


,...)

Returns for errors, a value not equal to for success. tuple is the PyObject* that was the C function's second argument. dict is the PyObject* that was the C function's third argument. format is like for PyArg_ParseTuple , except that it cannot include the (...) format code to parse nested sequences. kwlist is an array of char* terminated by a NULL sentinel, with the names of the parameters, one after the other. For example, the following C code:

static PyObject*
func_c(PyObject* self, PyObject* args, PyObject* kwds)
{
    static char* argnames[] = {"x", "y", "z", NULL};
    double x, y=0.0, z=0.0;
    if(!PyArg_ParseTupleAndKeywords(
        args,kwds,"ddd",argnames,&x,&y,&z))
        return NULL;
    /* rest of function snipped */

is roughly equivalent to this Python code:

def func_py(x, y=0.0, z=0.0):
    x, y, z = map(float, (x,y,z))
    # rest of function snipped

24.1.7 Creating Python Values

C functions that communicate with Python must often build Python values, both to return as their PyObject* result and for other purposes, such as setting items and attributes. The simplest and handiest way to build a Python value is most often with the Py_BuildValue function.

PyObject* Py_BuildValue(char*


format


,...)

format is a C string that describes the Python object to build. The following arguments of Py_BuildValue are C values from which the result is built. The PyObject* result is a new reference. Table 24-2 lists the commonly used code strings, of which zero or more are joined into string format . Py_BuildValue builds and returns a tuple if format contains two or more format codes, or if format begins with ( and ends with ) . Otherwise, the result is not a tuple. When you pass buffers, as for example in the case of format code s# , Py_BuildValue copies the data. You can therefore modify, abandon, or free( ) your original copy of the data after Py_BuildValue returns. Py_BuildValue always returns a new reference (except for format code N ). Called with an empty format , Py_BuildValue("") returns a new reference to None .

Table 24-2. Format codes for Py_BuildValue

c

char

d

double

d

Py_Complex

i

int

l

long

N

PyObject*

O

PyObject*

O&

convert + void*

s

char*

s#

char* + int

u

Py_UNICODE*

u#

Py_UNICODE* + int

(...)

[...]

{...}

Code O& corresponds to two arguments among the variable arguments: first the address of a converter function you code, then a void* (i.e., any address at all). The converter function must have signature PyObject* convert (void*) . Python calls the conversion function with the void* from the variable arguments as the only argument. The conversion function must either return NULL and raise an exception (as covered in Section 24.1.8 later in this chapter) to indicate an error, or return a new reference PyObject* built from the data in the void* .

Code {...} builds dictionaries from an even number of C values, alternately keys and values. For example, Py_BuildValue("{issi}",23,"zig","zag",42) returns a dictionary like Python's {23:'zig','zag':42} .

Note the important difference between codes N and O . N steals a reference from the PyObject* corresponding value among the variable arguments, so it's convenient when you're building an object including a reference you own that you would otherwise have to Py_DECREF . O does no reference stealing, so it's appropriate when you're building an object including a reference you don't own, or a reference you must also keep elsewhere.

24.1.8 Exceptions

To propagate exceptions raised from other functions you call, return NULL as the PyObject* result from your C function. To raise your own exceptions, set the current-exception indicator and return NULL . Python's built-in exception classes (covered in Chapter 6) are globally available, with names starting with PyExc_ , such as PyExc_AttributeError , PyExc_KeyError , and so on. Your extension module can also supply and use its own exception classes. The most commonly used C API functions related to raising exceptions are the following.

PyObject* PyErr_Format(PyObject*


type


,char*


format


,...)

Raises an exception of class type , a built-in such as PyExc_IndexError , or an exception class created with PyErr_NewException . Builds the associated value from format string format , which has syntax similar to printf 's, and the following C values indicated as variable arguments above. Returns NULL , so your code can just call:

return PyErr_Format(PyExc_KeyError, 
    "Unknown key name (%s)", thekeystring);

PyObject* PyErr_NewException(char*


name


,PyObject*


base


,PyObject*


dict


)

Subclasses exception class base , with extra class attributes and methods from dictionary dict (normally NULL , meaning no extra class attributes or methods), creating a new exception class named name (string name must be of the form " modulename . classname ") and returning a new reference to the new class object. When base is NULL , uses PyExc_Exception as the base class. You normally call this function during initialization of a module object module . For example:

PyModule_AddObject(module, "error", 
    PyErr_NewException("mymod.error", NULL, NULL));

PyObject* PyErr_NoMemory(  )

Raises an out-of-memory error and returns NULL , so your code can just call:

return PyErr_NoMemory(  );

void PyErr_SetObject(PyObject*


type


,PyObject*


value


)

Raises an exception of class type , a built-in such as PyExc_KeyError , or an exception class created with PyErr_NewException , with value as the associated value (a borrowed reference). PyErr_SetObject is a void function (i.e., returns no value).

PyObject* PyErr_SetFromErrno(PyObject*


type


)

Raises an exception of class type , a built-in such as PyExc_OSError , or an exception class created with PyErr_NewException . Takes all details from global variable errno , which C library functions and system calls set for many error cases, and the standard C library function strerror . Returns NULL , so your code can just call:

return PyErr_SetFromErrno(PyExc_IOError);

PyObject* PyErr_SetFromErrnoWithFilename(PyObject*


type


,char*


filename


)

Like PyErr_SetFromErrno , but also provides string filename as part of the exception's value. When filename is NULL , works like PyErr_SetFromErrno .

Your C code may want to deal with an exception and continue, as a try / except statement would let you do in Python code. The most commonly used C API functions related to catching exceptions are the following.

void PyErr_Clear(  )

Clears the error indicator. Innocuous if no error is pending.

int PyErr_ExceptionMatches(PyObject*


type


)

Call only when an error is pending, or the whole program might crash. Returns a value not equal to when the pending exception is an instance of the given type or any subclass of type , or when the pending exception is not such an instance.

PyObject* PyErr_Occurred(  )

Returns NULL if no error is pending, otherwise a borrowed reference to the type of the pending exception. (Don't use the returned value; call PyErr_ExceptionMatches instead, in order to catch exceptions of subclasses as well, as is normal and expected.)

void PyErr_Print(  )

Call only when an error is pending, or the whole program might crash. Outputs a standard traceback to sys.stderr , then clears the error indicator.

If you need to process errors in highly sophisticated ways, study other error-related functions of the C API, such as PyErr_Fetch , PyErr_Normalize , PyErr_GivenExceptionMatches , and PyErr_Restore . However, I do not cover such advanced and rarely needed possibilities in this book.

24.1.9 Abstract Layer Functions

The code for a C extension typically needs to use some Python functionality. For example, your code may need to examine or set attributes and items of Python objects, call Python-coded and built-in functions and methods, and so on. In most cases, the best approach is for your code to call functions from the abstract layer of Python's C API. These are functions that you can call on any Python object (functions whose names start with PyObject_ ), or any object within a wide category, such as mappings, numbers, or sequences (with names respectively starting with PyMapping_ , PyNumber_ , and PySequence_ ).

Some of the functions callable on objects within these categories duplicate functionality that is also available from PyObject_ functions; in these cases, you should use the PyObject_ function instead. I don't cover such redundant functions in this book.

Functions in the abstract layer raise Python exceptions if you call them on objects to which they are not applicable . All of these functions accept borrowed references for PyObject* arguments, and return a new reference ( NULL for an exception) if they return a PyObject* result.

The most frequently used abstract layer functions are the following.

int PyCallable_Check(PyObject*


x


)

True if x is callable, like Python's callable( x ) .

PyObject* PyEval_CallObject(PyObject*


x


,PyObject*


args


)

Calls callable Python object x with the positional arguments held in tuple args . Returns the call's result, like Python's return x (* args ) .

PyObject* PyEval_CallObjectWithKeywords(PyObject*


x


,PyObject*


args


,PyObject*


kwds


)

Calls callable Python object x with the positional arguments held in tuple args and the named arguments held in dictionary kwds Returns the call's result, like Python's return x (* args ,** kwds ) .

int PyIter_Check(PyObject*


x


)

True if x supports the iterator protocol (i.e., if x is an iterator).

PyObject* PyIter_Next(PyObject*


x


)

Returns the next item from iterator x . Returns NULL without raising any exception if x 's iteration is finished (i.e., when Python's x .next( ) raises StopIteration ).

int PyNumber_Check(PyObject*


x


)

True if x supports the number protocol (i.e., if x is a number).

PyObject* PyObject_CallFunction(PyObject*


x


,char*


format


,...)

Calls the callable Python object x with positional arguments described by format string format , using the same format codes as Py_BuildValue , covered earlier. When format is NULL , calls x with no arguments. Returns the call's result.

PyObject* PyObject_CallMethod(PyObject*


x


,char*


method


,char*


format


,...)

Calls the method named method of Python object x with positional arguments described by format string format , using the same format codes as Py_BuildValue . When format is NULL , calls the method with no arguments. Returns the call's result.

int PyObject_Cmp(PyObject*


x1


,PyObject*


x2


,int*


result


)

Compares objects x1 and x2 and places the result ( -1 , , or 1 ) in * result , like Python's result =cmp( x1 , x2 ) .

int PyObject_DelAttrString(PyObject*


x


,char*


name


)

Deletes x 's attribute named name , like Python's del x . name .

int PyObject_DelItem(PyObject*


x


,PyObject*


key


)

Deletes x 's item with key (or index) key , like Python's del x [ key ] .

int PyObject_DelItemString(PyObject*


x


,char*


key


)

Deletes x 's item with key key , like Python's del x [ key ] .

PyObject* PyObject_GetAttrString(PyObject*


x


,char*


name


)

Returns x 's attribute named name , like Python's x . name .

PyObject* PyObject_GetItem(PyObject*


x


,PyObject*


key


)

Returns x 's item with key (or index) key , like Python's x [ key ] .

int PyObject_GetItemString(PyObject*


x


,char*


key


)

Returns x 's item with key key , like Python's x [ key ] .

PyObject* PyObject_GetIter(PyObject*


x


)

Returns an iterator on x , like Python's iter( x ) .

int PyObject_HasAttrString(PyObject*


x


,char*


name


)

True if x has an attribute named name , like Python's hasattr( x , name ) .

int PyObject_IsTrue(PyObject*


x


)

True if x is true for Python, like Python's bool( x ) .

int PyObject_Length(PyObject*


x


)

Returns x 's length, like Python's len( x ) .

PyObject* PyObject_Repr(PyObject*


x


)

Returns x 's detailed string representation, like Python's repr( x ) .

PyObject* PyObject_RichCompare(PyObject*


x


,PyObject*


y


,int


op


)

Performs the comparison indicated by op between x and y , and returns the result as a Python object. op can be Py_EQ , Py_NE , Py_LT , Py_LE , Py_GT , or Py_GE , corresponding to Python comparisons x == y , x != y , x < y , x <= y , x > y , or x >= y , respectively.

int PyObject_RichCompareBool(PyObject*


x


,PyObject*


y


,int


op


)

Like PyObject_RichCompare , but returns for false, 1 for true.

int PyObject_SetAttrString(PyObject*


x


,char*


name


,PyObject*


v


)

Sets x 's attribute named name to v , like Python's x . name = v .

int PyObject_SetItem(PyObject*


x


,PyObject*


k


,PyObject *


v


)

Sets x 's item with key (or index) key to v , like Python's x [ key ]= v .

int PyObject_SetItemString(PyObject*


x


,char*


key


,PyObject *


v


)

Sets x 's item with key key to v , like Python's x [ key ]= v .

PyObject* PyObject_Str(PyObject*


x


)

Returns x 's readable string form, like Python's str( x ) .

PyObject* PyObject_Type(PyObject*


x


)

Returns x 's type object, like Python's type( x ) .

PyObject* PyObject_Unicode(PyObject*


x


)

Returns x 's Unicode string form, like Python's unicode( x ) .

int PySequence_Contains(PyObject*


x


,PyObject*


v


)

True if v is an item in x , like Python's v in x .

int PySequence_DelSlice(PyObject*


x


,int


start


,int


stop


)

Delete x 's slice from start to stop , like Python's del x [ start : stop ] .

PyObject* PySequence_Fast(PyObject*


x


)

Returns a new reference to a tuple with the same items as x , unless x is a list, in which case returns a new reference to x . When you need to get many items of an arbitrary sequence x , it's fastest to call t =PySequence_Fast( x ) once, then call PySequence_Fast_GET_ITEM( t , i ) as many times as needed, and finally call Py_DECREF( t ) .

PyObject* PySequence_Fast_GET_ITEM(PyObject*


x


,int


i


)

Returns the i item of x , where x must be the result of PySequence_Fast , x !=NULL , and 0<=i<PySequence_Fast_GET_SIZE( t ) . Violating these conditions can cause program crashes: this approach is optimized for speed, not for safety.

int PySequence_Fast_GET_SIZE(PyObject*


x


)

Returns the length of x . x must be the result of PySequence_Fast , x !=NULL .

PyObject* PySequence_GetSlice(PyObject*


x


,int


start


,int


stop


)

Returns x 's slice from start to stop , like Python's x [ start : stop ] .

PyObject* PySequence_List(PyObject*


x


)

Returns a new list object with the same items as x , like Python's list( x ) .

int PySequence_SetSlice(PyObject*


x


,int


start


,int


stop


,PyObject*


v


)

Sets x 's slice from start to stop to v , like Python's x [ start : stop ]= v . Just as in the equivalent Python statement, v must be a sequence of the same type as x .

PyObject* PySequence_Tuple(PyObject*


x


)

Returns a new reference to a tuple with the same items as x , like Python's tuple( x ) .

The functions whose names start with PyNumber_ allow you to perform numeric operations. Unary PyNumber functions, which take one argument PyObject* x and return a PyObject* , are listed in Table 24-3 with their Python equivalents.

Table 24-3. Unary PyNumber functions

PyNumber_Absolute

abs(x)

PyNumber_Float

float(x)

PyNumber_Int

int(x)

PyNumber_Invert

~x

PyNumber_Long

long(x)

PyNumber_Negative

-x

PyNumber_Positive

+x

Binary PyNumber functions, which take two PyObject* arguments x and y and return a PyObject* , are similarly listed in Table 24-4.

Table 24-4. Binary PyNumber functions

PyNumber_Add

x + y

PyNumber_And

x & y

PyNumber_Divide

x / y

PyNumber_Divmod

divmod(x, y)

PyNumber_FloorDivide

x // y

PyNumber_Lshift

x << y

PyNumber_Multiply

x * y

PyNumber_Or

x  y

PyNumber_Remainder

x % y

PyNumber_Rshift

x >> y

PyNumber_Subtract

x - y

PyNumber_TrueDivide

PyNumber_Xor

x ^ y

All the binary PyNumber functions have in-place equivalents whose names start with PyNumber_InPlace , such as PyNumber_InPlaceAdd and so on. The in-place versions try to modify the first argument in-place, if possible, and in any case return a new reference to the result, be it the first argument (modified) or a new object. Python's built-in numbers are immutable; therefore, when the first argument is a number of a built-in type, the in-place versions work just the same as the ordinary versions. Function PyNumber_Divmod returns a tuple with two items (the quotient and the remainder) and has no in-place equivalent.

There is one ternary PyNumber function, PyNumber_Power .

PyObject* PyNumber_Power(PyObject*


x


,PyObject*


y


,PyObject*


z


)

When z is Py_None , returns x raised to the y power, like Python's x ** y or equivalently pow( x,y ) . Otherwise, returns x ** y % z , like Python's pow( x,y,z ) . The in-place version is named PyNumber_InPlacePower .

24.1.10 Concrete Layer Functions

Each specific type of Python built-in object supplies concrete functions to operate on instances of that type, with names starting with Py type _ (e.g., PyInt_ for functions related to Python int s). Most such functions duplicate the functionality of abstract-layer functions or auxiliary functions covered earlier in this chapter, such as Py_BuildValue , which can generate objects of many types. In this section, I cover some frequently used functions from the concrete layer that provide unique functionality or substantial convenience or speed. For most types, you can check if an object belongs to the type by calling Py type _Check , which also accepts instances of subtypes , or Py type _CheckExact , which accepts only instances of type , not of subtypes. Signatures are as for functions PyIter_Check , covered earlier in this chapter.

PyObject* PyDict_GetItem(PyObject*


x


,PyObject*


key


)

Returns a borrowed reference to the item with key key of dictionary x .

int PyDict_GetItemString(PyObject*


x


,char*


key


)

Returns a borrowed reference to the item with key key of dictionary x .

int PyDict_Next(PyObject*


x


,int*


pos


,PyObject**


k


,PyObject**


v


)

Iterates over items in dictionary x . You must initialize * pos to at the start of the iteration: PyDict_Next uses and updates * pos to keep track of its place. For each successful iteration step, returns 1 ; when there are no more items, returns . Updates * k and * v to point to the next key and value respectively (borrowed references) at each step that returns 1 . You can pass either k or v as NULL if you are not interested in the key or value. During an iteration, you must not change in any way the set of x 's keys, but you can change x 's values as long as the set of keys remains identical.

int PyDict_Merge(PyObject*


x


,PyObject*


y


,int


override


)

Updates dictionary x by merging the items of dictionary y into x . override determines what happens when a key k is present in both x and y : if override is , then x [ k ] remains the same; otherwise x [ k ] is replaced by the value y [ k ] .

int PyDict_MergeFromSeq2(PyObject*


x


,PyObject*


y


,int


override


)

Like PyDict_Merge , except that y is not a dictionary but a sequence of sequences, where each subsequence has length 2 and is used as a ( key , value ) pair.

double PyFloat_AS_DOUBLE(PyObject*


x


)

Returns the C double value of Python float x , very fast, without error checking.

PyObject* PyList_New(int


length


)

Returns a new, uninitialized list of the given length . You must then initialize the list, typically by calling PyList_SET_ITEM length times.

PyObject* PyList_GET_ITEM(PyObject*


x


,int


pos


)

Returns the pos item of list x , without error checking.

int PyList_SET_ITEM(PyObject*


x


,int


pos


,PyObject*


v


)

Sets the pos item of list x to v , without error checking. Steals a reference to v . Use only immediately after creating a new list x with PyList_New .

char* PyString_AS_STRING(PyObject*


x


)

Returns a pointer to the internal buffer of string x , very fast, without error checking. You must not modify the buffer in any way, unless you just allocated it by calling PyString_FromStringAndSize(NULL , size ) .

int PyString_AsStringAndSize(PyObject*


x


,char**


buffer


,int*


length


)

Puts a pointer to the internal buffer of string x in * buffer , and x 's length in * length . You must not modify the buffer in any way, unless you just allocated it by calling PyString_FromStringAndSize(NULL , size ) .

PyObject* PyString_FromFormat(char*


format


,...)

Returns a Python string built from format string format , which has syntax similar to printf 's, and the following C values indicated as variable arguments above.

PyObject* PyString_FromFormat(char*


data


,int


size


)

Returns a Python string of length size , copying size bytes from data . When data is NULL , the Python string is uninitialized, and you must initialize it. You can get the pointer to the string's internal buffer by calling PyString_AS_STRING .

PyObject* PyTuple_New(int


length


)

Returns a new, uninitialized tuple of the given length . You must then initialize the tuple, typically by calling PyTuple_SET_ITEM length times.

PyObject* PyTuple_GET_ITEM(PyObject*


x


,int


pos


)

Returns the pos item of tuple x , without error checking.

int PyTuple_SET_ITEM(PyObject*


x


,int


pos


,PyObject*


v


)

#include <Python.h>

static PyObject*
merge(PyObject* self, PyObject* args, PyObject* kwds)
{
    static char* argnames[] = {"x","y","override",NULL};
    PyObject *x, *y;
    int override = 0;
    if(!PyArg_ParseTupleAndKeywords(args, kwds, "O!Oi", argnames,
        &PyDict_Type, &x, &y, &override))
            return NULL;
    if(-1 == PyDict_Merge(x, y, override)) {
        if(!PyErr_ExceptionMatches(PyExc_TypeError)):
            return NULL;
        PyErr_Clear(  );
        if(-1 == PyDict_MergeFromSeq2(x, y, override))
            return NULL;
    }
    return Py_BuildValue("");
}

static char merge_docs[] = "\
merge(x,y,override=False): merge into dict x the items of dict y (or the pairs\n\
    that are the items of y, if y is a sequence), with optional override.\n\
    Alters dict x directly, returns None.\n\
";

static PyObject*
mergenew(PyObject* self, PyObject* args, PyObject* kwds)
{
    static char* argnames[] = {"x","y","override",NULL};
    PyObject *x, *y, *result;
    int override = 0;
    if(!PyArg_ParseTupleAndKeywords(args, kwds, "O!Oi", argnames,
        &PyDict_Type, &x, &y, &override))
            return NULL;
    result = PyObject_CallMethod(x, "copy", "");
    if(!result)
        return NULL;
    if(-1 == PyDict_Merge(result, y, override)) {
        if(!PyErr_ExceptionMatches(PyExc_TypeError)):
            return NULL;
        PyErr_Clear(  );
        if(-1 == PyDict_MergeFromSeq2(result, y, override))
            return NULL;
    }
    return result;
}

static char merge_docs[] = "\
mergenew(x,y,override=False): merge into dict x the items of dict y (or\n\
     the pairs that are the items of y, if y is a sequence), with optional\n\
     override.  Does NOT alter x, but rather returns the modified copy as\n\
     the function's result.\n\
";

static PyMethodDef funcs[] = {
    {"merge", (PyCFunction)merge, METH_KEYWORDS, merge_docs},
    {"mergenew", (PyCFunction)mergenew, METH_KEYWORDS, mergenew_docs},
    {NULL}
};

void
initmerge(void)
{
    Py_InitModule3("merge", funcs, "Example extension module");
}

from distutils.core import setup, Extension
setup(name='merge', ext_modules=[ Extension('merge',sources=['merge.c']) ])

import merge
x = {'a':1,'b':2 }
merge.merge(x,[['b',3],['c',4]])
print x                               # prints: {'a':1, 'b':2, 'c':4 }
print merge.mergenew(x,{'a':5,'d':6},override=1) 
# prints: {'a':5, 'b':2, 'c':4, 'd':6 }
print x                               # prints: {'a':1, 'b':2, 'c':4 }

typedef struct {
    PyObject_HEAD
    /* other data needed by instances of this type, omitted */
} mytype;

static PyTypeObject t_mytype = {
/* tp_head */        PyObject_HEAD_INIT(NULL)   /* use NULL, for MSVC++ */
/* tp_internal */    0,                 /* must be 0 */
/* tp_name

/

"mymodule.mytype",  /* type name with module */
/* tp_basicsize */   sizeof(mytype),
/* tp_itemsize */    0,                 /* 0 except variable-size type */
/* tp_dealloc */     (destructor)mytype_dealloc,
/* tp_print */       0,                 /* usually 0, use str instead */
/* tp_getattr */     0,                 /* usually 0 (see getattro) */
/* tp_setattr */     0,                 /* usually 0 (see setattro) */
/* tp_compare*/      0,                 /* see also richcompare */
/* tp_repr */        (reprfunc)mytype_str,    /* like Python's _  _repr_  _ */
    /* rest of struct omitted */

static PyObject* mytype_str(mytype* self) { ... /* rest omitted */

static void mytype_dealloc(PyObject *x)
{
    x->ob_type->tp_free((PyObject*)x);
}

int


init_name


(PyObject *


self


,PyObject *


args


,PyObject *


kwds


)

PyObject*


new_name


(PyObject *


subtype


,PyObject *


args


,PyObject *


kwds


)

typedef struct {
    char*


name


;        /* Python-visible name of the member */
    int


type


;          /* code defining the data-type of the member */
    int


offset


;        /* offset of the member in the per-instance struct */
    int


flags


;         /* READONLY for a read-only member */
    char*


doc


;         /* docstring for the member */
} PyMemberDef

typedef struct {
    PyObject_HEAD
    double


datum


;
    char*


name


;
} mytype;

static PyMemberDef[] mytype_members = {
    {"datum", T_DOUBLE, offsetof(mytype, datum), 0, "The current datum"},
    {"name", T_STRING, offsetof(mytype, name), READONLY, 
     "Name of the datum"},
    {NULL}
};

#include "Python.h"
#include "structmember.h"

/* per-instance data structure */
typedef struct {
    PyObject_HEAD
    int first, second;
} intpair;

static int
intpair_init(PyObject *self, PyObject *args, PyObject *kwds)
{
    static char* nams[] = {"first","second",NULL};
    int first, second;
    if(!PyArg_ParseTupleAndKeywords(args, kwds, "ii", nams, &first, &second))
        return -1;
    ((intpair*)self)->first = first;
    ((intpair*)self)->second = second;
    return 0;
}

static void
intpair_dealloc(PyObject *self)
{
    self->ob_type->tp_free(self);
}

static PyObject*
intpair_str(PyObject* self)
{
    return PyString_FromFormat("intpair(%d,%d)",
        ((intpair*)self)->first, ((intpair*)self)->second);
}

static PyMemberDef intpair_members[] = {
    {"first", T_INT, offsetof(intpair, first), 0, "first item" },
    {"second", T_INT, offsetof(intpair, second), 0, "second item" },
    {NULL}
};

static PyTypeObject t_intpair = {
    PyObject_HEAD_INIT(0)               /* tp_head */
    0,                                  /* tp_internal */
    "intpair.intpair",                  /* tp_name */
    sizeof(intpair),                    /* tp_basicsize */
    0,                                  /* tp_itemsize */
    intpair_dealloc,                    /* tp_dealloc */
    0,                                  /* tp_print */
    0,                                  /* tp_getattr */
    0,                                  /* tp_setattr */
    0,                                  /* tp_compare */
    intpair_str,                        /* tp_repr */
    0,                                  /* tp_as_number */
    0,                                  /* tp_as_sequence */
    0,                                  /* tp_as_mapping */
    0,                                  /* tp_hash */
    0,                                  /* tp_call */
    0,                                  /* tp_str */
    PyObject_GenericGetAttr,            /* tp_getattro */
    PyObject_GenericSetAttr,            /* tp_setattro */
    0,                                  /* tp_as_buffer */
    Py_TPFLAGS_DEFAULT,
    "two ints (first,second)",
    0,                                  /* tp_traverse */
    0,                                  /* tp_clear */
    0,                                  /* tp_richcompare */
    0,                                  /* tp_weaklistoffset */
    0,                                  /* tp_iter */
    0,                                  /* tp_iternext */
    0,                                  /* tp_methods */
    intpair_members,                    /* tp_members */
    0,                                  /* tp_getset */
    0,                                  /* tp_base */
    0,                                  /* tp_dict */
    0,                                  /* tp_descr_get */
    0,                                  /* tp_descr_set */
    0,                                  /* tp_dictoffset */
    intpair_init,                       /* tp_init */
    PyType_GenericAlloc,                /* tp_alloc */
    PyType_GenericNew,                  /* tp_new */
    _PyObject_Del,                      /* tp_free */
};

void
initintpair(void)
{
    static PyMethodDef no_methods[] = { {NULL} };
    PyObject* this_module = Py_InitModule("intpair", no_methods);
    PyType_Ready(&t_intpair);
    PyObject_SetAttrString(this_module, "intpair", (PyObject*)&t_intpair);
}

class intpair(object):
    __slots_  _ = 'first', 'second'
    def __init_  _(self, first, second):
        self.first = first
        self.second = second
    def __repr_  _(self):
        return 'intpair(%s,%s)' % (self.first, self.second)

import intpair
x=intpair.intpair(1.2,3.4)                 # x is: intpair(1,3)