« back to all changes in this revision
Viewing changes to Doc/library/ctypes.rst
- browse files at revision 39019
- compare with another revision
- download diff
- download tarball
- view history from revision 39019
- Committer: benjamin.peterson
- Date: 2008-04-25 01:29:10 UTC
- Revision ID: svn-v3-trunk1:6015fed2-1504-0410-9fe1-9d1591cc4771:python%2Ftrunk:62490
reformat some documentation of classes so methods and attributes are under the class directive
- files modified:
- Doc/library/asynchat.rst
added
removed
Doc/library/ctypes.rst
1443
1443
so repeated attribute accesses return the same library each time.
1444
1444
1445
1445
1446
.. method:: LibraryLoader.LoadLibrary(name)
1446
.. method:: LoadLibrary(name)
1447
1447
1448
Load a shared library into the process and return it. This method always
1449
returns a new instance of the library.
1448
Load a shared library into the process and return it. This method always
1449
returns a new instance of the library.
1450
1450
1451
1451
These prefabricated library loaders are available:
1452
1452
1503
1503
1504
1504
Base class for C callable foreign functions.
1505
1505
1506
Instances of foreign functions are also C compatible data types; they represent
1507
C function pointers.
1508
1509
This behavior can be customized by assigning to special attributes of the
1510
foreign function object.
1511
1512
1513
.. attribute:: _FuncPtr.restype
1514
1515
Assign a ctypes type to specify the result type of the foreign function. Use
1516
``None`` for ``void`` a function not returning anything.
1517
1518
It is possible to assign a callable Python object that is not a ctypes type, in
1519
this case the function is assumed to return a C ``int``, and the callable will
1520
be called with this integer, allowing to do further processing or error
1521
checking. Using this is deprecated, for more flexible post processing or error
1522
checking use a ctypes data type as :attr:`restype` and assign a callable to the
1523
:attr:`errcheck` attribute.
1524
1525
1526
.. attribute:: _FuncPtr.argtypes
1527
1528
Assign a tuple of ctypes types to specify the argument types that the function
1529
accepts. Functions using the ``stdcall`` calling convention can only be called
1530
with the same number of arguments as the length of this tuple; functions using
1531
the C calling convention accept additional, unspecified arguments as well.
1532
1533
When a foreign function is called, each actual argument is passed to the
1534
:meth:`from_param` class method of the items in the :attr:`argtypes` tuple, this
1535
method allows to adapt the actual argument to an object that the foreign
1536
function accepts. For example, a :class:`c_char_p` item in the :attr:`argtypes`
1537
tuple will convert a unicode string passed as argument into an byte string using
1538
ctypes conversion rules.
1539
1540
New: It is now possible to put items in argtypes which are not ctypes types, but
1541
each item must have a :meth:`from_param` method which returns a value usable as
1542
argument (integer, string, ctypes instance). This allows to define adapters
1543
that can adapt custom objects as function parameters.
1544
1545
1546
.. attribute:: _FuncPtr.errcheck
1547
1548
Assign a Python function or another callable to this attribute. The callable
1549
will be called with three or more arguments:
1506
Instances of foreign functions are also C compatible data types; they
1507
represent C function pointers.
1508
1509
This behavior can be customized by assigning to special attributes of the
1510
foreign function object.
1511
1512
1513
.. attribute:: restype
1514
1515
Assign a ctypes type to specify the result type of the foreign function.
1516
Use ``None`` for ``void`` a function not returning anything.
1517
1518
It is possible to assign a callable Python object that is not a ctypes
1519
type, in this case the function is assumed to return a C ``int``, and the
1520
callable will be called with this integer, allowing to do further
1521
processing or error checking. Using this is deprecated, for more flexible
1522
post processing or error checking use a ctypes data type as
1523
:attr:`restype` and assign a callable to the :attr:`errcheck` attribute.
1524
1525
1526
.. attribute:: argtypes
1527
1528
Assign a tuple of ctypes types to specify the argument types that the
1529
function accepts. Functions using the ``stdcall`` calling convention can
1530
only be called with the same number of arguments as the length of this
1531
tuple; functions using the C calling convention accept additional,
1532
unspecified arguments as well.
1533
1534
When a foreign function is called, each actual argument is passed to the
1535
:meth:`from_param` class method of the items in the :attr:`argtypes`
1536
tuple, this method allows to adapt the actual argument to an object that
1537
the foreign function accepts. For example, a :class:`c_char_p` item in
1538
the :attr:`argtypes` tuple will convert a unicode string passed as
1539
argument into an byte string using ctypes conversion rules.
1540
1541
New: It is now possible to put items in argtypes which are not ctypes
1542
types, but each item must have a :meth:`from_param` method which returns a
1543
value usable as argument (integer, string, ctypes instance). This allows
1544
to define adapters that can adapt custom objects as function parameters.
1545
1546
1547
.. attribute:: errcheck
1548
1549
Assign a Python function or another callable to this attribute. The
1550
callable will be called with three or more arguments:
1550
1551
1551
1552
1552
1553
.. function:: callable(result, func, arguments)
1561
1562
``arguments`` is a tuple containing the parameters originally passed to the
1562
1563
function call, this allows to specialize the behavior on the arguments used.
1563
1564
1564
The object that this function returns will be returned from the foreign function
1565
call, but it can also check the result value and raise an exception if the
1566
foreign function call failed.
1565
The object that this function returns will be returned from the foreign
1566
function call, but it can also check the result value and raise an exception
1567
if the foreign function call failed.
1567
1568
1568
1569
1569
1570
.. exception:: ArgumentError()
1945
1946
:attr:`_objects`; this contains other Python objects that need to be kept alive
1946
1947
in case the memory block contains pointers.
1947
1948
1948
Common methods of ctypes data types, these are all class methods (to be exact,
1949
they are methods of the :term:`metaclass`):
1950
1951
1952
.. method:: _CData.from_address(address)
1953
1954
This method returns a ctypes type instance using the memory specified by address
1955
which must be an integer.
1956
1957
1958
.. method:: _CData.from_param(obj)
1959
1960
This method adapts obj to a ctypes type. It is called with the actual object
1961
used in a foreign function call, when the type is present in the foreign
1962
functions :attr:`argtypes` tuple; it must return an object that can be used as
1963
function call parameter.
1964
1965
All ctypes data types have a default implementation of this classmethod,
1966
normally it returns ``obj`` if that is an instance of the type. Some types
1967
accept other objects as well.
1968
1969
1970
.. method:: _CData.in_dll(library, name)
1971
1972
This method returns a ctypes type instance exported by a shared library. *name*
1973
is the name of the symbol that exports the data, *library* is the loaded shared
1974
library.
1975
1976
Common instance variables of ctypes data types:
1977
1978
1979
.. attribute:: _CData._b_base_
1980
1981
Sometimes ctypes data instances do not own the memory block they contain,
1982
instead they share part of the memory block of a base object. The
1983
:attr:`_b_base_` read-only member is the root ctypes object that owns the memory
1984
block.
1985
1986
1987
.. attribute:: _CData._b_needsfree_
1988
1989
This read-only variable is true when the ctypes data instance has allocated the
1990
memory block itself, false otherwise.
1991
1992
1993
.. attribute:: _CData._objects
1994
1995
This member is either ``None`` or a dictionary containing Python objects that
1996
need to be kept alive so that the memory block contents is kept valid. This
1997
object is only exposed for debugging; never modify the contents of this
1998
dictionary.
1949
Common methods of ctypes data types, these are all class methods (to be
1950
exact, they are methods of the :term:`metaclass`):
1951
1952
1953
.. method:: from_address(address)
1954
1955
This method returns a ctypes type instance using the memory specified by
1956
address which must be an integer.
1957
1958
1959
.. method:: from_param(obj)
1960
1961
This method adapts obj to a ctypes type. It is called with the actual
1962
object used in a foreign function call, when the type is present in the
1963
foreign functions :attr:`argtypes` tuple; it must return an object that
1964
can be used as function call parameter.
1965
1966
All ctypes data types have a default implementation of this classmethod,
1967
normally it returns ``obj`` if that is an instance of the type. Some
1968
types accept other objects as well.
1969
1970
1971
.. method:: in_dll(library, name)
1972
1973
This method returns a ctypes type instance exported by a shared
1974
library. *name* is the name of the symbol that exports the data, *library*
1975
is the loaded shared library.
1976
1977
1978
Common instance variables of ctypes data types:
1979
1980
1981
.. attribute:: _b_base_
1982
1983
Sometimes ctypes data instances do not own the memory block they contain,
1984
instead they share part of the memory block of a base object. The
1985
:attr:`_b_base_` read-only member is the root ctypes object that owns the
1986
memory block.
1987
1988
1989
.. attribute:: _b_needsfree_
1990
1991
This read-only variable is true when the ctypes data instance has
1992
allocated the memory block itself, false otherwise.
1993
1994
1995
.. attribute:: _objects
1996
1997
This member is either ``None`` or a dictionary containing Python objects
1998
that need to be kept alive so that the memory block contents is kept
1999
valid. This object is only exposed for debugging; never modify the
2000
contents of this dictionary.
1999
2001
2000
2002
2001
2003
.. _ctypes-fundamental-data-types-2:
2015
2017
ctypes data types that are not and do not contain pointers can
2016
2018
now be pickled.
2017
2019
2018
Instances have a single attribute:
2019
2020
2021
.. attribute:: _SimpleCData.value
2022
2023
This attribute contains the actual value of the instance. For integer and
2024
pointer types, it is an integer, for character types, it is a single character
2025
string, for character pointer types it is a Python string or unicode string.
2026
2027
When the ``value`` attribute is retrieved from a ctypes instance, usually a new
2028
object is returned each time. ``ctypes`` does *not* implement original object
2029
return, always a new object is constructed. The same is true for all other
2030
ctypes object instances.
2020
Instances have a single attribute:
2021
2022
2023
.. attribute:: value
2024
2025
This attribute contains the actual value of the instance. For integer and
2026
pointer types, it is an integer, for character types, it is a single
2027
character string, for character pointer types it is a Python string or
2028
unicode string.
2029
2030
When the ``value`` attribute is retrieved from a ctypes instance, usually
2031
a new object is returned each time. ``ctypes`` does *not* implement
2032
original object return, always a new object is constructed. The same is
2033
true for all other ctypes object instances.
2031
2034
2032
2035
Fundamental data types, when returned as foreign function call results, or, for
2033
2036
example, by retrieving structure field members or array items, are transparently
2265
2268
2266
2269
Abstract base class for structures in *native* byte order.
2267
2270
2268
Concrete structure and union types must be created by subclassing one of these
2269
types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
2270
create :term:`descriptor`\s which allow reading and writing the fields by direct
2271
attribute accesses. These are the
2272
2273
2274
.. attribute:: Structure._fields_
2275
2276
A sequence defining the structure fields. The items must be 2-tuples or
2277
3-tuples. The first item is the name of the field, the second item specifies
2278
the type of the field; it can be any ctypes data type.
2279
2280
For integer type fields like :class:`c_int`, a third optional item can be given.
2281
It must be a small positive integer defining the bit width of the field.
2282
2283
Field names must be unique within one structure or union. This is not checked,
2284
only one field can be accessed when names are repeated.
2285
2286
It is possible to define the :attr:`_fields_` class variable *after* the class
2287
statement that defines the Structure subclass, this allows to create data types
2288
that directly or indirectly reference themselves::
2289
2290
class List(Structure):
2291
pass
2292
List._fields_ = [("pnext", POINTER(List)),
2293
...
2294
]
2295
2296
The :attr:`_fields_` class variable must, however, be defined before the type is
2297
first used (an instance is created, ``sizeof()`` is called on it, and so on).
2298
Later assignments to the :attr:`_fields_` class variable will raise an
2299
AttributeError.
2300
2301
Structure and union subclass constructors accept both positional and named
2302
arguments. Positional arguments are used to initialize the fields in the same
2303
order as they appear in the :attr:`_fields_` definition, named arguments are
2304
used to initialize the fields with the corresponding name.
2305
2306
It is possible to defined sub-subclasses of structure types, they inherit the
2307
fields of the base class plus the :attr:`_fields_` defined in the sub-subclass,
2308
if any.
2309
2310
2311
.. attribute:: Structure._pack_
2312
2313
An optional small integer that allows to override the alignment of structure
2314
fields in the instance. :attr:`_pack_` must already be defined when
2315
:attr:`_fields_` is assigned, otherwise it will have no effect.
2316
2317
2318
.. attribute:: Structure._anonymous_
2319
2320
An optional sequence that lists the names of unnamed (anonymous) fields.
2321
``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
2322
otherwise it will have no effect.
2323
2324
The fields listed in this variable must be structure or union type fields.
2325
``ctypes`` will create descriptors in the structure type that allows to access
2326
the nested fields directly, without the need to create the structure or union
2327
field.
2328
2329
Here is an example type (Windows)::
2330
2331
class _U(Union):
2332
_fields_ = [("lptdesc", POINTER(TYPEDESC)),
2333
("lpadesc", POINTER(ARRAYDESC)),
2334
("hreftype", HREFTYPE)]
2335
2336
class TYPEDESC(Structure):
2337
_fields_ = [("u", _U),
2338
("vt", VARTYPE)]
2339
2340
_anonymous_ = ("u",)
2341
2342
The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field specifies
2343
which one of the union fields is valid. Since the ``u`` field is defined as
2344
anonymous field, it is now possible to access the members directly off the
2345
TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc`` are equivalent, but the
2346
former is faster since it does not need to create a temporary union instance::
2347
2348
td = TYPEDESC()
2349
td.vt = VT_PTR
2350
td.lptdesc = POINTER(some_type)
2351
td.u.lptdesc = POINTER(some_type)
2271
Concrete structure and union types must be created by subclassing one of these
2272
types, and at least define a :attr:`_fields_` class variable. ``ctypes`` will
2273
create :term:`descriptor`\s which allow reading and writing the fields by direct
2274
attribute accesses. These are the
2275
2276
2277
.. attribute:: _fields_
2278
2279
A sequence defining the structure fields. The items must be 2-tuples or
2280
3-tuples. The first item is the name of the field, the second item
2281
specifies the type of the field; it can be any ctypes data type.
2282
2283
For integer type fields like :class:`c_int`, a third optional item can be
2284
given. It must be a small positive integer defining the bit width of the
2285
field.
2286
2287
Field names must be unique within one structure or union. This is not
2288
checked, only one field can be accessed when names are repeated.
2289
2290
It is possible to define the :attr:`_fields_` class variable *after* the
2291
class statement that defines the Structure subclass, this allows to create
2292
data types that directly or indirectly reference themselves::
2293
2294
class List(Structure):
2295
pass
2296
List._fields_ = [("pnext", POINTER(List)),
2297
...
2298
]
2299
2300
The :attr:`_fields_` class variable must, however, be defined before the
2301
type is first used (an instance is created, ``sizeof()`` is called on it,
2302
and so on). Later assignments to the :attr:`_fields_` class variable will
2303
raise an AttributeError.
2304
2305
Structure and union subclass constructors accept both positional and named
2306
arguments. Positional arguments are used to initialize the fields in the
2307
same order as they appear in the :attr:`_fields_` definition, named
2308
arguments are used to initialize the fields with the corresponding name.
2309
2310
It is possible to defined sub-subclasses of structure types, they inherit
2311
the fields of the base class plus the :attr:`_fields_` defined in the
2312
sub-subclass, if any.
2313
2314
2315
.. attribute:: _pack_
2316
2317
An optional small integer that allows to override the alignment of
2318
structure fields in the instance. :attr:`_pack_` must already be defined
2319
when :attr:`_fields_` is assigned, otherwise it will have no effect.
2320
2321
2322
.. attribute:: _anonymous_
2323
2324
An optional sequence that lists the names of unnamed (anonymous) fields.
2325
``_anonymous_`` must be already defined when :attr:`_fields_` is assigned,
2326
otherwise it will have no effect.
2327
2328
The fields listed in this variable must be structure or union type fields.
2329
``ctypes`` will create descriptors in the structure type that allows to
2330
access the nested fields directly, without the need to create the
2331
structure or union field.
2332
2333
Here is an example type (Windows)::
2334
2335
class _U(Union):
2336
_fields_ = [("lptdesc", POINTER(TYPEDESC)),
2337
("lpadesc", POINTER(ARRAYDESC)),
2338
("hreftype", HREFTYPE)]
2339
2340
class TYPEDESC(Structure):
2341
_fields_ = [("u", _U),
2342
("vt", VARTYPE)]
2343
2344
_anonymous_ = ("u",)
2345
2346
The ``TYPEDESC`` structure describes a COM data type, the ``vt`` field
2347
specifies which one of the union fields is valid. Since the ``u`` field
2348
is defined as anonymous field, it is now possible to access the members
2349
directly off the TYPEDESC instance. ``td.lptdesc`` and ``td.u.lptdesc``
2350
are equivalent, but the former is faster since it does not need to create
2351
a temporary union instance::
2352
2353
td = TYPEDESC()
2354
td.vt = VT_PTR
2355
td.lptdesc = POINTER(some_type)
2356
td.u.lptdesc = POINTER(some_type)
2352
2357
2353
2358
It is possible to defined sub-subclasses of structures, they inherit the fields
2354
2359
of the base class. If the subclass definition has a separate :attr:`_fields_`
Loggerhead is a web-based interface for Breezy
Version: 2.0.1