doc/bindings/python/source/index.rst

   1 ###########################################
   2 Babeltrace |version| legacy Python bindings
   3 ###########################################
   4
   5 Generated on |today|.
   6
   7
   8 Welcome!
   9 ========
  10
  11 Welcome to `Babeltrace <http://www.efficios.com/babeltrace>`_'s
  12 *legacy* Python bindings' documentation!
  13
  14 Babeltrace is a trace format converter. It is able to read and write
  15 different trace formats, such as the
  16 `Common Trace Format <http://www.efficios.com/ctf>`_ (CTF).
  17 Babeltrace also acts as the CTF reference implementation.
  18
  19 The Babeltrace legacy Python bindings rely on the ``libbabeltrace``
  20 library, the public C API of Babeltrace.
  21
  22
  23 Installing
  24 ==========
  25
  26 The bindings may be enabled when configuring Babeltrace's build::
  27
  28     ./configure --enable-python-bindings
  29
  30 On Debian and Ubuntu, the bindings are available in the
  31 ``python3-babeltrace`` package.
  32
  33 .. note::
  34
  35    Currently, the Babeltrace legacy Python bindings only works
  36    with Python 3.
  37
  38
  39 Bindings
  40 ========
  41
  42 The Babeltrace legacy Python bindings are available as a single Python
  43 package, :py:mod:`babeltrace`.
  44
  45 The Babeltrace legacy Python bindings' API is divided into two parts:
  46
  47 * The :ref:`reader API <reader-api>` is exposed by the
  48   :mod:`babeltrace.reader` module, a set of classes used to
  49   open a collection of different traces and iterate on their events.
  50 * The :ref:`CTF writer API <ctf-writer-api>` is exposed by the
  51   :mod:`babeltrace.writer` module, which makes it possible to
  52   write a complete `CTF <http://www.efficios.com/ctf>`_ trace from
  53   scratch.
  54
  55 .. note::
  56
  57    For backward compatibility reasons, the reader API is imported in the
  58    package itself. The CTF writer API is imported in the package itself
  59    too, as :mod:`~babeltrace.CTFWriter`. It is, however, strongly
  60    recommended to import and use the three modules
  61    (:mod:`babeltrace.common`, :mod:`babeltrace.reader`, and
  62    :mod:`babeltrace.writer`) explicitly, since there is no long-term
  63    plan to maintain the compatibility layer.
  64
  65 **Contents**:
  66
  67 .. toctree::
  68    :numbered:
  69
  70    constants
  71    reader
  72    writer
  73    examples