ctypes-commit Mailing List for ctypes (Page 75)

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/ctypes/ctypes/sandbox/tools/codegen
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18755

Added Files:
	make.bat README.txt 
Log Message:
Some docs for the code generator.

--- NEW FILE: make.bat ---
@echo off
setlocal
set FLAGS=-s -g -t --stylesheet=default.css
py24 \python24\Scripts\rst2html.py %FLAGS% README.txt README.html
--- NEW FILE: README.txt ---
===============================
 README: ctypes code generation
===============================

.. _REST quickref: http://docutils.sourceforge.net/docs/user/rst/quickstart.html

This document describes the ctypes code generator.  The generator
converts declarations in C header files into executable Python code:
enums, structs, unions, function declarations, and preprocessor
definitions.

The ability to convert preprocessor definitions allows to use the code
generator as an improved version of the ``Tools/Scripts/h2py.py`` script
included with Python itself.

.. contents::

Overview
========

Creating wrappers for C header file(s) is a two step process.  First,
the ``h2xml.py`` script runs gccxml_ over the include file(s),
creating a XML file containing declarations and definitions.  Second,
the ``xml2py.py`` script parses the XML files and creates Python code
containing all or a subset of these definitions.

Python code is generated for C enums, structure, unions, typedefs and
function declarations.  Also included are preprocessor definitions, as
far as they can be converted to valid Python code.

It is possible to filter the output so that only a subset of the
definitions are converted, so it is either possible to generate a
complete Python module wrapping a shared library, or the generator can
be used to create snippets of Python code which can be pasted into a
manually written module.

Requirements
============

gccxml_ is required to parse C header files into an XML description.
**Unfortunately the latest official version 0.6.0 does not fulfill the
ctypes code generator requirements.**

For windows, you can download a prebuild windows installer from `the
ctypes download page`_.  Please note that the installation of gccxml
requires that MSVC 6, 7, or 7.1 is installed on your system, because
it needs the system header files.

If you don't want to or can not install gccxml, you can also download
a prebuilt windows.xml file from the same location.

For other platforms you must `get the development version from CVS`_
and `build gccxml from source`_.

.. _the ctypes download page: http://www.iontof.com/

.. _gccxml: http://www.gccxml.org/

.. _build gccxml from source: http://www.gccxml.org/HTML/Install.html

.. _get the development version from CVS: http://www.gccxml.org/HTML/Download.html

Usage examples
==============

Parse the windows header files (this may take a while)::

       C:\>python h2xml.py windows.h -o windows.xml -q
       C:\>

Generate code for the RECT structure::

       C:\>xml2py.py windows.xml -s RECT
       from ctypes import *
       LONG = c_long
       class tagRECT(Structure):
           pass
       RECT = tagRECT
       tagRECT._fields_ = [
           ('left', c_long),
           ('top', c_long),
           ('right', c_long),
           ('bottom', c_long),
       ]
       assert sizeof(tagRECT) == 16, sizeof(tagRECT)
       assert alignment(tagRECT) == 4, alignment(tagRECT)
       C:\>

Generate the MB_xxx constants, which are flags used for the MessageBox function::

       c:\>python xml2py.py windows.xml -r MB_.*
       # generated by 'xml2py.py'
       # flags 'windows.xml -r MB_.*'
       MB_USERICON = 128
       MB_DEFBUTTON3 = 512
       MB_USEGLYPHCHARS = 4
       MB_ABORTRETRYIGNORE = 2
       MB_ICONASTERISK = 64
       MB_ICONINFORMATION = MB_ICONASTERISK
       MB_ICONHAND = 16
       MB_ICONERROR = MB_ICONHAND
       MB_ICONEXCLAMATION = 48
       MB_ICONWARNING = MB_ICONEXCLAMATION
       MB_RIGHT = 524288
       MB_SYSTEMMODAL = 4096
       MB_ICONQUESTION = 32
       MB_APPLMODAL = 0
       MB_OK = 0
       MB_TYPEMASK = 15
       MB_MODEMASK = 12288
       MB_TASKMODAL = 8192
       MB_OKCANCEL = 1
       MB_RETRYCANCEL = 5
       MB_DEFAULT_DESKTOP_ONLY = 131072
       MB_RTLREADING = 1048576
       MB_PRECOMPOSED = 1
       MB_DEFBUTTON1 = 0
       MB_DEFMASK = 3840
       MB_DEFBUTTON2 = 256
       MB_YESNOCANCEL = 3
       MB_CANCELTRYCONTINUE = 6
       MB_HELP = 16384
       MB_ICONMASK = 240
       MB_SETFOREGROUND = 65536
       MB_TOPMOST = 262144
       MB_COMPOSITE = 2
       MB_DEFBUTTON4 = 768
       MB_YESNO = 4
       MB_ERR_INVALID_CHARS = 8
       MB_NOFOCUS = 32768
       MB_ICONSTOP = MB_ICONHAND
       MB_MISCMASK = 49152
       C:\>

Generate code for the RegisterClass function, please note how this
pulls in a lot of types::

       C:\>python xml2py.py windows.xml -w -s RegisterClass -d
       # generated by 'xml2py'
       # flags 'windows.xml -w -s RegisterClass'
       from ctypes import *
       from ctypes import decorators

       WORD = c_ushort
       ATOM = WORD
       class tagWNDCLASSA(Structure):
           pass
       WNDCLASSA = tagWNDCLASSA
       user32 = CDLL('user32')

       @ decorators.stdcall(ATOM, user32, [POINTER(WNDCLASSA)])
       def RegisterClassA(p1):
           return RegisterClassA._api_(p1)

       RegisterClass = RegisterClassA
       UINT = c_uint
       LONG_PTR = c_long
       LRESULT = LONG_PTR
       WNDPROC = WINFUNCTYPE(LRESULT, c_void_p, c_uint, c_uint, c_long)
       PVOID = c_void_p
       HANDLE = PVOID
       HINSTANCE = HANDLE
       HICON = HANDLE
       HCURSOR = HICON
       HBRUSH = HANDLE
       CHAR = c_char
       LPCSTR = POINTER(CHAR)
       tagWNDCLASSA._fields_ = [
           ('style', UINT),
           ('lpfnWndProc', WNDPROC),
           ('cbClsExtra', c_int),
           ('cbWndExtra', c_int),
           ('hInstance', HINSTANCE),
           ('hIcon', HICON),
           ('hCursor', HCURSOR),
           ('hbrBackground', HBRUSH),
           ('lpszMenuName', LPCSTR),
           ('lpszClassName', LPCSTR),
       ]
       assert sizeof(tagWNDCLASSA) == 40, sizeof(tagWNDCLASSA)
       assert alignment(tagWNDCLASSA) == 4, alignment(tagWNDCLASSA)

Create a Python module ``win_lean.py`` containing wrappers for the
'lean' windows api, that this creates a fairly large file::

    C:\>python h2xml.py windows.h -D WIN32_LEAN_AND_MEAN -D NO_STRICT -o win_lean.xml -q
    C:\>python xml2py.py win_lean.xml -w -o win_lean.py

Create a Python module ``SDL.py`` containing wrappers for the SDL
library.  To work around a problem gccxml has with a certain construct
in the SDL header files, you must define the SDLCALL macro to an empty
value::

    C:\>python h2xml.py SDL.h -I SDL\include -D SDLCALL= -o SDL.xml -q
    C:\>python xml2py.py SDL.xml -o SDL.py -l SDL.dll
    C:\>

The h2xml.py script
===================

``h2xml.py`` lets you specify the names of the header files to parse,
the name of the XML output file, and a few options which are passed to
gccxml.  The ``-D``, ``-E``, and ``-I`` flags may occur several times.

``-h, --help``

   Print a short usage summary and exit.

``-q, --quiet``

   Run in quiet mode.  The default mode is verbose, ``h2xml.py`` prints
   what it is currently doing.

``-D name[=value]``

   This flag defines a preprocessor name.

``-U name``

   This flag undefines a preprocessor name.

``-I directory``

   This flag defines an additional include directory.

``-o xmlfile``

   This flag specifies name and path of the XML output file.

The xml2py.py script
====================

``-h, --help``

   Print a short usage summary and exit.

``-d``

   Use Python 2.4 decorators for wrapped functions.

``-k[d][e][f][m][s][t]``

   Specifies the kind of types to include in the output:

   d = simple preprocessor definitions: #define <identifier> <identifier>

   e = enumerations

   f = function declarations

   m = preprocessor macros taking parameters: #define <ident>(parameters) something

   s = structures and unions

   t = typedefs

``-l sharedlib``

   specify shared library to search for exported functions.

``-m module``

   specifies a Python module containing symbols that will be imported
   instead of generated.

``-o outputfile``

   name of the output file containing Python code.  If not specified,
   the code is printed to standard output.

``-r regular_expression``

   regular expression specifying names of symbols to include.

``-s symbol``

   name of symbol to include.

``-v``

   verbose mode: prints a short summary of types generated.

``-w``

   windows only: add all standard windows dlls to the list of shared
   libraries searched for functions.

Note that specifying the ``-k``, ``-s``, and ``-r`` flags create a
start set of type declarations, the generated code, however, may also
contain other types.  If, for example, the code for an external
function is generated, code for the argument and return types is also
needed.

Also note that code for function declarations is only created when
xml2py.py can locate the function in one of the shared libraries
specified with -l or -w.

Project Files & Directories
===========================

* README.txt: You're reading it.

Getting Help
============
If you have questions or need assistance with ctypes or
the code generator, please `post a message`_ to the `ctypes-users
mailing list`.

.. _post a message: mailto:cty...@li...
.. _ctypes-users mailing list:
   http://lists.sourceforge.net/lists/listinfo/ctypes-users

..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   compile-command: "make"
   End:

2004	Jan	Feb	Mar	Apr (8)	May (90)	Jun (143)	Jul (106)	Aug (94)	Sep (84)	Oct (163)	Nov (60)	Dec (58)
2005	Jan (128)	Feb (79)	Mar (227)	Apr (192)	May (179)	Jun (41)	Jul (53)	Aug (103)	Sep (28)	Oct (38)	Nov (81)	Dec (17)
2006	Jan (184)	Feb (111)	Mar (188)	Apr (67)	May (58)	Jun (123)	Jul (73)	Aug	Sep	Oct (1)	Nov	Dec

ctypes-commit Mailing List for ctypes (Page 75)

ctypes-commit — CVS checkin messages