[Python-checkins] r46695 - python/trunk/Doc/lib/lib.tex python/trunk/Doc/lib/libctypes.tex
tim.peters
python-checkins at python.org
Tue Jun 6 17:52:35 CEST 2006
Author: tim.peters
Date: Tue Jun 6 17:52:35 2006
New Revision: 46695
Modified:
python/trunk/Doc/lib/lib.tex
python/trunk/Doc/lib/libctypes.tex
Log:
On python-dev Thomas Heller said these were committed
by mistake in rev 46693, so reverting this part of
rev 46693.
Modified: python/trunk/Doc/lib/lib.tex
==============================================================================
--- python/trunk/Doc/lib/lib.tex (original)
+++ python/trunk/Doc/lib/lib.tex Tue Jun 6 17:52:35 2006
@@ -245,6 +245,7 @@
\input{libplatform}
\input{liberrno}
\input{libctypes}
+\input{libctypesref}
\input{libsomeos} % Optional Operating System Services
\input{libselect}
Modified: python/trunk/Doc/lib/libctypes.tex
==============================================================================
--- python/trunk/Doc/lib/libctypes.tex (original)
+++ python/trunk/Doc/lib/libctypes.tex Tue Jun 6 17:52:35 2006
@@ -1,4 +1,4 @@
-\ifx\locallinewidth\undefined\newlength{\locallinewidth}\fi
+\newlength{\locallinewidth}
\setlength{\locallinewidth}{\linewidth}
\section{\module{ctypes} --- A foreign function library for Python.}
\declaremodule{standard}{ctypes}
@@ -70,12 +70,6 @@
XXX Add section for Mac OS X.
-\subsubsection{Finding shared libraries\label{ctypes-finding-shared-libraries}}
-
-XXX Add description of ctypes.util.find{\_}library (once I really
-understand it enough to describe it).
-
-
\subsubsection{Accessing functions from loaded dlls\label{ctypes-accessing-functions-from-loaded-dlls}}
Functions are accessed as attributes of dll objects:
@@ -192,172 +186,158 @@
have to learn more about \code{ctypes} data types.
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
+\subsubsection{Simple data types\label{ctypes-simple-data-types}}
\code{ctypes} defines a number of primitive C compatible data types :
\begin{quote}
-\begin{tableiii}{l|l|l}{textrm}
-{
+
+\begin{longtable}[c]{|p{0.19\locallinewidth}|p{0.28\locallinewidth}|p{0.14\locallinewidth}|}
+\hline
+\textbf{
ctypes type
-}
-{
+} & \textbf{
C type
-}
-{
+} & \textbf{
Python type
-}
-\lineiii{
+} \\
+\hline
+\endhead
+
\class{c{\_}char}
-}
-{
+ &
\code{char}
-}
-{
+ &
character
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}byte}
-}
-{
+ &
\code{char}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}ubyte}
-}
-{
+ &
\code{unsigned char}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}short}
-}
-{
+ &
\code{short}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}ushort}
-}
-{
+ &
\code{unsigned short}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}int}
-}
-{
+ &
\code{int}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}uint}
-}
-{
+ &
\code{unsigned int}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}long}
-}
-{
+ &
\code{long}
-}
-{
+ &
integer
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}ulong}
-}
-{
+ &
\code{unsigned long}
-}
-{
+ &
long
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}longlong}
-}
-{
+ &
\code{{\_}{\_}int64} or
\code{long long}
-}
-{
+ &
long
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}ulonglong}
-}
-{
+ &
\code{unsigned {\_}{\_}int64} or
\code{unsigned long long}
-}
-{
+ &
long
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}float}
-}
-{
+ &
\code{float}
-}
-{
+ &
float
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}double}
-}
-{
+ &
\code{double}
-}
-{
+ &
float
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}char{\_}p}
-}
-{
+ &
\code{char *}
(NUL terminated)
-}
-{
+ &
string or
\code{None}
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}wchar{\_}p}
-}
-{
+ &
\code{wchar{\_}t *}
(NUL terminated)
-}
-{
+ &
unicode or
\code{None}
-}
-\lineiii{
+ \\
+\hline
+
\class{c{\_}void{\_}p}
-}
-{
+ &
\code{void *}
-}
-{
+ &
integer or
\code{None}
-}
-\end{tableiii}
+ \\
+\hline
+\end{longtable}
\end{quote}
All these types can be created by calling them with an optional
@@ -400,7 +380,6 @@
c_char_p('Hi, there')
>>> print s # first string is unchanged
Hello, World
->>>
\end{verbatim}
You should be careful, however, not to pass them to functions
@@ -596,7 +575,7 @@
>>> GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
>>> GetModuleHandle(None) # doctest: +WINDOWS
486539264
->>> GetModuleHandle("something silly") # doctest: +WINDOWS
+>>> GetModuleHandle("something silly") # doctest: +WINDOWS +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
File "<stdin>", line 1, in ?
File "<stdin>", line 3, in ValidHandle
@@ -765,7 +744,6 @@
>>>
>>> print len(MyStruct().point_array)
4
->>>
\end{verbatim}
Instances are created in the usual way, by calling the class:
@@ -794,10 +772,6 @@
\subsubsection{Pointers\label{ctypes-pointers}}
-XXX Rewrite this section. Normally one only uses indexing, not the .contents
-attribute!
-List some recipes with pointers. bool(ptr), POINTER(tp)(), ...?
-
Pointer instances are created by calling the \code{pointer} function on a
\code{ctypes} type:
\begin{verbatim}
@@ -807,25 +781,16 @@
>>>
\end{verbatim}
+XXX XXX Not correct: use indexing, not the contents atribute
+
Pointer instances have a \code{contents} attribute which returns the
-object to which the pointer points, the \code{i} object above:
+ctypes' type pointed to, the \code{c{\_}int(42)} in the above case:
\begin{verbatim}
>>> pi.contents
c_long(42)
>>>
\end{verbatim}
-Note that \code{ctypes} does not have OOR (original object return), it
-constructs a new, equivalent object each time you retrieve an
-attribute:
-\begin{verbatim}
->>> pi.contents is i
-False
->>> pi.contents is pi.contents
-False
->>>
-\end{verbatim}
-
Assigning another \class{c{\_}int} instance to the pointer's contents
attribute would cause the pointer to point to the memory location
where this is stored:
@@ -843,21 +808,23 @@
>>>
\end{verbatim}
+XXX What is this???
Assigning to an integer index changes the pointed to value:
\begin{verbatim}
->>> print i
-c_long(99)
+>>> i2 = pi[0]
+>>> i2
+99
>>> pi[0] = 22
->>> print i
-c_long(22)
+>>> i2
+99
>>>
\end{verbatim}
It is also possible to use indexes different from 0, but you must know
-what you're doing, just as in C: You can access or change arbitrary
-memory locations. Generally you only use this feature if you receive a
-pointer from a C function, and you \emph{know} that the pointer actually
-points to an array instead of a single item.
+what you're doing when you use this: You access or change arbitrary
+memory locations when you do this. Generally you only use this feature
+if you receive a pointer from a C function, and you \emph{know} that the
+pointer actually points to an array instead of a single item.
\subsubsection{Pointer classes/types\label{ctypes-pointer-classestypes}}
@@ -870,7 +837,7 @@
>>> PI = POINTER(c_int)
>>> PI
<class 'ctypes.LP_c_long'>
->>> PI(42)
+>>> PI(42) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: expected c_long instead of int
@@ -880,82 +847,6 @@
\end{verbatim}
-\subsubsection{Type conversions\label{ctypes-type-conversions}}
-
-Usually, ctypes does strict type checking. This means, if you have
-\code{POINTER(c{\_}int)} in the \member{argtypes} list of a function or in the
-\member{{\_}fields{\_}} of a structure definition, only instances of exactly the
-same type are accepted. There are some exceptions to this rule, where
-ctypes accepts other objects. For example, you can pass compatible
-array instances instead of pointer types. So, for \code{POINTER(c{\_}int)},
-ctypes accepts an array of c{\_}int values:
-\begin{verbatim}
->>> class Bar(Structure):
-... _fields_ = [("count", c_int), ("values", POINTER(c_int))]
-...
->>> bar = Bar()
->>> print bar._objects
-None
->>> bar.values = (c_int * 3)(1, 2, 3)
->>> print bar._objects
-{'1': ({}, <ctypes._endian.c_long_Array_3 object at ...>)}
->>> bar.count = 3
->>> for i in range(bar.count):
-... print bar.values[i]
-...
-1
-2
-3
->>>
-\end{verbatim}
-
-To set a POINTER type field to \code{NULL}, you can assign \code{None}:
-\begin{verbatim}
->>> bar.values = None
->>>
-\end{verbatim}
-
-XXX list other conversions...
-
-Sometimes you have instances of incompatible types. In \code{C}, you can
-cast one type into another type. \code{ctypes} provides a \code{cast}
-function which can be used in the same way. The Bar structure defined
-above accepts \code{POINTER(c{\_}int)} pointers or \class{c{\_}int} arrays for its
-\code{values} field, but not instances of other types:
-\begin{verbatim}
->>> bar.values = (c_byte * 4)()
-Traceback (most recent call last):
- File "<stdin>", line 1, in ?
-TypeError: incompatible types, c_byte_Array_4 instance instead of LP_c_long instance
->>>
-\end{verbatim}
-
-For these cases, the \code{cast} function is handy.
-
-The \code{cast} function can be used to cast a ctypes instance into a
-pointer to a different ctypes data type. \code{cast} takes two
-parameters, a ctypes object that is or can be converted to a pointer
-of some kind, and a ctypes pointer type. It returns an instance of
-the second argument, which references the same memory block as the
-first argument:
-\begin{verbatim}
->>> a = (c_byte * 4)()
->>> cast(a, POINTER(c_int))
-<ctypes.LP_c_long object at ...>
->>>
-\end{verbatim}
-
-So, \code{cast} can be used to assign to the \code{values} field of \code{Bar}
-the structure:
-\begin{verbatim}
->>> bar = Bar()
->>> bar.values = cast((c_byte * 4)(), POINTER(c_int))
->>> print bar.values[0]
-0
->>>
-\end{verbatim}
-
-
\subsubsection{Incomplete Types\label{ctypes-incomplete-types}}
\emph{Incomplete Types} are structures, unions or arrays whose members are
@@ -1284,7 +1175,6 @@
>>> rc.a, rc.b = rc.b, rc.a
>>> print rc.a.x, rc.a.y, rc.b.x, rc.b.y
3 4 3 4
->>>
\end{verbatim}
Hm. We certainly expected the last statement to print \code{3 4 1 2}.
@@ -1294,7 +1184,6 @@
>>> temp0, temp1 = rc.b, rc.a
>>> rc.a = temp0
>>> rc.b = temp1
->>>
\end{verbatim}
Note that \code{temp0} and \code{temp1} are objects still using the internal
@@ -1325,80 +1214,6 @@
Accessing the contents again constructs a new Python each time!
-\subsubsection{Variable-sized data types\label{ctypes-variable-sized-data-types}}
-
-\code{ctypes} provides some support for variable-sized arrays and
-structures (this was added in version 0.9.9.7).
-
-The \code{resize} function can be used to resize the memory buffer of an
-existing ctypes object. The function takes the object as first
-argument, and the requested size in bytes as the second argument. The
-memory block cannot be made smaller than the natural memory block
-specified by the objects type, a \code{ValueError} is raised if this is
-tried:
-\begin{verbatim}
->>> short_array = (c_short * 4)()
->>> print sizeof(short_array)
-8
->>> resize(short_array, 4)
-Traceback (most recent call last):
- ...
-ValueError: minimum size is 8
->>> resize(short_array, 32)
->>> sizeof(short_array)
-32
->>> sizeof(type(short_array))
-8
->>>
-\end{verbatim}
-
-This is nice and fine, but how would one access the additional
-elements contained in this array? Since the type still only knows
-about 4 elements, we get errors accessing other elements:
-\begin{verbatim}
->>> short_array[:]
-[0, 0, 0, 0]
->>> short_array[7]
-Traceback (most recent call last):
- ...
-IndexError: invalid index
->>>
-\end{verbatim}
-
-The solution is to use 1-element arrays; as a special case ctypes does
-no bounds checking on them:
-\begin{verbatim}
->>> short_array = (c_short * 1)()
->>> print sizeof(short_array)
-2
->>> resize(short_array, 32)
->>> sizeof(short_array)
-32
->>> sizeof(type(short_array))
-2
->>> short_array[0:8]
-[0, 0, 0, 0, 0, 0, 0, 0]
->>> short_array[7] = 42
->>> short_array[0:8]
-[0, 0, 0, 0, 0, 0, 0, 42]
->>>
-\end{verbatim}
-
-Using 1-element arrays as variable sized fields in structures works as
-well, but they should be used as the last field in the structure
-definition. This example shows a definition from the Windows header
-files:
-\begin{verbatim}
-class SP_DEVICE_INTERFACE_DETAIL_DATA(Structure):
- _fields_ = [("cbSize", c_int),
- ("DevicePath", c_char * 1)]
-\end{verbatim}
-
-Another way to use variable-sized data types with \code{ctypes} is to use
-the dynamic nature of Python, and (re-)define the data type after the
-required size is already known, on a case by case basis.
-
-
\subsubsection{Bugs, ToDo and non-implemented things\label{ctypes-bugs-todo-non-implemented-things}}
Enumeration types are not implemented. You can do it easily yourself,
@@ -1409,627 +1224,3 @@
% compile-command: "make.bat"
% End:
-
-\subsection{ctypes reference\label{ctypes-ctypes-reference}}
-
-
-\subsubsection{loading shared libraries\label{ctypes-loading-shared-libraries}}
-
-\begin{classdesc}{LibraryLoader}{dlltype}
-Class which loads shared libraries.
-\end{classdesc}
-
-\begin{methoddesc}{LoadLibrary}{name, mode=RTLD_LOCAL, handle=None}
-Load a shared library.
-\end{methoddesc}
-
-\begin{classdesc}{CDLL}{name, mode=RTLD_LOCAL, handle=None}
-XXX
-\end{classdesc}
-
-\begin{datadescni}{cdll}
-XXX
-\end{datadescni}
-
-\begin{funcdesc}{OleDLL}{name, mode=RTLD_LOCAL, handle=None}
-XXX
-\end{funcdesc}
-
-\begin{datadescni}{oledll}
-XXX
-\end{datadescni}
-
-\begin{classdesc*}{py_object}
-XXX
-\end{classdesc*}
-
-\begin{funcdesc}{PyDLL}{name, mode=RTLD_LOCAL, handle=None}
-XXX
-\end{funcdesc}
-
-\begin{datadescni}{pydll}
-XXX
-\end{datadescni}
-
-\begin{datadescni}{RTLD_GLOBAL}
-XXX
-\end{datadescni}
-
-\begin{datadescni}{RTLD_LOCAL}
-XXX
-\end{datadescni}
-
-\begin{funcdesc}{WinDLL}{name, mode=RTLD_LOCAL, handle=None}
-XXX
-\end{funcdesc}
-
-\begin{datadescni}{windll}
-XXX
-\end{datadescni}
-
-\begin{datadescni}{pythonapi()}
-XXX
-\end{datadescni}
-
-
-\subsubsection{foreign functions\label{ctypes-foreign-functions}}
-
-The ultimate goal of \code{ctypes} is to call functions in shared
-libraries, aka as foreign functions. Foreign function instances can
-be created by accessing them as attributes of loaded shared libraries,
-or by instantiating a \emph{function prototype}.
-
-Function prototypes are created by factory functions.
-
-They are created by calling one of the following factory functions:
-
-\begin{funcdesc}{CFUNCTYPE}{restype, *argtypes}
-This is a factory function that returns a function prototype. The
-function prototype describes a function that has a result type of
-\member{restype}, and accepts arguments as specified by
-\member{argtypes}. The function prototype can be used to construct
-several kinds of functions, depending on how the prototype is
-called.
-
-The prototypes returned by \function{CFUNCTYPE} or \code{PYFUNCTYPE} create
-functions that use the standard C calling convention, prototypes
-returned from \function{WINFUNCTYPE} (on Windows) use the \code{{\_}{\_}stdcall}
-calling convention.
-
-Functions created by calling the \function{CFUNCTYPE} and \function{WINFUNCTYPE}
-prototypes release the Python GIL before entering the foreign
-function, and acquire it back after leaving the function code.
-\end{funcdesc}
-
-\begin{funcdesc}{WINFUNCTYPE}{restype, *argtypes}
-TBD
-\end{funcdesc}
-
-\begin{funcdesc}{PYFUNCTYPE}{restype, *argtypes}
-TBD
-\end{funcdesc}
-
-\begin{excdesc}{ArgumentError()}
-This exception is raised when a foreign function call cannot
-convert one of the passed arguments.
-\end{excdesc}
-
-
-\subsubsection{helper functions\label{ctypes-helper-functions}}
-
-\begin{funcdesc}{addressof}{obj}
-Returns the address of the memory buffer as integer. \code{obj} must
-be an instance of a ctypes type.
-\end{funcdesc}
-
-\begin{funcdesc}{alignment}{obj_or_type}
-Returns the alignment requirements of a ctypes type.
-\code{obj{\_}or{\_}type} must be a ctypes type or instance.
-\end{funcdesc}
-
-\begin{funcdesc}{byref}{obj}
-Returns a light-weight pointer to \code{obj}, which must be an
-instance of a ctypes type. The returned object can only be used as
-a foreign function call parameter. It behaves similar to
-\code{pointer(obj)}, but the construction is a lot faster.
-\end{funcdesc}
-
-\begin{funcdesc}{cast}{obj, type}
-This function is similar to the cast operator in C. It returns a
-new instance of \code{type} which points to the same memory block as
-\code{obj}. \code{type} must be a pointer type, and \code{obj} must be an
-object that can be interpreted as a pointer.
-\end{funcdesc}
-
-\begin{funcdesc}{create_string_buffer}{init_or_size\optional{, size}}
-This function creates a mutable character buffer. The returned
-object is a ctypes array of \class{c{\_}char}.
-
-\code{init{\_}or{\_}size} must be an integer which specifies the size of
-the array, or a string which will be used to initialize the array
-items.
-
-If a string is specified as first argument, the buffer is made one
-item larger than the length of the string so that the last element
-in the array is a NUL termination character. An integer can be
-passed as second argument which allows to specify the size of the
-array if the length of the string should not be used.
-
-If the first parameter is a unicode string, it is converted into
-an 8-bit string according to ctypes conversion rules.
-\end{funcdesc}
-
-\begin{funcdesc}{create_unicode_buffer}{init_or_size\optional{, size}}
-This function creates a mutable unicode character buffer. The
-returned object is a ctypes array of \class{c{\_}wchar}.
-
-\code{init{\_}or{\_}size} must be an integer which specifies the size of
-the array, or a unicode string which will be used to initialize
-the array items.
-
-If a unicode string is specified as first argument, the buffer is
-made one item larger than the length of the string so that the
-last element in the array is a NUL termination character. An
-integer can be passed as second argument which allows to specify
-the size of the array if the length of the string should not be
-used.
-
-If the first parameter is a 8-bit string, it is converted into an
-unicode string according to ctypes conversion rules.
-\end{funcdesc}
-
-\begin{funcdesc}{DllCanUnloadNow}{}
-Windows only: This function is a hook which allows to implement
-inprocess COM servers with ctypes. It is called from the
-DllCanUnloadNow function that the {\_}ctypes extension dll exports.
-\end{funcdesc}
-
-\begin{funcdesc}{DllGetClassObject}{}
-Windows only: This function is a hook which allows to implement
-inprocess COM servers with ctypes. It is called from the
-DllGetClassObject function that the \code{{\_}ctypes} extension dll exports.
-\end{funcdesc}
-
-\begin{funcdesc}{FormatError}{\optional{code}}
-Windows only: Returns a textual description of the error code. If
-no error code is specified, the last error code is used by calling
-the Windows api function GetLastError.
-\end{funcdesc}
-
-\begin{funcdesc}{GetLastError}{}
-Windows only: Returns the last error code set by Windows in the
-calling thread.
-\end{funcdesc}
-
-\begin{funcdesc}{memmove}{dst, src, count}
-Same as the standard C memmove library function: copies \var{count}
-bytes from \code{src} to \var{dst}. \var{dst} and \code{src} must be
-integers or ctypes instances that can be converted to pointers.
-\end{funcdesc}
-
-\begin{funcdesc}{memset}{dst, c, count}
-Same as the standard C memset library function: fills the memory
-block at address \var{dst} with \var{count} bytes of value
-\var{c}. \var{dst} must be an integer specifying an address, or a
-ctypes instance.
-\end{funcdesc}
-
-\begin{funcdesc}{POINTER}{type}
-This factory function creates and returns a new ctypes pointer
-type. Pointer types are cached an reused internally, so calling
-this function repeatedly is cheap. type must be a ctypes type.
-\end{funcdesc}
-
-\begin{funcdesc}{pointer}{obj}
-This function creates a new pointer instance, pointing to
-\code{obj}. The returned object is of the type POINTER(type(obj)).
-
-Note: If you just want to pass a pointer to an object to a foreign
-function call, you should use \code{byref(obj)} which is much faster.
-\end{funcdesc}
-
-\begin{funcdesc}{resize}{obj, size}
-This function resizes the internal memory buffer of obj, which
-must be an instance of a ctypes type. It is not possible to make
-the buffer smaller than the native size of the objects type, as
-given by sizeof(type(obj)), but it is possible to enlarge the
-buffer.
-\end{funcdesc}
-
-\begin{funcdesc}{set_conversion_mode}{encoding, errors}
-This function sets the rules that ctypes objects use when
-converting between 8-bit strings and unicode strings. encoding
-must be a string specifying an encoding, like \code{'utf-8'} or
-\code{'mbcs'}, errors must be a string specifying the error handling
-on encoding/decoding errors. Examples of possible values are
-\code{"strict"}, \code{"replace"}, or \code{"ignore"}.
-
-set{\_}conversion{\_}mode returns a 2-tuple containing the previous
-conversion rules. On windows, the initial conversion rules are
-\code{('mbcs', 'ignore')}, on other systems \code{('ascii', 'strict')}.
-\end{funcdesc}
-
-\begin{funcdesc}{sizeof}{obj_or_type}
-Returns the size in bytes of a ctypes type or instance memory
-buffer. Does the same as the C \code{sizeof()} function.
-\end{funcdesc}
-
-\begin{funcdesc}{string_at}{address\optional{, size}}
-This function returns the string starting at memory address
-address. If size is specified, it is used as size, otherwise the
-string is assumed to be zero-terminated.
-\end{funcdesc}
-
-\begin{funcdesc}{WinError}{code=None, descr=None}
-Windows only: this function is probably the worst-named thing in
-ctypes. It creates an instance of WindowsError. If \var{code} is not
-specified, \code{GetLastError} is called to determine the error
-code. If \code{descr} is not spcified, \function{FormatError} is called to
-get a textual description of the error.
-\end{funcdesc}
-
-\begin{funcdesc}{wstring_at}{address}
-This function returns the wide character string starting at memory
-address \code{address} as unicode string. If \code{size} is specified,
-it is used as the number of characters of the string, otherwise
-the string is assumed to be zero-terminated.
-\end{funcdesc}
-
-
-\subsubsection{Data types\label{ctypes-data-types}}
-
-\begin{classdesc*}{_CData}
-This non-public class is the base class of all ctypes data types.
-Among other things, all ctypes type instances contain a memory
-block that hold C compatible data; the address of the memory block
-is returned by the \code{addressof()} helper function. Another
-instance variable is exposed as \member{{\_}objects}; this contains other
-Python objects that need to be kept alive in case the memory block
-contains pointers.
-\end{classdesc*}
-
-Common methods of ctypes data types, these are all class methods (to
-be exact, they are methods of the metaclass):
-
-\begin{methoddesc}{from_address}{address}
-This method returns a ctypes type instance using the memory
-specified by address.
-\end{methoddesc}
-
-\begin{methoddesc}{from_param}{obj}
-This method adapts obj to a ctypes type.
-\end{methoddesc}
-
-\begin{methoddesc}{in_dll}{name, library}
-This method returns a ctypes type instance exported by a shared
-library. \var{name} is the name of the symbol that exports the data,
-\code{library} is the loaded shared library.
-\end{methoddesc}
-
-Common instance variables of ctypes data types:
-
-\begin{memberdesc}{_b_base_}
-Sometimes ctypes data instances do not own the memory block they
-contain, instead they share part of the memory block of a base
-object. The \member{{\_}b{\_}base{\_}} readonly member is the root ctypes
-object that owns the memory block.
-\end{memberdesc}
-
-\begin{memberdesc}{_b_needsfree_}
-This readonly variable is true when the ctypes data instance has
-allocated the memory block itself, false otherwise.
-\end{memberdesc}
-
-\begin{memberdesc}{_objects}
-This member is either \code{None} or a dictionary containing Python
-objects that need to be kept alive so that the memory block
-contents is kept valid. This object is only exposed for
-debugging; never modify the contents of this dictionary.
-\end{memberdesc}
-
-
-\subsubsection{Fundamental data types\label{ctypes-fundamental-data-types}}
-
-\begin{classdesc*}{_SimpleCData}
-This non-public class is the base class of all fundamental ctypes
-data types. It is mentioned here because it contains the common
-attributes of the fundamental ctypes data types. \code{{\_}SimpleCData}
-is a subclass of \code{{\_}CData}, so it inherits the methods and
-attributes of that.
-\end{classdesc*}
-
-Instances have a single attribute:
-
-\begin{memberdesc}{value}
-This attribute contains the actual value of the instance. For
-integer and pointer types, it is an integer, for character types,
-it is a single character string, for character pointer types it
-is a Python string or unicode string.
-
-When the \code{value} attribute is retrieved from a ctypes instance,
-usually a new object is returned each time. \code{ctypes} does \emph{not}
-implement original object return, always a new object is
-constructed. The same is true for all other ctypes object
-instances.
-\end{memberdesc}
-
-Fundamental data types, whether returned as result of foreign function
-calls, or, for example, by retrieving structure field members, are
-transparently converted to native Python types. In other words, if a
-foreign function has a \member{restype} of \class{c{\_}char{\_}p}, you will always
-receive a Python string, \emph{not} a \class{c{\_}char{\_}p} instance.
-
-Subclasses of fundamental data types do \emph{not} inherit this behaviour.
-So, if a foreign functions \member{restype} is a subclass of \class{c{\_}void{\_}p},
-you will receive an instance of this subclass from the function call.
-Of course, you can get the value of the pointer by accessing the
-\code{value} attribute.
-
-These are the fundamental ctypes data types:
-
-\begin{classdesc*}{c_byte}
-Represents the C signed char datatype, and interprets the value as
-small integer. The constructor accepts an optional integer
-initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_char}
-Represents the C char datatype, and interprets the value as a single
-character. The constructor accepts an optional string initializer,
-the length of the string must be exactly one character.
-\end{classdesc*}
-
-\begin{classdesc*}{c_char_p}
-Represents the C char * datatype, which must be a pointer to a
-zero-terminated string. The constructor accepts an integer
-address, or a string.
-\end{classdesc*}
-
-\begin{classdesc*}{c_double}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_float}
-Represents the C double datatype. The constructor accepts an
-optional float initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int}
-Represents the C signed int datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias to
-\class{c{\_}long}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int8}
-Represents the C 8-bit \code{signed int} datatype. Usually an alias for
-\class{c{\_}byte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int16}
-Represents the C 16-bit signed int datatype. Usually an alias for
-\class{c{\_}short}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int32}
-Represents the C 32-bit signed int datatype. Usually an alias for
-\class{c{\_}int}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_int64}
-Represents the C 64-bit \code{signed int} datatype. Usually an alias
-for \class{c{\_}longlong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_long}
-Represents the C \code{signed long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_longlong}
-Represents the C \code{signed long long} datatype. The constructor accepts
-an optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_short}
-Represents the C \code{signed short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_size_t}
-Represents the C \code{size{\_}t} datatype.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ubyte}
-Represents the C \code{unsigned char} datatype, it interprets the
-value as small integer. The constructor accepts an optional
-integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint}
-Represents the C \code{unsigned int} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done. On
-platforms where \code{sizeof(int) == sizeof(long)} it is an alias for
-\class{c{\_}ulong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint8}
-Represents the C 8-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ubyte}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint16}
-Represents the C 16-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ushort}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint32}
-Represents the C 32-bit unsigned int datatype. Usually an alias for
-\class{c{\_}uint}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_uint64}
-Represents the C 64-bit unsigned int datatype. Usually an alias for
-\class{c{\_}ulonglong}.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulong}
-Represents the C \code{unsigned long} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ulonglong}
-Represents the C \code{unsigned long long} datatype. The constructor
-accepts an optional integer initializer; no overflow checking is
-done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_ushort}
-Represents the C \code{unsigned short} datatype. The constructor accepts an
-optional integer initializer; no overflow checking is done.
-\end{classdesc*}
-
-\begin{classdesc*}{c_void_p}
-Represents the C \code{void *} type. The value is represented as
-integer. The constructor accepts an optional integer initializer.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar}
-Represents the C \code{wchar{\_}t} datatype, and interprets the value as a
-single character unicode string. The constructor accepts an
-optional string initializer, the length of the string must be
-exactly one character.
-\end{classdesc*}
-
-\begin{classdesc*}{c_wchar_p}
-Represents the C \code{wchar{\_}t *} datatype, which must be a pointer to
-a zero-terminated wide character string. The constructor accepts
-an integer address, or a string.
-\end{classdesc*}
-
-\begin{classdesc*}{HRESULT}
-Windows only: Represents a \class{HRESULT} value, which contains success
-or error information for a function or method call.
-\end{classdesc*}
-
-
-\subsubsection{structured data types\label{ctypes-structured-data-types}}
-
-\begin{classdesc}{Union}{*args, **kw}
-Abstract base class for unions in native byte order.
-\end{classdesc}
-
-\begin{classdesc}{BigEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{big endian} byte order.
-\end{classdesc}
-
-\begin{classdesc}{LittleEndianStructure}{*args, **kw}
-Abstract base class for structures in \emph{little endian} byte order.
-\end{classdesc}
-
-Structures with non-native byte order cannot contain pointer type
-fields, or any other data types containing pointer type fields.
-
-\begin{classdesc}{Structure}{*args, **kw}
-Abstract base class for structures in \emph{native} byte order.
-\end{classdesc}
-
-Concrete structure and union types must be created by subclassing one
-of these types, and at least define a \member{{\_}fields{\_}} class variable.
-\code{ctypes} will create descriptors which allow reading and writing the
-fields by direct attribute accesses. These are the
-
-\begin{memberdesc}{_fields_}
-A sequence defining the structure fields. The items must be
-2-tuples or 3-tuples. The first item is the name of the field,
-the second item specifies the type of the field; it can be any
-ctypes data type.
-
-For integer type fields, a third optional item can be given. It
-must be a small positive integer defining the bit width of the
-field.
-
-Field names must be unique within one structure or union. This is
-not checked, only one field can be accessed when names are
-repeated.
-
-It is possible to define the \member{{\_}fields{\_}} class variable \emph{after}
-the class statement that defines the Structure subclass, this
-allows to create data types that directly or indirectly reference
-themselves:
-\begin{verbatim}
-class List(Structure):
- pass
-List._fields_ = [("pnext", POINTER(List)),
- ...
- ]
-\end{verbatim}
-
-The \member{{\_}fields{\_}} class variable must, however, be defined before
-the type is first used (an instance is created, \code{sizeof()} is
-called on it, and so on). Later assignments to the \member{{\_}fields{\_}}
-class variable will raise an AttributeError.
-
-Structure and union subclass constructors accept both positional
-and named arguments. Positional arguments are used to initialize
-the fields in the same order as they appear in the \member{{\_}fields{\_}}
-definition, named arguments are used to initialize the fields with
-the corresponding name.
-
-It is possible to defined sub-subclasses of structure types, they
-inherit the fields of the base class plus the \member{{\_}fields{\_}} defined
-in the sub-subclass, if any.
-\end{memberdesc}
-
-\begin{memberdesc}{_pack_}
-An optional small integer that allows to override the alignment of
-structure fields in the instance. \member{{\_}pack{\_}} must already be
-defined when \member{{\_}fields{\_}} is assigned, otherwise it will have no
-effect.
-\end{memberdesc}
-
-\begin{memberdesc}{_anonymous_}
-An optional sequence that lists the names of unnamed (anonymous)
-fields. \code{{\_}anonymous{\_}} must be already defined when \member{{\_}fields{\_}}
-is assigned, otherwise it will have no effect.
-
-The fields listed in this variable must be structure or union type
-fields. \code{ctypes} will create descriptors in the structure type
-that allows to access the nested fields directly, without the need
-to create the structure or union field.
-
-Here is an example type (Windows):
-\begin{verbatim}
-class _U(Union):
- _fields_ = [("lptdesc", POINTER(TYPEDESC)),
- ("lpadesc", POINTER(ARRAYDESC)),
- ("hreftype", HREFTYPE)]
-
-class TYPEDESC(Structure):
- _fields_ = [("u", _U),
- ("vt", VARTYPE)]
-
- _anonymous_ = ("u",)
-\end{verbatim}
-
-The \code{TYPEDESC} structure describes a COM data type, the \code{vt}
-field specifies which one of the union fields is valid. Since the
-\code{u} field is defined as anonymous field, it is now possible to
-access the members directly off the TYPEDESC instance.
-\code{td.lptdesc} and \code{td.u.lptdesc} are equivalent, but the former
-is faster since it does not need to create a temporary \code{{\_}U}
-instance:
-\begin{verbatim}
-td = TYPEDESC()
-td.vt = VT_PTR
-td.lptdesc = POINTER(some_type)
-td.u.lptdesc = POINTER(some_type)
-\end{verbatim}
-\end{memberdesc}
-
-It is possible to defined sub-subclasses of structures, they inherit
-the fields of the base class. If the subclass definition has a
-separate``{\_}fields{\_}`` variable, the fields specified in this are
-appended to the fields of the base class.
-
More information about the Python-checkins
mailing list