Advanced Tutorial¶
The point of xdress is to wrap code. The purpose of xdress is to generate idiomatic wrappers. This tutorial describes some awesome things that you can do with xdress.
NumPy dtypes of Classes & Struct¶
When using stlwrap
, the vector
type actually creates custom
numpy dtypes for the templated type. This works not only on primitive types,
other STL containers (map, set, vector), but also on any custom type that the
type system knows about! Say we have the following run control file, which is
used to wrap a C++ class Joan:
xdressrc.py:
package = "france"
classes = [('Joan', 'france.cpp')]
stlcontainers = [('vector', 'Joan')]
The classes list, with the autodescribe and cythongen plugins, will create
Python wrappers for he Joan class. The stlcontainers will then see that the
vector template is dependent on Joan. This will create and register a dtype
called xd_joan
that you can use with ndarrays. You may then get and set
elements out of this array via the wrapper class that was created with cythongen.
For exmaple:
import numpy as np
from france.dtypes import xd_joan
x = np.zeros(10, dtype=xd_joan)
# A scalar array with dtype xd_joan
x[0]
# A Joan wrapper object with a copy of the 0th element of the array
x[0].item()
Note that the underlying memory is a contiguous block of Joans. The Python wrappers are regenerated on every getitem() call. Thus this is more truly an array of structs, as opposed to a structured array ;).
Importable Type Systems¶
Note
This is only starting to be explored
The TypeSystem
class has a mechanism to save and reload via dump()
and
load()
methods. Furthermore, type system variables by the name ts
in
run control and side car files are all merged together with the default type
system. This allows the users of xdress in project-beta to use
the type system developed in project-alpha with out having to re-expose,
re-register, or re-parse any project-alpha code at all!
This is an import-esque mechanism for acting on the type systems themselves. This should be a huge boon to mutlti-project systems. You can also choose to provide xdress type systems to down stream users and a convenience or favor to them. Only pickle and gzip pickle are currently supported, though others may be forthcoming.