pytrms 0.2.2__tar.gz → 0.9.0__tar.gz

pytrms-0.9.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.1
+Name: pytrms
+Version: 0.9.0
+Summary: Python bundle for proton-transfer reaction mass-spectrometry (PTR-MS).
+License: GPL-2.0
+Author: Moritz Koenemann
+Author-email: moritz.koenemann@ionicon.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: h5py (>=3.12.1,<4.0.0)
+Requires-Dist: matplotlib (>=3.9.2,<4.0.0)
+Requires-Dist: paho-mqtt (>=1.6.1,<1.7.0)
+Requires-Dist: pandas (>=2.2.3,<3.0.0)
+Requires-Dist: pyModbusTCP (>=0.3.0,<0.4.0)
+Requires-Dist: requests (>=2.32.3,<3.0.0)

{pytrms-0.2.2 → pytrms-0.9.0}/pyproject.toml

@@ -1,26 +1,31 @@
 [tool.poetry]
 name = "pytrms"
-version = "0.2.2"
+version = "0.9.0"
 description = "Python bundle for proton-transfer reaction mass-spectrometry (PTR-MS)."
 authors = ["Moritz Koenemann <moritz.koenemann@ionicon.com>"]
 license = "GPL-2.0"
 include = [
-    "par_ID_list.txt",
+    "pytrms/data/ParaIDs.csv",
     "pytrms/data/IoniTofPrefs.ini",
 ]
 
 [tool.poetry.dependencies]
-python = "^3.8"
-h5py = "^3.6.0"
-requests = "^2.27.1"
-pandas = "^1.4.0"
-pyModbusTCP = "^0.2.0"
+python = "^3.10"
+h5py = "^3.12.1"
+matplotlib = "^3.9.2"
+requests = "^2.32.3"
+pandas = "^2.2.3"
+pyModbusTCP = "~0.3.0"
+paho-mqtt = "~1.6.1"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.3.0"
 
 [tool.poetry.group.dev.dependencies]
-ipykernel = "^6.13.1"
-matplotlib = "^3.5.2"
-Sphinx = "^5.3.0"
+Sphinx = "^8.0.0"
+ipykernel = "^6.29.0"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]
 build-backend = "poetry.core.masonry.api"
+

pytrms-0.9.0/pytrms/__init__.py

@@ -0,0 +1,37 @@
+_version = '0.9.0'
+
+__all__ = ['load', 'connect']
+
+
+def load(path):
+    '''Open a datafile for post-analysis or batch processing.
+
+    returns a `Measurement`.
+    '''
+    from .measurement import OfflineMeasurement
+    from .readers import IoniTOFReader
+
+    reader = IoniTOFReader(path)
+
+    return OfflineMeasurement(reader)
+
+def connect(host=None, method='webapi'):
+    '''Connect a client to a running measurement server.
+
+    'method' is the preferred connection, either 'webapi' (default) or 'modbus'.
+
+    returns an `Instrument` if connected successfully.
+    '''
+    from .instrument import Instrument
+    from .helpers import PTRConnectionError
+
+    if method.lower() == 'webapi':
+        from .clients.ioniclient import IoniClient
+        return IoniClient(host)
+
+    if method.lower() == 'modbus':
+        from .modbus import IoniconModbus
+        return IoniconModbus(host)
+
+    raise NotImplementedError(str(method))
+

pytrms-0.9.0/pytrms/_base/__init__.py

@@ -0,0 +1,24 @@
+from collections import namedtuple
+
+from .mqttclient import MqttClientBase
+from .ioniclient import IoniClientBase
+
+class itype:
+
+    table_setting_t = namedtuple('mass_mapping', ['name', 'mass2value'])
+    timecycle_t     = namedtuple('timecycle',  ['rel_cycle','abs_cycle','abs_time','rel_time'])
+    masscal_t       = namedtuple('masscal',    ['mode', 'masses', 'timebins', 'cal_pars', 'cal_segs'])
+    add_data_item_t = namedtuple('add_data',   ['value', 'name', 'unit', 'view'])
+    fullcycle_t     = namedtuple('fullcycle',  ['timecycle', 'intensity', 'mass_cal', 'add_data'])
+
+    AME_RUN    = 8
+    AME_STEP   = 7
+    AME_ACTION = 5
+    USE_MEAN   = 2  # (only in AUTO_UseMean)
+
+    REACT_Udrift = 0
+    REACT_pDrift = 1
+    REACT_Tdrift = 2
+    REACT_PI_Idx = 4  # skipping E/N = 3
+    REACT_TM_Idx = 5
+

pytrms-0.9.0/pytrms/_base/ioniclient.py

@@ -0,0 +1,32 @@
+from abc import ABC, abstractmethod
+
+class IoniClientBase(ABC):
+
+    @property
+    @abstractmethod
+    def is_connected(self):
+        '''Returns `True` if connection to IoniTOF could be established.'''
+        pass
+
+    @property
+    @abstractmethod
+    def is_running(self):
+        '''Returns `True` if IoniTOF is currently acquiring data.'''
+        pass
+
+    @abstractmethod
+    def connect(self, timeout_s):
+        pass
+
+    @abstractmethod
+    def disconnect(self):
+        pass
+
+    def __init__(self, host, port):
+        # Note: circumvent (potentially sluggish) Windows DNS lookup:
+        self.host = '127.0.0.1' if host == 'localhost' else str(host)
+        self.port = int(port)
+
+    def __repr__(self):
+        return f"<{self.__class__.__name__} @ {self.host}[:{self.port}]>"
+

pytrms-0.9.0/pytrms/_base/mqttclient.py

@@ -0,0 +1,106 @@
+import os
+import time
+import logging
+import json
+from collections import deque
+from itertools import cycle
+from threading import Condition, RLock
+from datetime import datetime as dt
+from abc import ABC, abstractmethod
+
+import paho.mqtt.client as mqtt
+
+from .ioniclient import IoniClientBase
+
+log = logging.getLogger(__name__)
+
+__all__ = ['MqttClientBase']
+
+
+def _on_connect(client, self, flags, rc):
+    # Note: ensure subscription after re-connecting,
+    #  wildcards are '+' (one level), '#' (all levels):
+    default_QoS = 2
+    topics = set()
+    for subscriber in self._subscriber_functions:
+        topics.update(set(getattr(subscriber, "topics", [])))
+    subs = sorted(zip(topics, cycle([default_QoS])))
+    log.debug(f"[{self}] " + "\n   --> ".join(["subscribing to"] + list(map(str, subs))))
+    rv = client.subscribe(subs)
+    log.info(f"[{self}] successfully connected with {rv = }")
+
+def _on_subscribe(client, self, mid, granted_qos):
+    log.info(f"[{self}] successfully subscribed with {mid = } | {granted_qos = }")
+
+def _on_publish(client, self, mid):
+    log.debug(f"[{self}] published {mid = }")
+
+
+class MqttClientBase(IoniClientBase):
+
+    @property
+    @abstractmethod
+    def is_connected(self):
+        '''Returns `True` if connected to the server.
+
+        Note: this property will be polled on initialization and should
+         return `True` if a connection could be established!
+        '''
+        return (True
+            and self.client.is_connected())
+
+    def __init__(self, host, subscriber_functions,
+            on_connect, on_subscribe, on_publish, 
+            connect_timeout_s=10):
+        super().__init__(host, port=1883)
+        # configure connection...
+        self.client = mqtt.Client(clean_session=True)
+        # clean_session is a boolean that determines the client type. If True,
+        # the broker will remove all information about this client when it
+        # disconnects. If False, the client is a persistent client and
+        # subscription information and queued messages will be retained when the
+        # client disconnects.
+        # The clean_session argument only applies to MQTT versions v3.1.1 and v3.1.
+        # It is not accepted if the MQTT version is v5.0 - use the clean_start
+        # argument on connect() instead.
+        self.client.on_connect   = on_connect    if on_connect   is not None else _on_connect
+        self.client.on_subscribe = on_subscribe  if on_subscribe is not None else _on_subscribe
+        self.client.on_publish   = on_publish    if on_publish   is not None else _on_publish
+        # ...subscribe to topics...
+        self._subscriber_functions = list(subscriber_functions)
+        for subscriber in self._subscriber_functions:
+            for topic in getattr(subscriber, "topics", []):
+                self.client.message_callback_add(topic, subscriber)
+        # ...pass this instance to each callback...
+        self.client.user_data_set(self)
+        # ...and connect to the server:
+        try:
+            self.connect(connect_timeout_s)
+        except TimeoutError as exc:
+            log.warn(f"{exc} (retry connecting when the Instrument is set up)")
+
+    def connect(self, timeout_s=10):
+        log.info(f"[{self}] connecting to MQTT broker...")
+        self.client.connect(self.host, self.port, timeout_s)
+        self.client.loop_start()  # runs in a background thread
+        started_at = time.monotonic()
+        while time.monotonic() < started_at + timeout_s:
+            if self.is_connected:
+                break
+
+            time.sleep(10e-3)
+        else:
+            self.disconnect()
+            raise TimeoutError(f"[{self}] no connection to IoniTOF")
+
+    def publish_with_ack(self, *args, timeout_s=10, **kwargs):
+        # Note: this is important when publishing just before exiting the application
+        #  to ensure that all messages get through (timeout_s is set on `.__init__()`)
+        msg = self.client.publish(*args, **kwargs)
+        msg.wait_for_publish(timeout=timeout_s)
+        return msg
+
+    def disconnect(self):
+        self.client.loop_stop()
+        self.client.disconnect()
+

pytrms-0.9.0/pytrms/clients/__init__.py

@@ -0,0 +1,33 @@
+import os
+
+_root = os.path.dirname(__file__)
+_par_id_file = os.path.abspath(os.path.join(_root, '..', 'data', 'ParaIDs.csv'))
+assert os.path.exists(_par_id_file), "par-id file not found: please re-install PyTRMS package"
+
+
+import logging as _logging
+
+_logging.TRACE = 0  # overwrites logging.NOTSET
+
+def enable_extended_logging(log_level=_logging.DEBUG):
+    '''make output of http-requests more talkative.
+    
+    set 'log_level=logging.TRACE' (defined as 0 in pytrms.__init__) for highest verbosity!
+    '''
+    if log_level <= _logging.DEBUG:
+        # enable logging of http request urls on the library, that is
+        #  underlying the 'requests'-package:
+        _logging.warn(f"enabling logging-output on 'urllib3' ({log_level = })")
+        requests_log = _logging.getLogger("urllib3")
+        requests_log.setLevel(log_level)
+        requests_log.propagate = True
+    
+    if log_level == _logging.TRACE:
+        # Enabling debugging at http.client level (requests->urllib3->http.client)
+        # you will see the REQUEST, including HEADERS and DATA, and RESPONSE with
+        # HEADERS but without DATA. the only thing missing will be the response.body,
+        # which is not logged.
+        _logging.warn(f"enabling logging-output on 'HTTPConnection' ({log_level = })")
+        from http.client import HTTPConnection
+        HTTPConnection.debuglevel = 1
+

pytrms-0.9.0/pytrms/clients/db_api.py

@@ -0,0 +1,186 @@
+import os
+import json
+
+import requests
+
+from . import _logging
+from .._base import IoniClientBase
+
+log = _logging.getLogger(__name__)
+
+# TODO :: sowas waer auch ganz cool: die DBAPI bietes sich geradezu an,
+#  da mehr object-oriented zu arbeiten:
+#   currentVariable = get_component(currentComponentNameAction, ds)
+#   currentVariable.save_value({'value': currentValue})
+
+class IoniConnect(IoniClientBase):
+
+    @property
+    def is_connected(self):
+        '''Returns `True` if connection to IoniTOF could be established.'''
+        try:
+            self.get("/api/status")
+            return True
+        except:
+            return False
+
+    @property
+    def is_running(self):
+        '''Returns `True` if IoniTOF is currently acquiring data.'''
+        raise NotImplementedError("is_running")
+
+    def connect(self, timeout_s):
+        pass
+
+    def disconnect(self):
+        pass
+
+    def __init__(self, host='127.0.0.1', port=5066, session=None):
+        super().__init__(host, port)
+        self.url = f"http://{self.host}:{self.port}"
+        if session is None:
+            session = requests.sessions.Session()
+        self.session = session
+        # ??
+        self.current_avg_endpoint = None
+        self.comp_dict = dict()
+
+    def get(self, endpoint, **kwargs):
+        return self._get_object(endpoint, **kwargs).json()
+
+    def post(self, endpoint, data, **kwargs):
+        return self._create_object(endpoint, data, 'post', **kwargs).headers.get('Location')
+
+    def put(self, endpoint, data, **kwargs):
+        return self._create_object(endpoint, data, 'put', **kwargs).headers.get('Location')
+
+    def upload(self, endpoint, filename):
+        if not endpoint.startswith('/'):
+            endpoint = '/' + endpoint
+        with open(filename) as f:
+            # Note (important!): this is a "form-data" entry, where the server
+            #  expects the "name" to be 'file' and rejects it otherwise:
+            name = 'file'
+            r = self.session.post(self.url + endpoint, files=[(name, (filename, f, ''))])
+            r.raise_for_status()
+
+        return r
+
+    def _get_object(self, endpoint, **kwargs):
+        if not endpoint.startswith('/'):
+            endpoint = '/' + endpoint
+        if 'headers' not in kwargs:
+            kwargs['headers'] = {'content-type': 'application/hal+json'}
+        elif 'content-type' not in (k.lower() for k in kwargs['headers']):
+            kwargs['headers'].update({'content-type': 'application/hal+json'})
+        r = self.session.request('get', self.url + endpoint, **kwargs)
+        r.raise_for_status()
+        
+        return r
+
+    def _create_object(self, endpoint, data, method='post', **kwargs):
+        if not endpoint.startswith('/'):
+            endpoint = '/' + endpoint
+        if not isinstance(data, str):
+            data = json.dumps(data)
+        if 'headers' not in kwargs:
+            kwargs['headers'] = {'content-type': 'application/hal+json'}
+        elif 'content-type' not in (k.lower() for k in kwargs['headers']):
+            kwargs['headers'].update({'content-type': 'application/hal+json'})
+        r = self.session.request(method, self.url + endpoint, data=data, **kwargs)
+        if not r.ok:
+            log.error(f"POST {endpoint}\n{data}\n\nreturned [{r.status_code}]: {r.content}")
+            r.raise_for_status()
+
+        return r
+
+    def iter_events(self):
+        """Follow the server-sent-events (SSE) on the DB-API."""
+        r = self.session.request('GET', self.url + "/api/events",
+                headers={'accept': 'text/event-stream'}, stream=True)
+        r.raise_for_status()
+        kv_pair = dict()
+        for line in r.iter_lines():
+            # empty newlines serve as keep-alive and end-of-entry:
+            if not line:
+                if kv_pair:
+                    yield kv_pair
+                    kv_pair = dict()
+                else:
+                    log.debug("sse: still kept alive...")
+                continue
+
+            key, val = line.decode().split(':')
+            kv_pair[key] = val.strip()
+
+    def refresh_comp_dict(self):
+        j = self.get('/api/components')
+        self.comp_dict = {component["shortName"]: component
+            for component in j["_embedded"]["components"]}
+    
+    def get_component(self, short_name):
+        if not len(self.comp_dict):
+            self.refresh_comp_dict()
+    
+        return self.comp_dict[short_name]
+
+    def create_component(self, short_name):
+        payload = {
+            "shortName": short_name
+        }
+        self.post('/api/components', payload)
+        self.refresh_comp_dict()
+
+    def create_average(self, endpoint, run, step, action=0, use_mean=True):
+
+        params = {'run': int(run), 'step': int(step), 'usemean': bool(use_mean)}
+        if (action != 0):
+            params['action'] = int(action)
+
+        timecycles = self.get(endpoint, params)
+        self.current_avg_endpoint = self.post('/api/averages', timecycles)
+
+    def save_component_values(self, new_values):
+        """
+        Post Components to the database.
+
+        `new_values`    dictionary {name~>value}
+        """
+        if self.current_avg_endpoint is None:
+            raise Exception("create average first")
+    
+        payload = {
+            "quantities": [
+                {
+                    "componentID": self.get_component(name)["componentID"],
+                    "value": value
+                } for name, value in new_values.items()
+            ]
+        }
+        endpoint = self.current_avg_endpoint + '/component_traces'
+        self.put(endpoint, payload)
+
+    def save_instrument_values(self, new_values):
+        """
+        Post Parameters to the database.
+
+        `new_values`    dictionary {name~>value}
+        """
+        # 13.07.: SCHNELL, SCHNELL (es ist 17 Uhr 57 und ich will die Modbus-instrument
+        #  daten noch hochladen):
+        #  this expects a namedtuple as defined in Modbus client: .set, .act, .par_id
+        if self.current_avg_endpoint is None:
+            raise Exception("create average first")
+    
+        payload = {
+            "quantities": [
+                {
+                    "parameterID": item.par_id,
+                    "setValue": item.set,
+                    "actMean": item.act
+                } for name, item in new_values.items()
+            ]
+        }
+        endpoint = self.current_avg_endpoint + '/parameter_traces'  # on the DB it's called parameter... :\
+        self.put(endpoint, payload)
+

pytrms-0.9.0/pytrms/clients/dirigent.py

@@ -0,0 +1,169 @@
+import os
+import json
+from contextlib import contextmanager
+import logging
+
+import requests
+
+from . import ionitof_url
+
+log = logging.getLogger()
+
+
+class Template:
+    '''A template for uploading a collection item.
+
+    >>> t = Template()
+    >>> t.template == Template.default_template
+    True
+
+    >>> t.render('AME_FooNumber', 42)
+    '{"template": {"data": [{"name": "ParaID", "value": "AME_FooNumber", "prompt": "the
+        parameter ID"}, {"name": "ValAsString", "value": "42", "prompt": "the new value"}]}}'
+
+    '''
+
+    default_template = {
+            "data": [
+                 {"name": "ParaID", "value": "AME_RunNumber", "prompt": "the parameter ID"},
+                 {"name": "ValAsString", "value": "5.000000", "prompt": "the new value"},
+                 {"name": "DataType", "value": "", "prompt": "datatype (int, float, string)"},
+             ]
+         }
+
+    @staticmethod
+    def download(url=ionitof_url, endpoint='/api/schedule'):
+        r = requests.get(url + endpoint, headers={'accept': 'application/vnd.collection+json'})
+        r.raise_for_status()
+        j = r.json()
+
+        return Template(j["collection"]["template"])
+
+    def __init__(self, template=None):
+        if template is None:
+            template = Template.default_template
+        self.template = dict(template)
+
+        self._inserts = dict()  # cache data-items sorted by semantic meaning..
+        for insert in self.template["data"]:
+            if 'ID' in insert["name"] or 'parameter' in insert["prompt"]:
+                self._inserts["parID"] = insert
+            if 'set' in insert["name"].lower() or 'value' in insert["prompt"]:
+                self._inserts["value"] = insert
+            if 'typ' in insert["name"].lower() or 'datatype' in insert["prompt"]:
+                self._inserts["dtype"] = insert
+
+        assert len(self._inserts) == 3, "missing or unknown name in template"
+
+    def render(self, parID, value):
+        """Prepare a request for uploading."""
+        dtype = 'float'
+        if isinstance(value, int): dtype = 'int'
+        if isinstance(value, str): dtype = 'string'
+
+        parID_insert = dict(self._inserts["parID"])
+        value_insert = dict(self._inserts["value"])
+        dtype_insert = dict(self._inserts["dtype"])
+
+        parID_insert.update(value=str(parID)),
+        value_insert.update(value=str(value)),
+        dtype_insert.update(value=str(dtype)),
+
+        return json.dumps({
+            "template": dict(data=[
+                parID_insert,
+                value_insert,
+                dtype_insert,
+            ])}
+        )
+
+    def render_many(self, new_values):
+        for key, value in new_values.items():
+            yield self.render(key, value)
+
+
+class Dirigent:
+
+    def __init__(self, url=ionitof_url, template=None):
+        if template is None:
+            template = Template.download(url)
+
+        self.url = url
+        self.template = template
+        self._session = None  # TODO :: ?
+
+    def push(self, parID, new_value, future_cycle):
+        uri = self.url + '/api/schedule/' + str(int(future_cycle))
+        payload = self.template.render(parID, new_value)
+        r = self._make_request('PUT', uri, payload=payload)
+
+        return r.status_code
+
+    def push_filename(self, path, future_cycle):
+        return self.push('ACQ_SRV_SetFullStorageFile', path.replace('/', '\\'), future_cycle - 2)
+
+    def find_scheduled(self, parID):
+        uri = self.url + '/api/schedule/search'
+        r = self._make_request('GET', uri, params={'name': str(parID)})
+        j = r.json()
+
+        return [item['href'].split('/')[-1] for item in j['collection']['items']]
+
+    def _make_request(self, method, uri, params=None, payload=None):
+        if self._session is None:
+            session = requests  # not using a session..
+        else:
+            session = self._session
+
+        try:
+            r = session.request(method, uri, params=params, data=payload, headers={
+                'content-type': 'application/vnd.collection+json'
+            })
+        except requests.exceptions.ConnectionError as exc:
+            # Note: the LabVIEW-webservice seems to implement a weird HTTP:
+            #  we may get a [85] Custom Error (Bad status line) from urllib3
+            #  even though we just mis-spelled a parameter-ID ?!
+            log.error(exc)
+            raise KeyError(str(params, payload))
+
+        log.debug(f"request to <{uri}> returned [{r.status_code}]")
+        if not r.ok and payload:
+            log.error(payload)
+        r.raise_for_status()
+
+        return r
+
+    def wait_until(self, future_cycle):
+        if self._session is None:
+            session = requests  # not using a session..
+        else:
+            session = self._session
+
+        r = session.get(self.url + '/api/timing/' + str(int(future_cycle)))
+        # ...
+        if r.status_code == 410:
+            # 410 Client Error: Gone 
+            log.warning("we're late, better return immediately!")
+            return r.status_code
+    
+        r.raise_for_status()
+        log.debug(f"waited until {r.json()['TimeCycle']}")
+
+        return r.status_code
+
+    @contextmanager
+    def open_session(self):
+        '''open a session for faster upload (to be used as a contextmanager).'''
+        if self._session is None:
+            self._session = requests.Session()
+        try:
+            yield self
+        finally:
+            self._session.close()
+            self._session = None
+
+
+if __name__ == '__main__':
+    import doctest
+    doctest.testmod(verbose=True, optionflags=doctest.ELLIPSIS)
+