[C++-sig] Re: Presenting a Python embedding tutorial for Boost.Python

[Dirk Gerrits]

David Abrahams wrote:
> Dirk Gerrits <dirk at gerrits.homeip.net> writes:
> 
> 
>>I've finally finished the first draft of the embedding tutorial I was
>>writing for Boost.Python. I guess I underestimated the task, because
>>it took several days longer than I anticipated, but here it is:
>>
>>http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/boost-sandbox/boost-sandbox/libs/python/doc/tutorial/doc/embedding.html
>>
>>Note that I am neither an experienced writer, nor an experienced
>>Pythoneer. Any and all proof reading will be greatly appreciated.
> 
> 
> Thanks very much for your efforts!

Your welcome. I'm just glad I can help a great library become even 
better. :)

> I have several high-level remarks:
> 
> 1. Why spend so much time discussing manual reference-counting, if we
>    have a better solution?

Good point. At the time, I felt it was necessary to understand this to 
understand the difference between 'borrowed' and 'new'. On retrospect, I 
suppose this is not really necessary.

> 2. I notice no use of handle_exception(). Boost.Python code can throw
>    C++ exceptions which correspond to Python exceptions (e.g. when
>    initializing a handle<> from a null pointer), and
>    handle_exception() will translate these back into Python
>    exceptions... which can finally be printed on the console or
>    wherever else you think is appropriate

Well I guess that is because I haven't studied Boost.Python's exception 
facilities in much detail myself. But I agree that this would make a 
good addition. And a description of null_ok would probably be 
appropriate too.

> 3. It was always my intention to help people avoid touching PyObject*s
>    and the Python 'C' API at all.  Are there any obvious C++
>    interfaces that should be added to the library to wrap the
>    boilerplate use of the Python 'C' API I see in your examples?

A noble goal. :) And you've already got dict, list, long, numeric, 
object, str, tuple which covers a great deal of ground. My PyTuple_ 
examples are perhaps ill-chosen because python::tuple can do this much 
easier, but I didn't know what else to demonstrate there.

If I scrap the manual reference counting section though, then I've still 
got the PyRun_String example. The PyRun_ functions are pretty vital for 
embedding and they are not directly covered by Boost.Python AFAIK.

However, adding Boost.Python facilities for the PyRun_ functions 
probably means adding a load of other Python C API facilites as well.

I would like to have something like this in Boost.Python:

object run_python_code(InputIterator begin, InputIterator end);
object run_python_code(String str);

Or, if a python::module was added, perhaps this would be more generic:

object run_python_code(InputIterator begin, InputIterator end, module 
mod = main_module());
object run_python_code(String str, module mod = main_module());

Also, it might be a good idea to wrap Py_Initialize and Py_Finalize in a 
  RAII class?

I'm just not sure where this line of thought will end. It might add a 
lot of functions and classes to Boost.Python.

What do you think?

Dirk Gerrits