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

[Philippe Proulx]

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
>