The documentation for ctypes in Python 2.5, drawn largely from the 
original ctypes tutorial, misses a number of important points which 
users will want to know.  In particular the documentation surrounding 
casting of types is currently non-existant and the documentation 
regarding the relationship between pointer(), byref() and array objects 
is at best limited.

In order to fix this I would suggest the following changes:

1) A new sub-sub-sub-section 13.14.1.x should be added to 
document the "cast()" function provided by ctypes.  The cast function 
takes two parameters, a ctypes object of some sort and a ctypes type 
class, and it returns the former cast to the later. e.g.:

    class Foo(Structure):
        _fields_ = [("x", c_int), ("y", c_int)]
    class Bar(Structure):
        _fields_ = [("count", c_int),("values", c_void_p)]

    f = Foo(1,2)
    b = Bar(1, cast(pointer(f), c_void_p))

I'm sure that there are many other subtleties to the cast() function 
which I don't know about, because they are not currently documented!

2) Nowhere is is explicitly stated that, where a pointer to a type is 
expected, a ctypes array object can be assigned instead.  While this is 
arguably intuitive to any C programmer it could with being 
documented.  Otherwise people will write:
    someFun.argtypes = [POINTER(Foo)]
    tenFoos = (Foo * 10)()
    someFun(cast(byref(tenFoos), POINTER(Foo)))
when the last line is better written:
    someFun(tenFoos)
Adding some words on this subject to section 13.14.1.13 (Arrays) or 
13.14.1.14 (Pointers) would be helpful.

Logged In: YES 
user_id=11105

Nicko, the attached file 'conversions.txt' contains a first
draft of a chapter that describes the 'cast' function and
that arrays are also accepted instead of pointers.  Could
you please review if this is useful?

Closing because no response.