[Ns-developers] Status of Python bindings

[Gustavo Carneiro]

2008/5/19 Gustavo Carneiro <gjcarneiro at gmail.com>:

> The PyBindGen API changes are more or less complete:
>
> https://code.launchpad.net/~gjc/pybindgen/trunk<https://code.launchpad.net/%7Egjc/pybindgen/trunk>
>
> If nothing else comes up API-wise, next steps are:
>
>  1. Generate NS-3 API definitions as a single Python file and make it work;
>
>  2. Split the above file into several files, and support local modification
> files;
>
>  3. Figure out issues related to splitting python bindings into a separate
> repository;


=== Facts ===

We should come to a decision regarding how to deploy python bindings after
3.1.

Looking at the obtained result, I see that the ns-3-pybindgen-notracing dist
tarball is 748 KiB, versus the no-python normal tarball which is 720 KiB.
That is, only 4% increase.  If I also add the pybindgen source tree, the
total goes to 800KiB, or 11% increase.  In any case, API definitions in this
new format are much smaller than I had expected.

=== Proposal ===

That being said, I think it will be vastly simpler and less painful if:

 1. Python API definitions are kept in the main ns-3-dev branch;

 2. For logistic reasons, and because pybindgen is an independent project
useful to other people, I would prefer to pull the pybindgen source tree
from a bzr branch hosted in code.launchpad.net, the same way regression
traces are pulled from another branch;

 3. The released ns-3 tarballs would ship both a pybindgen tree and API
definitions.  This means that whoever receives the tarball can:

    a) Build the python bindings easily, only needing Python (>= 2.3) with
Python headers as external dependency;

    b) Add extra API definitions using the simplified pybindgen API (I
already added support for this and an example, missing documentation only).

=== Problems Likely To Occur ===

Problems that may occur regarding python bindings are:

 1. A user that receives the tarball hacks NS-3 away, changing APIs in the
process.  The user will then see a compiler error message in the Python
bindings, which may be blocking her work;

        a) I don't see any magical solution here.  Needs documentation
explaining to the user she needs to update the API definition or disable
python bindings;

 2. A NS-3 developer changes the API (I hope this will become rare!).  If
Python bindings are enabled, they will stop compiling and block further work
until they are fixed.  New we can decide whether Python bindings are enabled
by default in development trees (read: branch checkout):

    a) Python bindings are enabled by default.  This means that developers
that change existing APIs will have to fix the corresponding pybindgen API
definition or comment it out;

    b) Python bindings are disabled by default.  This means that Python
bindings will often not be compilable during development periods, but most
developers are free from worrying about bindings.  Some other developers
will have to do the extra work.
        i) In this case we would need to discuss how to detect developer
trees vs release trees...

Please comment.


>  4. Document the process, adding examples;
>
>  5. Bring the code up to date to ns-3-dev (assuming it is API stable by
> then).
>
>
-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert