.. DRAMA Python Interface documentation master file, created by
   sphinx-quickstart on Fri Jun 24 12:26:08 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive. Format is reStructedText.

Welcome to DRAMA Python Interface's documentation!
==================================================
This is the documentation :drama:`DRAMA<dramaintro.html>` interface to Python, via the :drama:`DRAMA2 API<drama2_html/index.html>`.  It allows you to create python scripts and GUIs in Python which will communicate with DRAMA Tasks.

I'm afraid the layout of this documentation is rather poor - it is automatically generated from the source but there are some restrictions on what I can do - I hope to work out how to improve it over time.

The interface is generated using the SWIG tool.  The table belows shows the
main entry point classes and procedures, but there are various other support 
classes listed in the :dpython:`Code Documentation<code>` and 
:dpython:`Index<genindex>`.

Having started DRAMA in the normal way, the DPYTHON_DIR is put in PYTHONPATH and you should be able to import dpython to access these classes.

+-------------------------------------------------+-------------------------------+
| Class Name                                      |       Description             |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.Task<Task>`                   | Implements a DRAMA task.      |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.Path<Path>`                   | Implements a Path object used | 
|                                                 | to talk to other tasks.       |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.AId<Aid>`                     | Provides access to DRAMA's    |
|                                                 | SDS objects (A for argument). |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.pmonitor<pmonitor>`           | Provides the ability to       |
|                                                 | monitor parameters in other   |
|                                                 | tasks.                        |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.SdsToDict<SdsToDict>`         | Convert an SDS structure to   |
|                                                 | a dictionary.                 |
+-------------------------------------------------+-------------------------------+
| :dpycode:`dpython.MonitorToDict<MonitorToDict>` | A subclass of pmonitor which  |
|                                                 | puts parameter values in a    |
|                                                 | dictionary.                   |
+-------------------------------------------------+-------------------------------+

.. highlight:: python
    :linenothreshold: 1

The source code library includes the file pythontest.py, which is a general
test program.  The examples below are based on that file.

Here is how you might define a class to run the DRAMA message loop in a thread::

    class dramaTask (threading.Thread):
        def __init__(self):
            threading.Thread.__init__(self)
        def run(self):
            self.task = dpython.Task("AAA")

            self.task.AddExitAction()
            self.task.RunDrama()
        def GetTask(self):
            return dpython.TaskWeakPtr(self.task)
        def SignalExit(self):
            self.task.SignalDramaToExit(0)

And then to actually start the task, use::

    dramaThread = dramaTask()
    dramaThread.start()
    time.sleep(1)

Note that after executing the start() method, you typically wait a second for
the DRAMA task to actually start (really, to force a thread context switch).
Otherwise the DRAMA task may not be running when you try to do something.

The following show how you might load and run the task TICKER, from the file
ticker in the directory $DITS_DEV (presuming the DRAMA networking is running)::

    myPath = dpython.Path(dramaThread.GetTask(), "TICKER", "", "DITS_DEV:ticker")
    myPath.SetBuffers(1600,1600);
    myPath.GetPath()


To send an obey message to TICKER using this path, you would do::

    myPath.Obey("TICK")

And this shows how to create a command structure (might use for an Obey as well)
and then to use it to set a parameter value::

    a = dpython.AId.CreateArgStruct()
    a.Puti("Argument1", 10)
    myPath.SetParam("PARAM1", a)

Here a get followed by various AId (SDS) calls to examine the result::

    b = myPath.GetParam("PARAM1")
    b.List()

    name = b.GetName()
    code = b.Code()
    if code == "SDS_STRUCT":
        item = b.Find("PARAM1")
        name = item.GetName()
        code = item.Code()
        dims = item.GetNumArrayDims()
        value = item.toString()

Here we create an SDS structure, list it and then convert it to a dictionary to
demostrate the required calls::

    a = dpython.AId.CreateArgStruct()
    a.Putc("CharItem", 3);
    a.Puts("ShortItem", 4);
    a.Putus("UShortItem", 5);
    a.Puti("INT32Item", 6);
    a.Putui("UINT32Item", 7);
    a.Puti64("INT64Item", 8);
    a.Putui64("UINT64Item", 9);
    a.Putf("FloatItem", 10.1);
    a.Putd("DoubleItem", 11.2);
    a.PutStr("StringItem1", "12");

    # Have a look at what we have created (to stdout).
    a.List()

    #
    # We can convert things like this to python dictionaries.
    #
    print (dpython.SdsToDict(a))

Or reading an SDS structure from a file and converting it to a dictionary::

    b = dpython.AId.Read("tict_pars.sds")
    print (dpython.SdsToDict(b))

Note that to cause the DRAMA task thread to exit, you need to execute::

    dramaThread.SignalExit()


DRAMA Parameter monitoring allows your task to be notified automatically if
the value of a parameter in another task changes.  It requires that, having 
created your DRAMA message reading thread, that you create and run another 
thread to do the monitoring. In the example below, I first create a class 
which will be used to implement thread. This class uses an object
of type :dpycode:`dpython.MonitorToDict<MonitorToDict>`, itself a sub-class of
:dpycode:`dpython.pmonitor<pmonitor>`, to do the monitoring.  The
MonitorToDict class is used to cause the parameter values to appear in a
dictionary.  You could create your own sub-class of pmonitor to have other
things happen on the changes.::

    class dramaMonitor (threading.Thread):
        # Constructor.  Save details to be used when thread starts.
        def __init__(self, task, path, parameters):
            threading.Thread.__init__(self)
            self.task = task.GetTask()
            self.param = parameters
            self.path  = path
            self.monitor = None
        
        # After the thread is started, this is run within the thread
        #  to do the real work of thread.  We set up and run our monitor,
        #  using a variable of type myMonitor (a sub-class of
        #   dpython.pmonitor) to do the monitoring.
        def run(self):
            self.monitor = dpython.MonitorToDict(self.task, self.param)
            self.monitor.RunMonitor(self.path)
            print ("Dictionary contains:")
            print (self.monitor.dict)
        # Method used to cancel the monitor.
        def cancel(self):
            if self.monitor:
                self.monitor.Cancel()


Once I have this class definitoin, I can ran the monitor like so::
        
    # Create the monitor thread object.  Specifying parameter to monitor
    #   Presumes the dramaThread and myPath objects from previous examples.
    monitorThread = dramaMonitor(dramaThread, myPath,
                                 dpython.StringVector(["PARAM1",
                                                       "PARAM2",
                                                       "PARAM3",
                                                       "PARAM4",
                                                       "STRUCT_PARAM"]))
    # And now start the monitor thread.
    monitorThread.start()


Parameter monitoring is particuarly usefull to allow a GUI to automatically
update displayed items.

Contents:

.. toctree::
   :maxdepth: 3

   code

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

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


============
Example code
============
The full dpython test program is below.  This can be found in the dpython
ACMM sub-system.


.. literalinclude:: ../dpythontest.py