The Synchronous High Level API
==============================

The main advantage of using the high level APIs over their low level counterparts is the support of automatic parameter name completion in Python IDEs. With the high level APIs parameter name typing errors are a thing of the past.

The Python classes and modules needed for this feature are autogenerated from the parameter models of the supported laser types. A separate Python module is provided for each software release.

Client Access to Parameters
---------------------------

Reading or writing parameter values works as follows:

.. code-block:: python

    from toptica.lasersdk.dlcpro.v1_6_3 import DLCpro, NetworkConnection

    with DLCpro(NetworkConnection('My Laser')) as dlcpro:
        print(dlcpro.system_label.get())
        dlcpro.system_label.set('Please do not touch!')

The separator character (':') used within full parameter names is replaced by the Python dot operator ('.'). Hyphens ('-') are replaced by underscores ('_').

Invoking events works as expected:

.. code-block:: python

    dlcpro.laser1.dl.lock.close()

The same applies for events with extensions (aka commands):

.. code-block:: python

    # Execute command with two arguments that returns a bytes object
    result = dlcpro.laser1.recorder.data.get_data(0, 100)

    # Execute command with binary output stream and no return value
    output_stream = dlcpro.system_service_report.service_report()

    # Execute command with one argument, binary input stream, string-type
    # output stream, and no return value
    with open('DLCpro-archive.fw', 'rb') as f:
        data = f.read()

    output_stream = dlcpro.fw_update.upload(input_stream=data, f.name)

Parameter Subscription
----------------------

Parameter value subscription is also possible. Change notifications are delivered via a callback function:

.. code-block:: python

    from toptica.lasersdk.dlcpro.v2_6_0 import DLCpro, NetworkConnection, Subscription, Timestamp, SubscriptionValue

    def callback(subscription: Subscription, timestamp: Timestamp, value: SubscriptionValue):
        print("{}: Parameter '{}' changed its value to {}".format(timestamp.time(), subscription.name, value.get()))

    with DLCpro(NetworkConnection('172.16.109.112')) as dlc:
        with dlc.laser1.dl.cc.current_act.subscribe(callback):
            dlc.run()


Example
-------

See :ref:`synchronous_api_example`.