doc/bindings/python/source/index.rst

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