[C++-sig] Boost.Python

[David Abrahams]

Followups to the C++-sig, please.

"Drumheller, Michael" <michael.drumheller at boeing.com> writes:

> David:
>
>   > a really great facility, and I am excited to try it out. 
>   
>   Thanks; that's always gratifying to hear!
>   
> You're welcome!
>
>   > I have a question though:  In the Tutorial->Embedding section,
>   > http://www.boost.org/libs/python/doc/tutorial/doc/html/python/embedding.html
>   > it says "Currently, Boost.Python does not directly support everything
>   > you'll need when embedding."  However, in other sections, such as the Ref Man page
>   > http://www.boost.org/libs/python/doc/v2/call_method.html, it seems to suggest
>   > that there is very powerful support for calling Python functions/methods etc.
>   > from C++.  
>   >
>   > Are these documents just out of sync, or am I misunderstanding
>   > something?
>   
>   I guess the latter.  Despite that powerful support you mention, there
>   are still gaps in Boost.Python's wrapping of the Python/C API as you
>   can see from the example.
>
> OK, thank you.  I think this is rather a serious doc bug.  

The smallest mistakes can look serious if they lead you down the wrong
path.

> I very nearly dismissed Boost.Python summarily as useless (to me)
> upon reading the Tutorial section.  (This is because my initial
> interest is in calling Python from C++, not building C++
> extensions.)  If you don't mind me going into a little detail, I'd
> like to explain how the documentation appeared to me, in particular
> the browsing sequence that it "led me through":
>
> I started browsing the Boost.Python doc pages, and found at this
> link pretty quickly:
> http://www.boost.org/libs/python/doc/tutorial/doc/html/python/embedding.html.
> (I found it because I first went to
> http://www.boost.org/libs/python/doc/, and there I saw the tutorial
> link
> http://www.boost.org/libs/python/doc/tutorial/doc/html/index.html.
> A tutorial is *always* the first thing I look for, so I went there.)
> I saw the "Embedding" item in the contents.  Clicking there, I saw
> right at the top of the first page the statement "...sometimes you
> may need to do the reverse: call Python code from the C++-side."  So
> I thought "A-ha, this is what I was looking for.  I am definitely in
> the right place."
>
> But when I read the rest of that page, all I saw stuff for eval'ing
> a string or file.  So I thought, "Hmmm, this stuff has not gone very
> far beyond what Python has been able to do forever."

If you can make some _specific_ suggestions about how to reformulate
that page, they'd be greatly appreciated.  I mean, "add this text
here, delete that text, stick a link here to whatever."

> I can't recall how I found the other link
> http://www.boost.org/libs/python/doc/v2/call_method.html, but it
> definitely took more time and resourcefulness on my part than it
> should have.

That might be good, because you shouldn't use it ;-).  The object
interface described at
http://www.boost.org/libs/python/doc/tutorial/doc/html/python/object.html
is much cleaner and generally more effective.

> I think Boost (and maybe Boost Consulting!) might be losing a
> potential user/customer now and then because of this--that is,
> because of the failure of the "Embedding" section to point to all
> the cool "callable" stuff.  

Well, yeah, I agree we could do better.  That said, if a person is
going to dive into the middle of the documentation, they're going to
miss some things.  You can only point to so many cool things from any
page before the whole doc becomes terribly redundant.

> To view it in the worst possible light, it is rather a glaring
> inadequacy, and such inadequacies, as you know, tend to cause doubts
> in people's minds as to the professional quality of a piece of
> software, and, speaking for myself, it tends to make one wonder
> whethere anyone is using, maintaining, or even paying attention to
> it.  (In fact, given that Boost has been around for a while, I find
> it kind of puzzling that I should be the first person to notice this
> particular problem.)

It's getting plenty of use and -- at the moment -- not as much
maintenance attention as I'd like.  Boost.Python is at its healthiest
when someone is funding development, but I do try to stay on top of
the critical things all the time.

> Another suggestion, while I'm at it, is this: I think the
> Boost.Python html docs *definitely* need to be supplemented with
> either/or/both (a) a one-page html version, (b) a pdf version.  The
> reason is to provide easy searchability.  If the Boost.Python docs
> were searchable, I might have found what I was looking for faster.

I can easily put a "search Boost.Python docs" box on the library's
front page without changing the format.  That's a good idea.  In the
meantime, try typing your search terms into Google, followed by

  site:http://www.boost.org/libs/python/doc

> All that being said, I'd like to say again that I am fascinated and impressed
> by the capabilities described therein and I'm looking forward to trying it out!

Thanks a lot!

-- 
Dave Abrahams
Boost Consulting
www.boost-consulting.com