Trying it out¶
This is a basic guide to try cppyy and see whether it works for you. Large code bases will benefit from more advanced features such as pythonizations for a cleaner interface to clients; precompiled modules for faster parsing and reduced memory usage; “dictionaries” to package locations and manage dependencies; and mapping files for automatic, lazy, loading. You can, however, get very far with just the basics and it may even be completely sufficient for small packages with fewer classes.
cppyy works by parsing C++ definitions through
cling, generating tiny
wrapper codes to honor compile-time features and create standardized
interfaces, then compiling/linking those wrappers with the
It thus requires only those two ingredients: C++ definitions and
All cppyy uses, the basic and the more advanced, are variations on the
theme of bringing these two together at the point of use.
Definitions typically live in header files and symbols in libraries.
Headers can be loaded with
cppyy.include and libraries with the
Loading the header is sufficient to start exploring, with
starting point of all things C++, while the linker symbols are only needed at
the point of first use.
Here is an example using the zlib library, which is likely available on your system:
>>> import cppyy >>> cppyy.include('zlib.h') # bring in C++ definitions >>> cppyy.load_library('libz') # load linker symbols >>> cppyy.gbl.zlibVersion() # use a zlib API '1.2.11' >>>
Since header files can include other header files, it is easy to aggregate
all relevant ones into a single header to include.
If there are project-specific include paths, you can add those paths through
If a header is C-only and not set for use with C++, use
extern "C" around the header.
Library files can be aggregated by linking all relevant ones to a single
library to load.
Using the linker for this purpose allows regular system features such as
rpath and envars such as
LD_LIBRARY_PATH to be applied as usual.
Note that any mechanism that exposes the library symbols will work.
For example, you could also use the standard module
ctypes.CDLL with the
To explore, start from
cppyy.gbl to access your namespaces, classes,
functions, etc., etc. directly; or use python’s
dir (or tab-completion)
to see what is available.
help to see list the methods and data members of classes and
see the interfaces of functions.
Now try this out for some of your own headers, libraries, and APIs!