Releases: xdress/xdress
0.4
XDress 0.4 Release Notes
XDress is a numpy-aware automatic wrapper generator for C/C++ written in pure Python.
Currently, xdress may generate Python bindings (via Cython) for C++ classes,
functions, and certain variable types. It also contains idiomatic wrappers for
C++ standard library containers (sets, vectors, maps). In the future, other tools
and bindings will be supported.
The main enabling feature of xdress is a dynamic type system that was designed with
the purpose of API generation in mind.
Release highlights:
- Clang support! All kudos to Geoffrey Irving!
- NumPy dtypes may be created independently of C++ STL vectors
- A complete test suite refactor
- Arbitrary source code locations
- Global run control files
- A plethora of useful bug fixes
This version of xdress is not 100% backwards compatible with previous versions
of xdress. We apologize in the name of progress. It represents ans impressive
245 files changed, 44917 aggregate line insertions (+), and 7893 deletions (-).
Please visit the website for more information: http://xdress.org/
Ask questions on the mailing list: https://groups.google.com/forum/#!forum/xdress
Download the code from GitHub: http://github.com/xdress/xdress
XDress is free & open source (BSD 2-clause license) and requires Python 2.7+,
NumPy 1.5+, Cython 0.19+, and optionally Clang, GCC-XML, pycparser, dOxygen, or lxml.
New Features
Clang Support
Through the herculean efforts of Geoffrey Irving xdress finally has full, first-class
Clang/LLVM support! This is major advancement as it allows xdress to wrap more modern
versions of C++ than GCC-XML can handle. Because of deficiencies in the existing
libclang and Python bindings it was necessary for us to fork libclang for xdress
in the short term. We hope to integrate these changes upstream. Clang
versions 3.2 - 3.4 are supported.
Independent NumPy Dtypes
In previous versions of xdress, to create a dtype of type T the user needed to
declare the desire for a wrapper of an STL vector of type T. These two desires have
now been separated. It is now possible to create a dtype via the dtypes run
control parameter. STL vectors are still wrapped via dtypes. See the dtypes module
for more information.
Shiny New Test Suite
The xdress test suite has been completely revamped to include both unit and
integration tests which are run for all available parsers. The integration tests
are accomplished though two fake projects - cproj and cppproj - on which the xdress
CLI is run. These tests are now fully platform independent, unlike the previous
BASH-based test suite.
Source Paths
Source file paths are now given by either their absolute or relative path. This
allows source code to be located anywhere on the user's file system and enable
the wrapping of dependencies or externally supplied libraries as needed. The run
control parameter sourcedir has been deprecated.
Global Run Control Files
It is sometimes useful to be able to set system-wide run control parameters.
XDress will now search the following files in order of increasing precedence.
$HOME/.xdressrc$HOME/.xdressrc.py$HOME/.config/xdressrc$HOME/.config/xdressrc.py
$HOME is the user's home directory. Settings in the project run control file
take precedence over the values here.
Major Bug Fixes
- Debug file now always written when in debug mode.
- STL sets of custom types now allowed.
- Template parameters now allowed to be enum values.
- Allow classes with no default constructor.
Join in the Fun!
If you are interested in using xdress on your project (and need help), contributing
back to xdress, starting up a development team, or writing your own code generation
plugin tool, please let us know. Participation is very welcome!
Authors
- Anthony Scopatz
- Geoffrey Irving *
- James Casbon *
- Kevin Tew *
- Spencer Lyon
- John Wiggins
- Matt McCormick
- Brad Buran
- Chris Harris *
- Gerald Dalley *
- Micky Latowicki *
- Mike C. Fletcher *
- Robert Schwarz *
An * indicates a first time contributor.
Links
- Homepage - http://xdress.org/
- Mailing List - https://groups.google.com/forum/#!forum/xdress
- GitHub Organization - https://github.com/xdress
0.4-rc1
0.3
XDress 0.3 Release Notes
XDress is an automatic wrapper generator for C/C++ written in pure Python. Currently,
xdress may generate Python bindings (via Cython) for C++ classes, functions, and
certain variable types. It also contains idiomatic wrappers for C++ standard library
containers (sets, vectors, maps). In the future, other tools and bindings will be
supported.
The main enabling feature of xdress is a dynamic type system that was designed with
the purpose of API generation in mind.
Release highlights:
- C++ template class & function support
- Automatic docstring generation via dOxygen
- A complete type system implementation refactor
- Wrapped names may be different than source names,
allowing automatic PEP-8-ification - A plethora of useful bug fixes
Please visit the website for more information: http://xdress.org/
Ask questions on the mailing list: xdress@googlegroups.com
Download the code from GitHub: http://github.com/xdress/xdress
XDress is free & open source (BSD 2-clause license) and requires Python 2.7,
NumPy 1.5+, Cython 0.19+, and optionally GCC-XML, pycparser, dOxygen, and lxml.
New Features
C++ Template Support
The most requested feature following SciPy 2013 was full and complete support
for C++ templates. It is here! Template instantiations are now automatically
discovered, described, and wrapped. The only exception to this is that
template member functions are not automatically discovered due to a defect in
GCC-XML. Template methods must, therefore, be added by hand in a sidecar file.
See the FAQ for more details.
dOxygen Docstrings
A new plugin called xdress.doxygen has been added which automatically
scrapes the source code for documentation using dOxygen. These are then
automatically inserted as docstrings into the wrappers that are generated. These
docstrings follow the numpydoc convention.
Type System Refactor
The type system has undergone a complete reactor to make it more user-friendly
and expose a lot of its internals. Previously, the type system was a collection
of functions and module-level private containers. All of this has been moved into
a new TypeSystem class whose attributes and methods are almost all public.
This enables a number of potentially useful features.
- Type systems may be customized in the xdressrc.py file.
- Type systems may be customized in side car files.
- Type systems can now persist and load themselves. This enables saving
a type system when wrapping one project and loading it in as a dependency
in future projects. - Easier testing
As a consequence, most other parts of xdress must now hold a reference to a type
system object. Before, it was sufficient to import the type system module.
API Named Tuple
A new named tuple class apiname has been added. This allows for a broader
selection of how users can choose to write names in the classes, functions, and
variables list in the run control file. Possible options now include::
from xdress.utils import apiname
classes = [
(srcname, srcfile,),
(srcname, srcfile, tarfile,),
(srcname, srcfile, tarfile, tarname),
[srcname, srcfile, tarfile, tarname],
{'srcname': a, 'srcfile': b, 'tarfile': c, 'tarname': d},
apiname(srcname, srcfile, tarfile, tarname),
]
This allows the target name (ie the name in the wrapper) to be distinct from
the name that is in the C/C++ source code (ie the source name). This is very
useful for customizing APIs because xdress takes care of the mapping for you!
PEP-8 Compliance Plugin
A new plugin called xdress.pep8names has been added which ensures that
all target names for API elements are PEP-8 compliant for that type. If the
target name is not PEP-8 complaint then it converts it to a compliant version
for you. Subversive? That's the point! Functions and variables are converted
to lowercase_with_underscores while classes are converted to CapCase.
Description Filtering Plugin
Sometimes autoall will expose too much. To avoid certain API elements while
still automatically finding other names, the xdress.descfilter plugin allows
you to skip methods, attributes, and types that the you doesn't feel are appropriate
to expose. This is also a useful stop-gap for data types that have not yet been
implemented into the xdress type system.
Tab Completion in BASH
Through the power and magic of the argcomplete package, all arguments and options
for all plugins now have tab-completion enabled in BASH. Install argcomplete
and then add the following lines to your ~/.bashrc file::
# Enable completion for xdress
eval "$(register-python-argcomplete xdress)"
Major Bug Fixes
- Enums and functions pointers were noticeably absent from the GCC-XML describer.
This has been rectified. - Classes and structs are now registered into the type system earlier. This allows
them to be used in other plugins. This includes stlwrap. It is now possible
and easy to create custom numpy dtypes for any struct or C++ class. - Fixed segfaults with custom dtypes
- Fixed build issue when only vectors were present in stlcontainers.
- The global namespace is now correctly represented by None, rather than '::',
when using GCC-XML.
Join in the Fun!
If you are interested in using xdress on your project (and need help), contributing
back to xdress, starting up a development team, or writing your own code generation
plugin tool, please let us know. Participation is very welcome!
Authors
- Anthony Scopatz
- Spencer Lyon
- John Wiggins *
- Matt McCormick *
- Brad Buran
An * indicates a first time contributor.
Links
- Homepage - http://xdress.org/
- Mailing List - xdress@googlegroups.com
- GitHub Organization - https://github.com/xdress
- numpydoc - https://pypi.python.org/pypi/numpydoc
- argcomplete - https://argcomplete.readthedocs.org/en/latest/
v0.3-rc1
0.3-rc2
0.2
XDress 0.2 Release Notes
XDress is an automatic wrapper generator for C/C++ written in pure Python. Currently,
xdress may generate Python bindings (via Cython) for C++ classes, functions, and
certain variable types. It also contains idiomatic wrappers for C++ standard library
containers (sets, vectors, maps). In the future, other tools and bindings will be
supported.
The main enabling feature of xdress is a dynamic type system that was designed with
the purpose of API generation in mind.
Release highlights:
- First class support for C via pycparser.
- Python 3 support, by popular demand!
- A plethora of awesome type system updates, including:
- type matching
- lambda-valued converters
- function pointer support - Easy to use and implement plugin architecture.
Please visit the website for more information: http://xdress.org/
Ask questions on the mailing list: xdress@googlegroups.com
Download the code from GitHub: http://github.com/xdress/xdress
XDress is free & open source (BSD 2-clause license) and requires Python 2.7,
NumPy 1.5+, Cython 0.19+, and optionally GCC-XML, pycparser, and lxml.
New Features
First Class C Support
Wrapping C code is now fully handled through with the optional pycparser.
This means that you don't have to worry about whether or not the GCC-XML
parser will work on your particular bit of code. Furthermore, C structs
and their members are now handled idiomatically. (C++ structs are actually
treated as C++ classes, which means that their are allowed to have
constructors and other C++ concepts not present in C.)
Python 3 Support
The entire code base is built and tested under Python 3.3. This uses the single
code base model, as most development takes pace in Python 2.7. The Cython code
that is generated may be used by both Python 2 & 3.
Type System
The type system has been expanded and hardened to handle additional use cases,
largely motivated by the desire for realistic C support.
A new function pointer (fucntion_pointer) refinement type has been added.
When converting from C to Python, a new function object is created that wraps
the underlying call. For converting from Python to C, a virtual table of
callback functions is constructed that have the same signature of the pointer
but hold a reference to a Python function. The size of the table and thus how
many callbacks you can have before overwriting previous ones, is set by the
max_callbacks key in the extra dictionary in class descriptions. This
defaults to 8.
A new enum refinement type now also comes stock. These may be exposed to Python
in the rc.variables list.
The type system now also comes with basic type matching tools. There is a new
TypeMatcher class, a matches() function, and a singleton MatchAny
that may be used for determining whether a type adheres to a pattern. The
TypeMatcher class itself is immutable and hashable and therefore may be used
anywhere other type elements (tuples, str, int) may be used including as dict
keys! This is helpful for specifying conversions for large groups of types.
Finally, the type system conversion dictionaries now accept callable objects
as values. This was put in to handle templated types where the number of
argument is not in general know beforehand, e.g. enums and function pointers.
The values must be callable with only a single argument -- the type itself.
For example, lambda t: rtnvalue is valid.
Plugins!
XDress is a suite of tools written on top of a type system. Thus the entire
core has been refactored to implement a very nimble and easy plugin system.
The plugin mechanism enables external projects with their own code generators
to easily hook into the xdress tools. Additionally, this allows users to
decide at run time which plugins they want to use.
Mini-FAQ
-
Why not use an existing solution (eg, SWIG)?
Their type systems don't support run-time, user provided refinement types,
and thus are unsuited for verification & validation use cases that often
arise in computational science.Furthermore, they tend to not handle C++ dependent types well (i.e. vector
does not come back as a np.view(..., dtype=T)). -
Why GCC-XML and not Clang's AST?
I tried using Clang's AST (and the remnants of a broken visitor class remain
in the code base). However, the official Clang AST Python bindings lack
support for template argument types. This is a really big deal. Other C++ ASTs
may be supported in the future -- including Clang's. -
I run xdress and it creates these files, now what?!
It is your job to integrate the files created by xdress into your build system.
Join in the Fun!
If you are interested in using xdress on your project (and need help), contributing
back to xdress, starting up a development team, or writing your own code generation
plugin tool on top of the type system and autodescriber, please let us know.
Participation is very welcome!
Authors
Anthony Scopatz <http://scopatz.com/>_- Spencer Lyon *
- Gerald Dalley *
- Alexander Eisenhuth *
An * indicates a first time contributor.
Links
- Homepage - http://xdress.org/
- Mailing List - xdress@googlegroups.com
- GitHub Organization - https://github.com/xdress
- Pycparser - https://pypi.python.org/pypi/pycparser
0.2-rc1
0.1
XDress 0.1 Release Notes
XDress is an automatic wrapper generator for C/C++ written in pure Python. Currently,
xdress may generate Python bindings (via Cython) for C++ classes & functions
and in-memory wrappers for C++ standard library containers (sets, vectors, maps).
In the future, other tools and bindings will be supported.
The main enabling feature of xdress is a dynamic type system that was designed with
the purpose of API generation in mind.
Release highlights:
- Dynamic system for specifying types
- Automatically describes C/C++ APIs from source code with no modifications.
- Python extension module generation (via Cython) from C++ API descriptions
- Python views into C++ STL containers. Vectors are NumPy arrays while maps
and sets have custom collections.MutableMapping and collections.MutableSet
subclasses. - Command line interface to the above tools.
Please visit the website for more information: http://bit.ly/xdress-code
Or grab the code from GitHub: http://github.com/scopatz/xdress
XDress is free & open source (BSD 2-clause license) and requires Python 2.7,
NumPy 1.5+, PyTables 2.1+, Cython 0.18+, GCC-XML, and lxml.
New Features
Type System
This module provides a suite of tools for denoting, describing, and converting
between various data types and the types coming from various systems. This is
achieved by providing canonical abstractions of various kinds of types:
- Base types (int, str, float, non-templated classes)
- Refined types (even or odd ints, strings containing the letter 'a')
- Dependent types (templates such arrays, maps, sets, vectors)
All types are known by their name (a string identifier) and may be aliased with
other names. However, the string id of a type is not sufficient to fully describe
most types. The system here implements a canonical form for all kinds of types.
This canonical form is itself hashable, being comprised only of strings, ints,
and tuples.
Descriptions
A key component of API wrapper generation is having a a top-level, abstract
representation of the software that is being wrapped. In C++ there are three
basic constructs which may be wrapped: variables, functions, and classes.
Here we restrict ourselves to wrapping classes and functions, though variables
may be added in the future.
The abstract representation of a C++ class is known as a description (abbr. desc).
This description is simply a Python dictionary with a specific structure.
This structure makes heavy use of the type system to declare the types of all needed
parameters.
Mini-FAQ
-
Why not use an existing solution (eg, SWIG)?
Their type systems don't support run-time, user provided refinement types,
and thus are unsuited for verification & validation use cases that often
arise in computational science.Furthermore, they tend to not handle C++ dependent types well (i.e. vector
does not come back as a np.view(..., dtype=T)). -
Why GCC-XML and not Clang's AST?
I tried using Clang's AST (and the remnants of a broken visitor class remain
in the code base). However, the official Clang AST Python bindings lack
support for template argument types. This is a really big deal. Other C++ ASTs
may be supported in the future -- including Clang's. -
I run xdress and it creates these files, now what?!
It is your job to integrate the files created by xdress into your build system.
Join in the Fun!
If you are interested in using xdress on your project (and need help), contributing
back to xdress, starting up a development team, or writing your own code generation
front end tool on top of the type system and autodescriber, please let me know.
Participation is very welcome!
Authors
XDress was written by Anthony Scopatz, who had many
type system discussions with John Bachan over coffee at the Div school, and was
polished up and released under the encouragement of Christopher Jordan-Squire at
PyCon 2013.