kea/src/lib/dns/python

This is an implementation of the python wrappers for isc::dns.

When compiled the module is called pydnspp. If we
decide to always need it we can add a default import under
lib/python/isc.

To use it from the source tree, you must add src/lib/dns/python/.libs
to your PYTHONPATH environment variable. Within python you can then use
> import pydnspp
> rrc = pydnspp.RRClass("IN")
etc.

Notes:

this implementation is not a complete 1-to-1 mapping of the C++ API;
some of the functionality is not needed the way we use it in Python.

For instance, we did not implement the buffer classes;
everywhere in the API where buffers are used, you can pass a bytearray
object.

We also (currently) left out some 'lowlevel' wrappers, for instance for
specific Rdata types.

If you have specific functionality you do need, please ask for it and we
will add it.

The 'main' module is defined in pydnspp.cc.
There is a pydnspp_common.[cc|h] for helper functions.

Implementation notes:

Writing wrappers for a lot of classes is mostly a case of repetition.
There are a lot of things one must do, and that is why nearly everyone
immediately and continually has the urge to make generators for this.

We have added a little more documentation than is strictly necessary to
rrclass.h, for reference to new readers.

To keep it maintainable as the original API changes, we use two
techniques;

1. Full unittests. Or at least as full as possible. These unit tests
test the *wrapper* code, not necessarily the underlying c++ code,
which has its own unit tests. There is of course some overlap.
2. Structure. I have tried to structure the wrapper files as much as
possible, see below.

Structure:

Since we are moving a lot of wrappers into one module, the specific
classes are split over several files, each one having the name of the
original header file they are wrapping (e.g. the wrapper for name.h
becomes name_python.cc).

At the top we first declare any exceptions, constants, and enums. These
are all called po_ (the actual python name will be set once
they are added to the module in the module inialization function).

Each class needs a struct that contains a pointer to an instance of the
object (and any helper data). We call these structs s_.

Then we declare (but not define!) all methods we will export to
python. These are named _.

We will also need an _init and _destroy function for all of these.

After the function declarations we define the method array; this
contains the name of the methods as they appear in python, the wrapping
function here, and documentation strings.

Next is the type description; this is used for the wrapper code to
convert native classes from and to python objects, and defines
type-specific pointers (for instance to the method table mentioned above,
but also to a __str__ function should one be defined, how the object
should behave when it is used as a Sequence, etc.). For most classes,
almost all values here shall be NULL.
This has the name _type.

After that we define the exported functions we defined earlier. In some
cases these need the type we just defined, and the type needed the
function names, so for consistency, all functions are defined after,
but declared before the type.

This is repeated for every class we export.

Finally we define the function to add the class, constants, exceptions,
and enums to the module. This function is called from the init function
in pydnspp.cc, has the name
initModulePart_, returns a boolean
(true on success, false on failure), and takes the module as a
PyObject*. There is a convenience function called addClassVariable to
add constants and enums to classes.