Karabo Bridge Python client
===========================

The ``karabo_bridge`` Python package provides a client interface to receive
data from the Karabo bridge.

.. module:: karabo_bridge


.. autoclass:: Client

   .. automethod:: next

Data container
--------------

The data object returned by :meth:`Client.next` is a tuple of two nested
dictionaries, holding data and metadata respectively.

The first level of keys in both dictionaries are source names,
which typically correspond to Karabo device names.

In the data dictionary, each source has a dictionary representing a flattened
Karabo hash, with dots delimiting successive key levels.
The values are either basic Python types such as strings and floats,
or numpy arrays.

In the metadata dictionary, each source has a dictionary with keys: ``source``,
``timestamp``, ``timestamp.tid``, ``timestamp.sec``, ``timestamp.frac``
and ``ignored_keys``, which is a list of strings identifying keys which were
filtered out of the data by configuration options on the bridge server.

.. code-block:: python

    (
        {   # Metadata
            'SPB_DET_AGIPD1M-1/DET/0CH0:xtdf': {
                'source': 'SPB_DET_AGIPD1M-1/DET/0CH0:xtdf',
                'timestamp': 1526464869.4109755,
                # Timestamps can have attosecond resolution: 18 fractional digits
                'timestamp.frac': '410975500000000000',
                'timestamp.sec': '1526464869',
                'timestamp.tid': 10000000001,
                'ignored_keys': []
            },
        },
        {   # Data
            'SPB_DET_AGIPD1M-1/DET/0CH0:xtdf': {
                'image.data': array(...),
                'header.pulseCount': 64,
                # ... other keys
            }
        }
    )