[lttng-dev] Babeltrace python bindings documentation is no up-to-date

Tue Nov 1 00:51:30 UTC 2016

On Mon, Oct 31, 2016 at 4:38 PM, Philippe Proulx
<eeppeliteloop at gmail.com> wrote:
> On Mon, Oct 31, 2016 at 4:02 PM, Jean Spector <jean.spector at gmail.com> wrote:
>> Thank you Philippe.
>>
>> Adding a different documentation page for older versions (it's the latest
>> package on RHEL 7.2 - so I'd expect more newbies to encounter this issue)
>> could help anyone trying the Python bindings for the first time.
>> I'm sure you realize that trying the official example and failing can be
>> quite frustrating and could turn off potential users.
>
> I'll make sure to make the doc as clear as possible. The main problem here is
> that the module is simply not Sphinx-documented in Babeltrace 1.x. I guess
> I could search and replace the package names in the doc before publishing it.
> I'll find a way to make it clear anyway.

Jean,

See <http://diamon.org/babeltrace/docs/python/> again.

I added an important admonition to each page which at least explains what
to do if you're using Babeltrace 1.x. Plus the indicated version is
now `2.0.0-pre`.

It should not be so complicated to understand for newcomers. That's the best
I can do for the moment; writing a different version for Babeltrace
1.x is out of
the question.

Phil

>
>> This is especially
>> true if it comes after other issues(let me know if you'd prefer these to be
>> sent in separate emails):
>>
>> RHEL 7.2 uses python 3.4, but babeltrace-python-1.2.4 requires python 3.3,
>> which is not available anymore - at least not out of the box.
>
> What do you mean? The bindings work just fine with Python 3.4 and Python 3.5.
>
>> Again, I've solved the issue for myself, so it's not a support call. The
>> idea is that it would be great if the initial install+run stage was made
>> less painful.
>> I believe it would increase the user base as, for instance, I was on the
>> verge of giving up after building from source has also failed for me.
>>
>> When trying to build from latest stable source (1.4.0) on RHEL 7.2, I've
>> encountered a couple of issues:
>>
>> configure would fail on popt. "ln -s /usr/lib64/libpopt.so.0
>> /usr/lib64/libpopt.so" worked around the issue, but there must be a better
>> way (or a line in the README).
>> "python3 -c 'import babeltrace'" would fail with "ImportError:
>> /usr/local/lib64/python3.4/site-packages/babeltrace/_nativebt.so: undefined
>> symbol: PyInstance_Type"
>>
>> That's where I gave up trying to build from source. It could be due to the
>> same python 3.4 - but it's just a guess.
>
> The official channel for reporting bugs is the bug tracker
> <https://bugs.lttng.org/projects/babeltrace/>. If you create an issue there, we
> can ask for details about the environment and context and track the bug to
> remember it.
>
> I have no idea what's going wrong here, but if you create an issue we
> can test the
> same environment (RHEL 7.2) and see if we can reproduce the bug.
>
>>
>> ==========
>>
>> To recap, I see 3 issues here:
>>
>> Documentation - any platform
>> Install of the latest  babeltrace-python (1.2.4) - RHEL 7.2
>> Building from the latest stable source (1.4.0) - RHEL 7.2
>>
>>
>> In any case, thanks for the great tool. I hope to put it to good use.
>> Jean
>
> Thanks for the feedback! We appreciate.
>
> Phil
>
>>
>>
>> On Mon, Oct 31, 2016 at 7:07 PM, Philippe Proulx <eeppeliteloop at gmail.com>
>> wrote:
>>>
>>> On Sat, Oct 29, 2016 at 9:55 AM, Jean Spector <jean.spector at gmail.com>
>>> wrote:
>>> > When trying to use the example from
>>> > http://diamon.org/babeltrace/docs/python/examples/ (pointed to via
>>> > http://lttng.org/viewers/), the code is not up-to-date.
>>> >
>>> > For instance, the first line in the example (import babeltrace.reader)
>>> > fails
>>> > as there's no 'reader' to import.
>>> >
>>> > I've managed to get over it, but thought it would be better to have a
>>> > working example code.
>>>
>>> I wrote this doc and it was merged into master more than a year ago.
>>> When writing this doc, I split the `babeltrace` package into the
>>> `reader` and `writer` subpackages to make the autodocumentation with
>>> Sphinx easier. Now it looks like this split was never backported to
>>> v1.2, v1.3, v1.4, and soon v1.5.
>>>
>>> The `Babeltrace 1.2.0` version you see on the front page is just the
>>> current version found when I generated the online version. Really, the
>>> title should say `Babeltrace (master branch)`. The master branch will
>>> become Babeltrace 2.0 soon. In the meantime, simply drop the `reader`
>>> subpackage when you read the doc and try examples. So
>>>
>>>     import babeltrace.reader as btreader
>>>
>>>     trace_collection = btreader.TraceCollection()
>>>
>>> becomes
>>>
>>>     import babeltrace as btreader
>>>
>>>     trace_collection = btreader.TraceCollection()
>>>
>>> For the CTF writer part, drop the `writer` subpackage, and import the
>>> `CTFWriter` class: you'll find all the documented classes within this
>>> class (kind of weird, and one of the reasons I created a subpackage
>>> instead):
>>>
>>>     import babeltrace.writer as btwriter
>>>
>>>     writer = btwriter.Writer(trace_path)
>>>
>>> becomes
>>>
>>>     from babeltrace import CTFWriter as btwriter
>>>
>>>     writer = btwriter.Writer(trace_path)
>>>
>>> Note that the new subpackage split is backward compatible with the
>>> bindings of v1.x, so the code you write now will continue to work...
>>> forever.
>>>
>>> I might add an equivalent of this response as a note in the generated
>>> documentation.
>>>
>>> BR,
>>> Phil
>>>
>>> >
>>> > P.S. I'm running RHEL 7.2 with babeltrace-python-1.2.4-1.el7.x86_64
>>> >
>>> > Best Regards,
>>> > Jean
>>> >
>>> >
>>> > _______________________________________________
>>> > lttng-dev mailing list
>>> > lttng-dev at lists.lttng.org
>>> > https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev
>>> >
>>
>>