[ python-Bugs-1484580 ] ctypes documenation obscure and incomplete

[SourceForge.net]

Bugs item #1484580, was opened at 2006-05-09 12:59
Message generated for change (Comment added) made by theller
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1484580&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
>Status: Closed
Resolution: None
Priority: 5
Private: No
Submitted By: Nicko van Someren (nicko)
Assigned to: Thomas Heller (theller)
Summary: ctypes documenation obscure and incomplete

Initial Comment:
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.




----------------------------------------------------------------------

>Comment By: Thomas Heller (theller)
Date: 2007-07-13 19:52

Message:
Logged In: YES 
user_id=11105
Originator: NO

Closing because no response.

----------------------------------------------------------------------

Comment By: Thomas Heller (theller)
Date: 2006-05-10 21:45

Message:
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?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1484580&group_id=5470