.. PdCom5 documentation master file, created by
   sphinx-quickstart on Fri Jul  8 09:20:30 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to PdCom5's documentation!
==================================

.. image:: https://gitlab.com/etherlab.org/pdcom/badges/master/pipeline.svg
    :target: https://gitlab.com/etherlab.org/pdcom/commits/master
    :alt: pipeline status

.. image:: https://gitlab.com/etherlab.org/pdcom/badges/master/coverage.svg
    :target: https://gitlab.com/etherlab.org/pdcom/commits/master
    :alt: coverage report

.. py:module:: pdcom5

How to install
--------------

You can install PdCom5 using `pip`: `pip3 install pdcom5`.
The sources can be found `here <https://gitlab.com/etherlab.org/pdcom>`_ on GitLab.
They can be used to build PdCom5 on your own if the packages provided on PyPI
or Linux package repositories don't suit you.

Quickstart
----------

The counterpart of PdCom is `PdServ <https://gitlab.com/etherlab.org/pdserv>`_ which ships an example application.
This can be used for exploring the Python interface of PdCom5 if you don't have your own PdServ application.

Please note that this Python API is based on asyncio,
so uses a lot of coroutines (these things with `async` and `await`).
But if you have Python >= 3.8, you can still use this library interactively on the CLI
by starting the asyncio REPL: `python3 -m asyncio`.

The starting point for almost everything is the :py:class:`Process` class
which is in charge of handling the communication.
You can use it to find variables, to set parameters and to subscribe to signals.

In this snippet, a connection is made to the oscillator example in PdServ.
Its cosine output is subscribed to with a period of one second.
The value is printed five times, then the `enable` Parameter is set to False.
After that, the cosine output is polled twice.

>>> import pdcom5
>>> process = pdcom5.Process()
>>> await process.connect("msr://localhost:2345")
>>> variable = await process.find("/osc/cos")
>>> variable.shape
(1,)
>>> sub = await process.subscribe(1.0, variable)
>>> for i in range(5):
...     await sub.read()
...
(8.78446130364271, datetime.timedelta(days=19459, seconds=29086, microseconds=437320))
(7.851994244479773, datetime.timedelta(days=19459, seconds=29087, microseconds=437407))
(-3.094420865989016, datetime.timedelta(days=19459, seconds=29088, microseconds=437398))
(-10.094402900214018, datetime.timedelta(days=19459, seconds=29089, microseconds=437408))
(-4.220607508690086, datetime.timedelta(days=19459, seconds=29090, microseconds=437397))
>>> await process.setVariableValue("/osc/enable", False)
>>> await variable.poll()
(-2.7455815235765124, datetime.timedelta(days=19459, seconds=29159, microseconds=877336))
>>> await variable.poll()
(-2.7455815235765124, datetime.timedelta(days=19459, seconds=29160, microseconds=817388))

There is also :py:attr:`Transmission.event_mode` and
:py:attr:`Transmission.poll_mode` for creating non-periodical subscriptions.

Authentication
--------------

Username and Password can be passed in the url given to :py:meth:`Process.connect`,
for example `msr://username:passwort@localhost`.
If `username` contains an at sign (`@`), it has to be escaped using `%40`.

If login is mandatory and no credentials were supplied,
:py:exc:`LoginRequired` is thrown when calling :py:meth:`Process.connect`.
:py:exc:`LoginFailed` is raised in case login has not been successful.

TLS Encryption
--------------

When using the `msrs` scheme, TLS will be used to encrypt the communication.
If the Certificate Authory (CA) which signed the public certificate
of the PdServ instance is not installed on your machine,
you can provide your own :py:class:`ssl.SSLContext`.

>>> import ssl
>>> ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
>>> ctx.load_verify_locations("/path/to/ca.pem")
>>> ctx.verify_mode = ssl.CERT_REQUIRED
>>> ctx.check_hostname = True
>>> import pdcom5
>>> process = pdcom5.Process()
>>> await process.connect("msrs://localhost", ctx)

You can also use the :py:class:`ssl.SSLContext` to provide User Certificates,
they can be used for TLS Client Authentication.

How to find the PdCom Version
-----------------------------

In the `pdcom5` module, the variable `full_version` contains the version
of the PdCom5 library. If you have any questions or report a bug,
please include this version information in your request. ::

    $ python3 -c "import pdcom5; print(pdcom5.full_version)"
    5.1.0.8.gea62937+

Indices and tables
------------------


.. toctree::
   :maxdepth: 2
   :caption: Contents:

   pdcom5_Process
   pdcom5_Variable
   pdcom5_Subscription
   pdcom5_Subscriber
   pdcom5_Exceptions

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