[C++-sig] Pyste/Pyplusplus/Boost documentation problems

[Niall Douglas]

On 14 Jan 2006 at 22:21, David Abrahams wrote:

> >> """If you can, use pyplusplus over pyste. I say that for ALL users of
> >> pyste, pyplusplus is now mature enough to be useful as well as being
> >> actively developed. It can also do quite a few tricks pyste cannot."""
> >>
> >> If this is really the case, I think the Boost documentation needs to say
> >> so.  For example, the doc page
> >> <<http://www.boost.org/libs/python/pyste/>> does not give any warning
> >> that Pyste is essentially deprecated (which it apparently is, if the
> >> above quote is true).  
> >
> > It may be deprecated by the author of that quote, but the author of
> > the quote has no official standing.
> 
> I should clarify that I don't mean any disrespect to Niall (the author
> of the quote) and I am not hostile to pyplusplus. 

I should also clarify. pyplusplus is superior to pyste, but it 
doesn't mean pyplusplus is good enough to replace pyste yet. I have 
still to generate a working binary using pyplusplus (which is because 
I have had so little free time recently rather than any fault with 
the software) and until I do have a fully working binary, I wouldn't 
recommend submitting any Boost.Python documentation patches.

TnFOX is to my knowledge the biggest and most complex user of pyste - 
perhaps even Boost.Python if the bindings library size is to be 
judged. Pyplusplus generates far more efficient code (which is also 
easier to debug) so it's entirely possible I'll get a far smaller 
binding too. It's all good, but it's not there quite yet.

> However, Roman (the
> author of pyplusplus) has not made the sort of overtures I would
> expect in order to get it to be officially endorsed by Boost(.Python).
> He has been very "independent-minded," doing most of pyplusplus on his
> own and rejecting the idea of working with the author of Pyste, from
> whom he might have learned a few things, Pyste's weaknesses
> notwithstanding.  Without more coordination with the community it
> should be no surprise that the community is not linking more to
> pyplusplus.  If it is indeed more capable than Pyste I would like to
> be referencing it as the de-facto generator for Boost.Python wrpapers.

With respect Dave, you never have used pyste yourself in anger and so 
are completely unaware of its strengths and failings. If I were you, 
I would have tested it myself extensively before allowing it into my 
CVS - it after all will be the first thing most users see of your 
library and often the *only* thing they see. Its strengths and 
weaknesses reflect strongly on BPL.

Now pyste needed rewriting - it had run into architectural limits. 
And I admit I had doubts when Roman started saying he was going to 
write a replacement - admittedly not helped by his poor English. 
However, when literally out of the blue he sent me a set of new TnFOX 
bindings about 98% complete I was quite blown away. Since then as I 
have delved into his source, I realise that he is a very competent 
coder and has got the design right from the beginning - which Bruno 
(and my respect to you nevertheless) did not. There are still some 
rough spots (like default parameters), but it's very nearly perfect 
on the generation front.

> Is it a complete replacement for pyste?  What should a Pyste user do
> in order make his code us pyplusplus instead?  IMO there ought to be a
> Pyste compatibility layer.

That would be inadvisable. The best thing is for pyste users to 
regenerate their config files from scratch as pyplusplus uses quite a 
different configuration model (nowhere near as easy, but considerably 
more powerful).

> I think
> http://www.language-binding.net/pyplusplus/to_pyste_comparison.html
> would be a lot better if it took a more neutral tone; it seems to bash
> Pyste a lot more than necessary.  Fortunately, this page doesn't seem
> to be linked from the pyplusplus main page but if Boost is going to
> endorse pyplusplus, that same information *ought* to be made more
> generally available.

No Roman is being fair on that page. He nor I mean no disrespect to 
Bruno, pyste is a good bindings generator but it has hard design 
limits in it and Roman gives a pretty good overview of those.

I should add that when Roman says it doesn't support templates, he 
doesn't mean it doesn't support template *instances* which it does 
(again, there are some rough spots here, but it's as good or better 
than pyste).

I think we're all getting ahead of ourselves. My last exam is on the 
20th January after which I have one free week. During this week, I 
have two items on the plan:

1. Write article for Economics journal
2. Finish pyplusplus bindings in TnFOX

If I finish the latter, I will submit a BPL documentation patch to 
alert users that pyplusplus exists and what it can do. Before 
pyplusplus could become part of BPL it would need extensive amounts 
of documenting, and unless someone volunteers then that won't be 
soon.

Cheers,
Niall