mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-30 12:21:51 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 9

Tutorial:

Browse source 
Clarify somewhat how parameters are passed to functions
    (especially explain what integer means).

    Correct the table - Python integers and longs can both be used.
    Further clarification to the table comparing ctypes types, Python
    types, and C types.

Reference:

    Replace integer by C ``int`` where it makes sense.
This commit is contained in:
Thomas Heller 2006-08-16 18:02:11 +00:00
parent c13324e313
commit f5af05a211
1 changed files with 48 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

77
Doc/lib/libctypes.tex
View file

@ -199,8 +199,13 @@ WindowsError: exception: access violation reading 0x00000020
There are, however, enough ways to crash Python with \code{ctypes}, so There are, however, enough ways to crash Python with \code{ctypes}, so
you should be careful anyway. you should be careful anyway.
Python integers, strings and unicode strings are the only objects that \code{None}, integers, longs, byte strings and unicode strings are the
can directly be used as parameters in these function calls. only native Python objects that can directly be used as parameters in
these function calls. \code{None} is passed as a C \code{NULL} pointer,
byte strings and unicode strings are passed as pointer to the memory
block that contains their data (\code{char *} or \code{wchar{\_}t *}). Python
integers and Python longs are passed as the platforms default C
\code{int} type, their value is masked to fit into the C type.
Before we move on calling functions with other parameter types, we Before we move on calling functions with other parameter types, we
have to learn more about \code{ctypes} data types. have to learn more about \code{ctypes} data types.
@ -227,7 +232,18 @@ Python type
\code{char} \code{char}
} }
{ {
character 1-character
string
}
\lineiii{
\class{c{\_}wchar}
}
{
\code{wchar{\_}t}
}
{
1-character
unicode string
} }
\lineiii{ \lineiii{
\class{c{\_}byte} \class{c{\_}byte}
@ -236,7 +252,7 @@ character
\code{char} \code{char}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}ubyte} \class{c{\_}ubyte}
@ -245,7 +261,7 @@ integer
\code{unsigned char} \code{unsigned char}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}short} \class{c{\_}short}
@ -254,7 +270,7 @@ integer
\code{short} \code{short}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}ushort} \class{c{\_}ushort}
@ -263,7 +279,7 @@ integer
\code{unsigned short} \code{unsigned short}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}int} \class{c{\_}int}
@ -272,7 +288,7 @@ integer
\code{int} \code{int}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}uint} \class{c{\_}uint}
@ -281,7 +297,7 @@ integer
\code{unsigned int} \code{unsigned int}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}long} \class{c{\_}long}
@ -290,7 +306,7 @@ integer
\code{long} \code{long}
} }
{ {
integer int/long
} }
\lineiii{ \lineiii{
\class{c{\_}ulong} \class{c{\_}ulong}
@ -299,7 +315,7 @@ integer
\code{unsigned long} \code{unsigned long}
} }
{ {
long int/long
} }
\lineiii{ \lineiii{
\class{c{\_}longlong} \class{c{\_}longlong}
@ -309,7 +325,7 @@ long
\code{long long} \code{long long}
} }
{ {
long int/long
} }
\lineiii{ \lineiii{
\class{c{\_}ulonglong} \class{c{\_}ulonglong}
@ -319,7 +335,7 @@ long
\code{unsigned long long} \code{unsigned long long}
} }
{ {
long int/long
} }
\lineiii{ \lineiii{
\class{c{\_}float} \class{c{\_}float}
@ -368,8 +384,8 @@ unicode or
\code{void *} \code{void *}
} }
{ {
integer or int/long
\code{None} or \code{None}
} }
\end{tableiii} \end{tableiii}
\end{quote} \end{quote}
@ -554,11 +570,11 @@ the \member{{\_}as{\_}parameter{\_}} attribute.
\subsubsection{Return types\label{ctypes-return-types}} \subsubsection{Return types\label{ctypes-return-types}}
By default functions are assumed to return integers. Other return By default functions are assumed to return the C \code{int} type. Other
types can be specified by setting the \member{restype} attribute of the return types can be specified by setting the \member{restype} attribute of
function object. the function object.
Here is a more advanced example, it uses the strchr function, which Here is a more advanced example, it uses the \code{strchr} function, which
expects a string pointer and a char, and returns a pointer to a expects a string pointer and a char, and returns a pointer to a
string: string:
\begin{verbatim} \begin{verbatim}
@ -1611,8 +1627,8 @@ library object is available:
\begin{datadescni}{pythonapi} \begin{datadescni}{pythonapi}
An instance of \class{PyDLL} that exposes Python C api functions as An instance of \class{PyDLL} that exposes Python C api functions as
attributes. Note that all these functions are assumed to return attributes. Note that all these functions are assumed to return C
integers, which is of course not always the truth, so you have to \code{int}, which is of course not always the truth, so you have to
assign the correct \member{restype} attribute to use these functions. assign the correct \member{restype} attribute to use these functions.
\end{datadescni} \end{datadescni}
@ -1642,8 +1658,8 @@ function. Use \code{None} for \code{void} a function not returning
anything. anything.
It is possible to assign a callable Python object that is not a It is possible to assign a callable Python object that is not a
ctypes type, in this case the function is assumed to return an ctypes type, in this case the function is assumed to return a
integer, and the callable will be called with this integer, C \code{int}, and the callable will be called with this integer,
allowing to do further processing or error checking. Using this allowing to do further processing or error checking. Using this
is deprecated, for more flexible postprocessing or error checking is deprecated, for more flexible postprocessing or error checking
use a ctypes data type as \member{restype} and assign a callable to the use a ctypes data type as \member{restype} and assign a callable to the
@ -2283,9 +2299,12 @@ Windows only: Represents a \class{HRESULT} value, which contains success
or error information for a function or method call. or error information for a function or method call.
\end{classdesc*} \end{classdesc*}
\begin{classdesc*}{py_object} \code{py{\_}object} : classdesc*
Represents the C \code{PyObject *} datatype. \begin{quote}
\end{classdesc*}
Represents the C \code{PyObject *} datatype. Calling this with an
without an argument creates a \code{NULL} \code{PyObject *} pointer.
\end{quote}
The \code{ctypes.wintypes} module provides quite some other Windows The \code{ctypes.wintypes} module provides quite some other Windows
specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}. specific data types, for example \code{HWND}, \code{WPARAM}, or \code{DWORD}.
@ -2324,9 +2343,9 @@ A sequence defining the structure fields. The items must be
the second item specifies the type of the field; it can be any the second item specifies the type of the field; it can be any
ctypes data type. ctypes data type.
For integer type fields, a third optional item can be given. It For integer type fields like \class{c{\_}int}, a third optional item can
must be a small positive integer defining the bit width of the be given. It must be a small positive integer defining the bit
field. width of the field.
Field names must be unique within one structure or union. This is Field names must be unique within one structure or union. This is
not checked, only one field can be accessed when names are not checked, only one field can be accessed when names are