.. OTF2 documentation primary file, created by
   sphinx-quickstart on Tue May  3 10:51:53 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Open Trace Format 2's Python interface
======================================

The OTF2 library provides an interface to write and read trace data.

OTF2 is developed within the Score-P project. The Score-P project is funded by the German Federal
Ministry of Education and Research. OTF2 is available under the BSD open source license that allows
free usage for academic and commercial applications.

About the Python interface
--------------------------

The Python OTF2 interface comprises two parts.

    1. The low-level Python interface in the :py:mod:`_otf2` module
    2. The high-level Python interface in the :py:mod:`otf2` module

The low-level interface is implemented using :py:mod:`ctypes`. The main goal for the low-level
interface was to hide ctypes from the user. Besides that, it sticks as near as possible to the
original C interface. See :ref:`lowlevel`.

The high-level interface is built on top of the low-level interface with the aim of hiding all those
nitty gritty details. This part of the interface is described here in detail.

Installing the Python package
-----------------------------

The Python modules are either installed as a regular Python package or are provided by the OTF2
installation when building from the OTF2 source package.
To install the latest release via pip from PyPI use:

  .. code-block:: bash

   pip install [-U] otf2

You can also install the Python package from a source directory.
The standalone Python packages come with a shared OTF2 library of the same version.


Accessing the Python package from a full OTF2 installation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Python modules are also installed into the OTF2 installation. To access these modules
you need to add this path to ``PYTHONPATH``. ``otf2-config`` provides this path
via the ``--pythonpath`` parameter:

- Bash:

  .. code-block:: bash

   export PYTHONPATH=$PYTHONPATH:$(otf2-config --pythonpath)

- Csh:

  .. code-block:: csh

   setenv PYTHONPATH $PYTHONPATH:`otf2-config --pythonpath`

What to read next?
------------------

If you are new to tracing in general or new to OTF2, you should start with reading the :doc:`basics`.

When you are familiar with that, or you want to get your hands wet as quickly at possible, the
:doc:`examples` will help you.

If you have specific questions, the :doc:`otf2` will hopefully help
you.

Contents
--------

.. toctree::
   :maxdepth: 2

   basics

   examples

   otf2

   _otf2

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`