pytrms 0.9.7__py3-none-any.whl → 0.9.8__py3-none-any.whl

pytrms/__init__.py

@@ -1,8 +1,52 @@
-_version = '0.9.7'
+_version = '0.9.8'
+
+import logging
+from functools import wraps
+
+_logging_getLogger = logging.getLogger
+
+@wraps(_logging_getLogger)
+def getLoggerWithAnnouncement(name=None):
+    # patch the (global) logger to print its own name
+    #  (useful for turning individual loggers on/off)
+    # WARNING: this will patch every instance of the
+    #  logging-module in every import after pytrms is
+    #  imported! don't be overwhelmingly fancy with this!
+    rv = _logging_getLogger(name)
+    if name is not None:
+        rv.debug(f"'acquired logger for '{name}'")
+
+    return rv
+
+logging.getLogger = getLoggerWithAnnouncement
+logging.TRACE = 5  # even more verbose than logging.DEBUG
 
 __all__ = ['load', 'connect']
 
 
+def enable_extended_logging(log_level=logging.DEBUG):
+    '''make output of http-requests more talkative.
+
+    set 'log_level=logging.TRACE' for highest verbosity!
+    '''
+    if log_level <= logging.DEBUG:
+        # enable logging of http request urls on the library, that is
+        #  underlying the 'requests'-package:
+        logging.warning(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.warning(f"enabling logging-output on 'HTTPConnection' ({log_level = })")
+        from http.client import HTTPConnection
+        HTTPConnection.debuglevel = 1
+
+
 def load(path):
     '''Open a datafile for post-analysis or batch processing.
 

pytrms/clients/__init__.py

@@ -1,33 +1,9 @@
 import os
 
+from .. import enable_extended_logging
+
 _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 = 5  # even more verbose than logging.DEBUG
-
-def enable_extended_logging(log_level=_logging.DEBUG):
-    '''make output of http-requests more talkative.
-
-    set 'log_level=_logging.TRACE' for highest verbosity!
-    '''
-    if log_level <= _logging.DEBUG:
-        # enable logging of http request urls on the library, that is
-        #  underlying the 'requests'-package:
-        _logging.warning(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.warning(f"enabling logging-output on 'HTTPConnection' ({log_level = })")
-        from http.client import HTTPConnection
-        HTTPConnection.debuglevel = 1
-

pytrms/clients/db_api.py

@@ -1,21 +1,53 @@
 import os
+import time
 import json
+import logging
+from collections import namedtuple
+import urllib3.util
 
 import requests
+import requests.adapters
+import requests.exceptions
 
-from . import _logging
 from .ssevent import SSEventListener
 from .._base import _IoniClientBase
 
-log = _logging.getLogger(__name__)
+log = logging.getLogger(__name__)
+
+_unsafe = namedtuple('http_response', ['status_code', 'href'])
+
+__all__ = ['IoniConnect']
 
 
 class IoniConnect(_IoniClientBase):
 
+    # Note: this retry-policy is specifically designed for the
+    #  SQLite Error 5: 'database locked', which may take potentially
+    #  minutes to resolve itself! Therefore, it is extra generous
+    #  and backs off up to `3.0 * 2^4 = 48 sec` between retries for
+    #  a total of ~1 1/2 minutes (plus database timeout). But, giving
+    #  up on retrying here, would mean *losing all data* in the queue!
+    #    ==>> We would rather crash on a `queue.full` exception! <<==
+    _retry_policy = urllib3.util.Retry(
+        # this configures policies on each cause for errors individually...
+        total=None,             # max. retries (takes precedence). `None`: turned off
+        connect=0, read=0, redirect=0,  # (all turned off, see docs for details)
+        other=0,                # "other" errors include timeout (set to 27 seconds)
+        # configure the retries on specific status-codes...
+        status=5,               # how many times to retry on bad status codes
+        raise_on_status=True,   # `True`: do not return a 429 status code
+        status_forcelist=[429], # integer status-codes to retry on
+        allowed_methods=None,   # `None`: retry on all (possibly not idempotent) verbs
+        # this configures backoff between retries...
+        backoff_factor=3.0,     # back off *after* first try in seconds (x 2^n_retries)
+        respect_retry_after_header=False,  # would override `backoff_factor`, turn off!
+    )
+
     @property
     def is_connected(self):
         '''Returns `True` if connection to IoniTOF could be established.'''
         try:
+            assert self.session is not None, "not connected"
             self.get("/api/status")
             return True
         except:
@@ -24,88 +56,223 @@ class IoniConnect(_IoniClientBase):
     @property
     def is_running(self):
         '''Returns `True` if IoniTOF is currently acquiring data.'''
-        # TODO :: /api/meas/curretn {isRunning ?}
-        raise NotImplementedError("is_running")
+        try:
+            assert self.session is not None, "not connected"
+            self.get_location("/api/measurements/current")
+            return True
+        except (AssertionError, requests.exceptions.HTTPError):
+            return False
 
-    def connect(self, timeout_s):
-        # TODO :: create session ?! (see __init__ ...)
-        pass
+    def connect(self, timeout_s=10):
+        self.session = requests.sessions.Session()
+        self.session.mount('http://',  self._http_adapter)
+        self.session.mount('https://', self._http_adapter)
+        started_at = time.monotonic()
+        while timeout_s is None or time.monotonic() < started_at + timeout_s:
+            try:
+                self.current_meas_loc = self.get_location("/api/measurements/current")
+                break
+            except requests.exceptions.HTTPError:
+                # OK, no measurement running..
+                self.current_meas_loc = ''
+                break
+            except Exception:
+                pass
+
+            time.sleep(10e-1)
+        else:
+            self.session = self.current_meas_loc = None
+            raise TimeoutError(f"no connection to '{self.url}'");
 
     def disconnect(self):
-        # TODO :: del session ?!
-        pass
+        if self.session is not None:
+            del self.session
+            self.session = None
+            self.current_meas_loc = None
 
     def start_measurement(self, path=None):
         '''Start a new measurement and block until the change is confirmed.
 
         If 'path' is not None, write to the given .h5 file.
         '''
-        # TODO :: POST /api/measurement {recipeDirectory}  / path = ?
-        pass
+        assert not self.is_running, "measurement already running @ " + str(self.current_meas_loc)
+
+        payload = {}
+        if path is not None:
+            assert os.path.isdir(path), "must point to a (recipe-)directory: " + str(path)
+            payload |= { "recipeDirectory": str(path) }
+
+        self.current_meas_loc = self.post("/api/measurements", payload)
+        self.put(self.current_meas_loc, { "isRunning": True })
+
+        return self.current_meas_loc
 
     def stop_measurement(self, future_cycle=None):
         '''Stop the current measurement and block until the change is confirmed.
 
         If 'future_cycle' is not None and in the future, schedule the stop command.
         '''
-        # TODO :: PUT /api/meas/current {isRunning = False}
-        pass
+        loc = self.current_meas_loc or self.get_location("/api/measurements/current")
+        self.patch(loc, { "isRunning": False })
+        self.current_meas_loc = ''
 
-    def __init__(self, host='127.0.0.1', port=5066, session=None):
+    def __init__(self, host='127.0.0.1', port=5066):
         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()
+        self._http_adapter = requests.adapters.HTTPAdapter(max_retries=self._retry_policy)
+        self.session = None
+        self.current_meas_loc = None
+        try:
+            self.connect(timeout_s=3.3)
+        except TimeoutError:
+            log.warning("no connection! make sure the DB-API is running and try again")
 
     def get(self, endpoint, **kwargs):
-        return self._get_object(endpoint, **kwargs).json()
+        """Make a GET request to `endpoint` and parse JSON if applicable."""
+        try:
+            r = self._fetch_object(endpoint, 'get', **kwargs)
+            if 'json' in r.headers.get('content-type', ''):
+                return r.json()
+            if 'text' in r.headers.get('content-type', ''):
+                return r.text
+            else:
+                log.warning(f"unexpected 'content-type: {r.headers['content-type']}'")
+                log.info(f"did you mean to use `{type(self).__name__}.download(..)` instead?")
+                return r.content
+
+        except requests.exceptions.HTTPError as e:
+            if e.response.status_code == 410:  # Gone
+                log.debug(f"nothing there at '{endpoint}' 0_o ?!")
+                return None
+            raise
+
+    def get_location(self, endpoint, **kwargs):
+        """Returns the actual location that `endpoint` points to (may be a redirect)."""
+        r = self._fetch_object(endpoint, 'get', **(kwargs | { "allow_redirects": False }))
+        return r.headers.get('Location', r.request.path_url)
 
     def post(self, endpoint, data, **kwargs):
-        return self._create_object(endpoint, data, 'post', **kwargs).headers.get('Location')
+        """Append to the collection at `endpoint` the object defined by `data`."""
+        r = self._create_object(endpoint, data, 'post', **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', ''))  # no default location known!
 
     def put(self, endpoint, data, **kwargs):
-        return self._create_object(endpoint, data, 'put', **kwargs).headers.get('Location')
+        """Replace the entire object at `endpoint` with `data`."""
+        r = self._create_object(endpoint, data, 'put', **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
+
+    def patch(self, endpoint, data, **kwargs):
+        """Change parts of the object at `endpoint` with fields in `data`."""
+        r = self._create_object(endpoint, data, 'patch', **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
+
+    def delete(self, endpoint, **kwargs):
+        """Attempt to delete the object at `endpoint`."""
+        r = self._fetch_object(endpoint, data, 'delete', **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
+
+    def link(self, parent_ep, child_ep, **kwargs):
+        """Make the object at `parent_e[nd]p[oint]` refer to `child_e[nd]p[oint]`"""
+        r = self._make_link(parent_ep, child_ep, sever=False, **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
+
+    def unlink(self, parent_ep, child_ep, **kwargs):
+        """Destroy the reference from `parent_e[nd]p[oint]` to `child_e[nd]p[oint]`"""
+        r = self._make_link(parent_ep, child_ep, sever=True, **kwargs)
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
 
     def upload(self, endpoint, filename):
+        """Upload the file at `filename` to `endpoint`."""
         if not endpoint.startswith('/'):
             endpoint = '/' + endpoint
-        with open(filename) as f:
+        with open(filename, 'rb') 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 = self._create_object(endpoint, None, 'post',
+                    # Note: the requests library will set the content-type automatically
+                    #  and also add a randomly generated "boundary" to separate files:
+                    #headers={'content-type': 'multipart/form-data'}, No!
+                    files=[(name, (filename, f, ''))])
             r.raise_for_status()
 
-        return r
+        return _unsafe(r.status_code, r.headers.get('Location', r.request.path_url))
 
-    def _get_object(self, endpoint, **kwargs):
+    def download(self, endpoint, out_file='.'):
+        """Download from `endpoint` into `out_file` (may be a directory).
+
+        Returns:
+            status_code, actual_filename
+        """
+        if not endpoint.startswith('/'):
+            endpoint = '/' + endpoint
+
+        out_file = os.path.abspath(out_file)
+
+        content_type = 'application/octet-stream'
+        r = self._fetch_object(endpoint, 'get', stream=True, headers={'accept': content_type})
+        assert r.headers['content-type'] == content_type, "unexcepted content-type"
+
+        content_dispo = r.headers['content-disposition'].split('; ')
+        #['attachment',
+        # 'filename=2025_10_06__13_23_32.h5',
+        # "filename*=UTF-8''2025_10_06__13_23_32.h5"]
+        filename = next(
+            (dispo.split('=')[1] for dispo in content_dispo if dispo.startswith("filename="))
+            , None)
+        if os.path.isdir(out_file):
+            assert filename, "no out_file given and server didn't supply filename"
+            out_file = os.path.join(out_file, filename)
+
+        with open(out_file, mode='xb') as f:
+            # chunk_size must be of type int or None. A value of None will
+            # function differently depending on the value of `stream`.
+            # stream=True will read data as it arrives in whatever size the
+            # chunks are received. If stream=False, data is returned as
+            # a single chunk.
+            for chunk in r.iter_content(chunk_size=None):
+                f.write(chunk)
+            r.close()
+
+        return _unsafe(r.status_code, out_file)
+
+    def _fetch_object(self, endpoint, method='get', **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'})
+            kwargs['headers'] = {'accept': 'application/json'}
+        elif 'accept' not in (k.lower() for k in kwargs['headers']):
+            kwargs['headers'].update({'accept': 'application/json'})
         if 'timeout' not in kwargs:
             # https://requests.readthedocs.io/en/latest/user/advanced/#timeouts
             kwargs['timeout'] = (6.06, 27)
-        r = self.session.request('get', self.url + endpoint, **kwargs)
+        r = self.session.request(method, self.url + endpoint, **kwargs)
         r.raise_for_status()
-        
+
+        return r
+
+    def _make_link(self, parent_href, child_href, *, sever=False, **kwargs):
+        verb = "LINK" if not sever else "UNLINK"
+        if 'timeout' not in kwargs:
+            # https://requests.readthedocs.io/en/latest/user/advanced/#timeouts
+            kwargs['timeout'] = (6.06, 27)
+        r = self.session.request(verb, self.url + parent_href,
+                headers={"location": child_href}, **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, ensure_ascii=False)  # default is `True`, escapes Umlaute!
-        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'})
+        if data is not None:
+            if not isinstance(data, str):
+                # Note: default is `ensure_ascii=True`, but this escapes Umlaute!
+                data = json.dumps(data, ensure_ascii=False)
+            if 'headers' not in kwargs:
+                kwargs['headers'] = {'content-type': 'application/json'}
+            elif 'content-type' not in (k.lower() for k in kwargs['headers']):
+                kwargs['headers'].update({'content-type': 'application/json'})
         if 'timeout' not in kwargs:
             # https://requests.readthedocs.io/en/latest/user/advanced/#timeouts
             kwargs['timeout'] = (6.06, 27)
@@ -122,8 +289,9 @@ class IoniConnect(_IoniClientBase):
         from operator import attrgetter
 
         # Note: the DB-API distinguishes between peaks with 
-        #  different center *and* name, so this is our key:
-        make_key = lambda peak: (peak['center'], peak['name'])
+        #  different center *and* name, while the PyTRMS 'Peak'
+        #  only distinguishes by center, so this is our key:
+        make_key = lambda p_info: (p_info['center'], p_info['name'])
 
         if isinstance(peaktable, str):
             log.info(f"loading peaktable '{peaktable}'...")
@@ -147,55 +315,74 @@ class IoniConnect(_IoniClientBase):
             updates[make_key(payload)] = {'payload': payload}
 
         log.info(f"fetching current peaktable from the server...")
+        pt_server = self.get('/api/peaks')['_embedded']['peaks']
         # create a comparable collection of peaks already on the database by
         # reducing the keys in the response to what we actually want to update:
         db_peaks = {make_key(p): {
-                    'payload': {k: p[k] for k in conv.keys()},
-                    'self':   p['_links']['self'],
-                    'parent': p['_links'].get('parent'),
+                        'payload': {k: p[k] for k in conv.keys()},
+                        'self':   p['_links']['self'],
+                        'parent': p['_links'].get('parent'),
                     } for p in self.get('/api/peaks')['_embedded']['peaks']}
 
         to_update = updates.keys() & db_peaks.keys()
         to_upload = updates.keys() - db_peaks.keys()
-        updated = 0
+        updated = up_to_date = 0
         for key in sorted(to_update):
             # check if an existing peak needs an update
             if db_peaks[key]['payload'] == updates[key]['payload']:
                 # nothing to do..
                 log.debug(f"up-to-date: {key}")
-                continue
-
-            self.put(db_peaks[key]['self']['href'], updates[key]['payload'])
-            log.info(f"updated:    {key}")
-            updated += 1
+                up_to_date += 1
+            else:
+                self.put(db_peaks[key]['self']['href'], updates[key]['payload'])
+                log.info(f"updated:    {key}")
+                updated += 1
 
         if len(to_upload):
             # Note: POSTing the embedded-collection is *miles faster*
             #  than doing separate requests for each peak!
-            payload = {'_embedded': {'peaks': [updates[key]['payload'] for key in sorted(to_upload)]}}
+            payload = {
+                '_embedded': {
+                    'peaks': [updates[key]['payload']
+                              for key in sorted(to_upload)]
+                }
+            }
             self.post('/api/peaks', payload)
             for key in sorted(to_upload):
                 log.info(f"added new:  {key}")
+            # Note: we need the updated peaktable to learn about 
+            #  the href (id) assigned to newly added peaks:
+            pt_server = self.get('/api/peaks')['_embedded']['peaks']
+
+        log.info("repairing fitpeak~>nominal links...")
+        peak2href = {
+            Peak(p["center"], label=p["name"]): p["_links"]["self"]["href"]
+            for p in pt_server
+        }
+        to_link = set((peak2href[fitted], peak2href[fitted.parent])
+            for fitted in peaktable.fitted)
+
+        is_link = set((child["_links"]["self"]["href"], child["_links"]["parent"]["href"])
+            for child in pt_server if "parent" in child["_links"])
+
+        for child_href, parent_href in is_link & to_link:
+            log.debug(f"keep link  {parent_href} <~> {child_href}")
+            pass
+
+        for child_href, parent_href in to_link - is_link:
+            log.debug(f"make link  {parent_href} ~>> {child_href}")
+            self.link(parent_href, child_href)
 
-        if len(peaktable.fitted):
-            # Note: until now, we disregarded the peak-parent-relationship, so
-            # make another request to the updated peak-table from the server...
-            peak2href = {Peak(center=p["center"], label=p["name"]): p["_links"]["self"]["href"]
-                            for p in self.get('/api/peaks')['_embedded']['peaks']}
-
-            for fitted in peaktable.fitted:
-                fitted_href = peak2href[fitted]
-                parent_href = peak2href[fitted.parent]
-                r = self.session.request('link', self.url + parent_href, headers={"location": fitted_href})
-                if not r.ok:
-                    log.error(f"LINK {parent_href} to Location: {fitted_href} failed\n\n[{r.status_code}]: {r.content}")
-                    r.raise_for_status()
-                log.debug(f"linked parent {parent_href} ~> {fitted_href}")
+        for child_href, parent_href in is_link - to_link:
+            log.debug(f'break link {parent_href} ~x~ {child_href}')
+            self.unlink(parent_href, child_href)
 
         return {
                 'added': len(to_upload),
                 'updated': updated,
-                'up-to-date': len(to_update) - updated,
+                'up-to-date': up_to_date,
+                'linked': len(to_link - is_link),
+                'unlinked': len(is_link - to_link),
         }
 
     def iter_events(self, event_re=r".*"):

pytrms/clients/dummy.py

@@ -1,7 +1,8 @@
-from . import _logging
+import logging
+
 from .._base import _IoniClientBase
 
-log = _logging.getLogger(__name__)
+log = logging.getLogger(__name__)
 
 
 class IoniDummy(_IoniClientBase):
@@ -21,7 +22,7 @@ class IoniDummy(_IoniClientBase):
 
     __is_running = False
 
-    def connect(self, timeout_s):
+    def connect(self, timeout_s=0):
         log.info(f'pretending to connect to server')
         self.__is_connected = True
 
@@ -37,7 +38,7 @@ class IoniDummy(_IoniClientBase):
         log.info(f'pretending to stop measurement ({future_cycle = })')
         self.__is_running = False
 
-    def __init__(self, host='localhost', port=5687):
+    def __init__(self, host='localhost', port=1234):
         super().__init__(host, port)
         self.connect()
 

pytrms/clients/mqtt.py

@@ -2,18 +2,18 @@ import os
 import time
 import json
 import queue
+import logging
 from collections import deque, namedtuple
 from datetime import datetime
 from functools import wraps
 from itertools import cycle, chain, zip_longest
 from threading import Condition, RLock
 
-from . import _logging
 from . import _par_id_file
 from .._base import itype, _MqttClientBase, _IoniClientBase
 
 
-log = _logging.getLogger(__name__)
+log = logging.getLogger(__name__)
 
 __all__ = ['MqttClient']
 
@@ -22,12 +22,6 @@ with open(_par_id_file) as f:
     from pandas import read_csv, isna
 
     _par_id_info = read_csv(f, sep='\t').drop(0).set_index('Name').fillna('')
-    if isna(_par_id_info.at['MPV_1', 'Access']):
-        log.warning(f'filling in read-properties still missing in {os.path.basename(_par_id_file)}')
-        _par_id_info.at['MPV_1', 'Access'] = 'RW'
-        _par_id_info.at['MPV_2', 'Access'] = 'RW'
-        _par_id_info.at['MPV_3', 'Access'] = 'RW'
-
 
 
 ## >>>>>>>>    adaptor functions    <<<<<<<< ##

pytrms/clients/ssevent.py

@@ -1,15 +1,16 @@
 import re
+import time
+import logging
 from collections import namedtuple
 from collections.abc import Iterable
 
 import requests
 
-from . import _logging
-
-log = _logging.getLogger(__name__)
+log = logging.getLogger(__name__)
 
 _event_rv = namedtuple('ssevent', ['event', 'data'])
 
+
 class SSEventListener(Iterable):
 
     @staticmethod
@@ -29,7 +30,6 @@ class SSEventListener(Iterable):
             self._get = session.get
         else:
             self._get = requests.get
-        self._connect_response = None
         self.subscriptions = set()
         if event_re is not None:
             self.subscribe(event_re)
@@ -37,46 +37,75 @@ class SSEventListener(Iterable):
     def subscribe(self, event_re):
         """Listen for events matching the given string or regular expression."""
         self.subscriptions.add(re.compile(event_re))
-        if self._connect_response is None:
-            r = self._get(self.uri, headers={'accept': 'text/event-stream'}, stream=True)
-            if not r.ok:
-                log.error(f"no connection to {self.uri} (got [{r.status_code}])")
-                r.raise_for_status()
-
-            self._connect_response = r
 
     def unsubscribe(self, event_re):
         """Stop listening for certain events."""
         self.subscriptions.remove(re.compile(event_re))
-        if not len(self.subscriptions):
-            log.debug(f"closing connection to {self.uri}")
-            self._connect_response.close()
-            self._connect_response = None
 
-    def __iter__(self):
-        if self._connect_response is None:
+    def follow_events(self, timeout_s=None, prime=False):
+        """Returns a generator that produces events as soon as they are emitted.
+
+        When `timeout_s` is given, a hard timeout is set, after which the stream
+        is closed and the generator raises `StopIteration`. This makes it possible
+        to e.g. collect events into a list or test for an event to occur.
+
+        With `prime=True` the first (pseudo-)event will be generated immediately
+        after the connection has been made. The event type is 'new connection'.
+
+        _Note_: The timeout cannot be accurate, because the `requests` library only
+         allows to check the timeout when either an event or a keep-alive is received!
+         This may take up to 13 seconds (currently set on the API). Also, the last
+         event may be discarded.
+
+        `iter(<instance>)` calls this method with `timeout_s=None`.
+        """
+        if not len(self.subscriptions):
             raise Exception("call .subscribe() first to listen for events")
 
+        log.debug(f"opening connection to {self.uri}")
+        _response = self._get(self.uri, headers={'accept': 'text/event-stream'}, stream=True)
+        if not _response.ok:
+            log.error(f"no connection to {self.uri} (got [{_response.status_code}])")
+            _response.raise_for_status()
+
+        if prime:
+            yield _event_rv('new connection', '/api/status')
+
+        started_at = time.monotonic()
         event = msg = ''
-        for line in self._line_stream(self._connect_response):  # blocks...
-            if not line:
-                # an empty line concludes an event
-                if event and any(re.match(sub, event) for sub in self.subscriptions):
-                    yield _event_rv(event, msg)
-
-                # Note: any further empty lines are ignored (may be used as keep-alive),
-                #  but in either case clear event and msg to rearm for the next event:
-                event = msg = ''
-                continue
-
-            key, val = line.split(':', maxsplit=1)
-            if not key:
-                # this is a comment, starting with a colon ':' ...
-                log.log(_logging.TRACE, "sse:" + val)
-            elif key == 'event':
-                event = val.lstrip()
-            elif key == 'data':
-                msg += val.lstrip()
-            else:
-                log.warning(f"unknown SSE-key <{key}> in stream")
+        try:
+            for line in self._line_stream(_response):  # blocks...
+                elapsed_s = time.monotonic() - started_at
+                if timeout_s is not None and elapsed_s > timeout_s:
+                    log.debug(f"no more events after {round(elapsed_s)} seconds")
+                    return  # (raises StopIteration)
+
+                if not line:
+                    # an empty line concludes an event
+                    if event and any(re.match(sub, event) for sub in self.subscriptions):
+                        yield _event_rv(event, msg)
+
+                    # Note: any further empty lines are ignored (may be used as keep-alive),
+                    #  but in either case clear event and msg to rearm for the next event:
+                    event = msg = ''
+                    continue
+
+                key, val = line.split(':', maxsplit=1)
+                if not key:
+                    # this is a comment, starting with a colon ':' ...
+                    log.log(logging.TRACE, "sse:" + val)
+                elif key == 'event':
+                    event = val.lstrip()
+                elif key == 'data':
+                    msg += val.lstrip()
+                else:
+                    log.warning(f"unknown SSE-key <{key}> in stream")
+        finally:
+            _response.close()
+            log.debug(f"closed connection to {self.uri}")
+
+    def __iter__(self):
+        g = self.follow_events(timeout_s=None, prime=True)
+        assert next(g).event == 'new connection', "invalid program: pseude-event expected"
+        yield from g
 

pytrms/data/ParaIDs.csv

@@ -69,9 +69,9 @@ ID	Name	DataType	Access	ServerName	LVWriteQueueName	SharedVariable	PrettyName	Un
 67	MPV_Dir_1	I32		PTR	PTR_Write		MPV Dir		
 68	MPV_Dir_2	I32		PTR	PTR_Write		MPV Dir2		
 69	MPV_Dir_3	I32		PTR	PTR_Write		MPV Dir3		
-70	MPV_1			PTR	PTR_Write		MPValve1		
-71	MPV_2			PTR	PTR_Write		MPValve2		
-72	MPV_3			PTR	PTR_Write		MPValve3		
+70	MPV_1		RW	PTR	PTR_Write		MPValve1		
+71	MPV_2		RW	PTR	PTR_Write		MPValve2		
+72	MPV_3		RW	PTR	PTR_Write		MPValve3		
 73	DPS_Uf	DBL	RW	PTR	PTR_Write		Uf	V	
 74	DPS_U1	DBL	RW	PTR	PTR_Write		UF1	V	
 75	DPS_U2	DBL	RW	PTR	PTR_Write		UF2	V	

pytrms/instrument.py

@@ -1,11 +1,12 @@
+"""
+@file instrument.py
+
+"""
 import os.path
 import time
 from abc import abstractmethod, ABC
 
-from .measurement import (
-        RunningMeasurement,
-        FinishedMeasurement,
-)
+from ._base import _IoniClientBase
 
 __all__ = ['Instrument']
 
@@ -14,13 +15,35 @@ class Instrument(ABC):
     '''
     Class for controlling the PTR instrument remotely.
 
-    This class reflects the states of the actual instrument, which can be currently idle
-    or running a measurement. An idle instrument can start a measurement. A running
-    instrument can be stopped. But trying to start a measurement twice will raise an
-    exception (RuntimeError).
+    This class reflects the states of the actual instrument, which can be currently
+    either idle or running. A idle instrument can start a measurement. A running
+    instrument can be stopped.
+
+    The `Instrument` class wraps a `backend`. For testing purposes, we use a mock:
+    >>> from pytrms.clients import dummy
+    >>> backend = dummy.IoniDummy()
+
+    Note, that for every client PTR instrument there is only one instance of this class
+     (this is to prevent different instances to be in other states than the instrument).
+
+    >>> ptr = Instrument(backend)
+    >>> ptr
+    <_IdleInstrument [<IoniDummy @ 127.0.0.1[:1234]>]>
+
+    >>> id(ptr) == id(Instrument(dummy.IoniDummy()))  # singleton ID is always the same
+    True
+
+    Trying to start an instrument twice will raise a RuntimeError!
+
+    >>> ptr.start_measurement(filename='foo %y %M')
+    >>> ptr.is_running
+    True
+
+    >>> ptr.start_measurement()
+    Traceback (most recent call last):
+        ...
+    RuntimeError: can't start <_RunningInstrument>
 
-    Note, that for every client PTR instrument there is only one instance of this class.
-    This is to prevent different instances to be in other states than the instrument.
     '''
     __instance = None
 
@@ -28,7 +51,7 @@ class Instrument(ABC):
         # Note: we get ourselves a nifty little state-machine :)
         self.__class__ = newstate
 
-    def __new__(cls, backend):
+    def __new__(cls, *args, **kwargs):
         # Note (reminder): If __new__() does not return an instance of cls,
         #  then the new instance’s __init__() method will *not* be invoked!
         #
@@ -38,6 +61,9 @@ class Instrument(ABC):
         if cls._Instrument__instance is not None:
             return cls._Instrument__instance
 
+        backend = args[0]  # fetch it from first argument (passed to __init__)
+        assert isinstance(backend, (_IoniClientBase)), f"backend must implement {type(_IoniClientBase)}"
+
         if backend.is_running:
             inst = object.__new__(_RunningInstrument)
         else:
@@ -47,9 +73,9 @@ class Instrument(ABC):
 
         return inst
 
-    def __init__(self, backend):
-        # Note: this will be called *once* per Python process!
-        self.backend = backend
+    @property
+    def is_running(self):
+        return type(self) is _RunningInstrument
 
     @property
     def is_local(self):
@@ -57,6 +83,13 @@ class Instrument(ABC):
         host = str(self.backend.host)
         return 'localhost' in host or '127.0.0.1' in host
 
+    def __init__(self, backend):
+        # Note: this will be called *once* per Python process! see __new__() method.
+        self.backend = backend
+
+    def __repr__(self):
+        return f'<{self.__class__.__name__} [{self.backend}]>'
+
     def get(self, varname):
         """Get the current value of a setting."""
         # TODO :: this is not an interface implementation...
@@ -76,15 +109,29 @@ class Instrument(ABC):
         """Set a variable to a new value."""
         return self.backend.set(varname, value, unit='-')
 
-    _current_sourcefile = ''
-
     def start_measurement(self, filename=''):
+        """Start a new measurement.
+
+        'filename' is the filename of the datafile to write to. If left blank, start
+        a "quick measurement", for which IoniTOF writes to its default folder.
+
+        If pointing to a file and the file exist on the (local) server, this raises
+        an exception! To create unique filenames, use placeholders for year (%Y),
+        month (%m), and so on, for example `filename=D:/Sauerteig_%Y-%m-%d_%H-%M-%S.h5`.
+        The `filename` is passed through `strftime` with the current date and time.
+
+        see also:
+        """
         # this method must be implemented by each state
-        raise RuntimeError("can't start %s" % self.__class__)
+        raise RuntimeError("can't start <%s>" % type(self).__name__)
+
+    # (see also: this docstring)
+    start_measurement.__doc__ += time.strftime.__doc__
 
     def stop_measurement(self):
+        """Stop a running measurement."""
         # this method must be implemented by each state
-        raise RuntimeError("can't stop %s" % self.__class__)
+        raise RuntimeError("can't stop <%s>" % type(self).__name__)
 
 
 class _IdleInstrument(Instrument):
@@ -110,18 +157,12 @@ class _IdleInstrument(Instrument):
                 raise RuntimeError(f'filename exists and cannot be overwritten')
 
         self.backend.start_measurement(filename)
-        self._current_sourcefile = filename
-        self._new_state(RunningInstrument)
-
-        return RunningMeasurement(self)
+        self._new_state(_RunningInstrument)
 
 
 class _RunningInstrument(Instrument):
 
     def stop_measurement(self):
         self.backend.stop_measurement()
-        self._new_state(IdleInstrument)
-
-        # TODO :: this catches only one sourcefile.. it'll do for simple cases:
-        return FinishedMeasurement(self._current_sourcefile)
+        self._new_state(_IdleInstrument)
 

pytrms/peaktable.py

@@ -22,8 +22,7 @@ other custom formats.
 ... [
 ... {"label":"H3O+",
 ...  "center":21.0219,
-...  "formula":"?",
-...  "parent":"?",
+...  "formula":"<unknown>",
 ...  "isotopic_abundance":0.002,
 ...  "k_rate":2.10,
 ...  "multiplier":488
@@ -53,7 +52,7 @@ Peaks may be modified and the PeakTable exported in the same format:
       "center": 21.0219,
       "label": "H3O+",
       "formula": "H3O",
-      "parent": "?",
+      "parent": null,
       "isotopic_abundance": 0.678,
       "k_rate": 2.1,
       "multiplier": 488.0,
@@ -107,7 +106,7 @@ class Peak:
     """
     _exact_decimals = 4
 
-    def __init__(self, center, label='', formula='', parent=None, borders=(),
+    def __init__(self, center, label='', *, formula='', parent=None, borders=(),
                  isotopic_abundance=1.0, k_rate=2.0, multiplier=1.0,
                  resolution=1000, shift=0):
         self.center = round(float(center), ndigits=Peak._exact_decimals)

{pytrms-0.9.7.dist-info → pytrms-0.9.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: pytrms
-Version: 0.9.7
+Version: 0.9.8
 Summary: Python bundle for proton-transfer reaction mass-spectrometry (PTR-MS).
 License: GPL-2.0
 Author: Moritz Koenemann

{pytrms-0.9.7.dist-info → pytrms-0.9.8.dist-info}/RECORD

@@ -1,28 +1,28 @@
-pytrms/__init__.py,sha256=jqpXWWSo2wsyj3kgPz7ppNOmUqCxTuF1NVVdTm8zdMw,1134
+pytrms/__init__.py,sha256=znPgfmjFqRfx_UoKYLhpNTtDlMVqrQc8cmYHwigABaY,2821
 pytrms/_base/__init__.py,sha256=2KUO7R_SPZxsV0Xe_Hy4e2HnQI5zDzOYJc4H7G3ZQpE,850
 pytrms/_base/ioniclient.py,sha256=eTkksDwB8u9i-rnwCGH7o8rXcNbez-QakXLqQFJJCw0,1368
 pytrms/_base/mqttclient.py,sha256=DxETIjK_qIvxCGiHLzHXdvyGcCgiwYfggWlXrxzwpqY,5347
 pytrms/_version.py,sha256=yRCN1kvPaX0FHycK0NBHTluhkf5euj8U7WNTKdVQafg,828
-pytrms/clients/__init__.py,sha256=79EUbgBItW49t8Kjl8HF3d109mTwB2YmEc320RdA3yI,1347
-pytrms/clients/db_api.py,sha256=HsbJsocRt2nkTyFSuiBsLfIyDf_6F4NWCB34-YxZkSw,8627
-pytrms/clients/dummy.py,sha256=Ciyw8kErRpCilNRIdTBtuZ2HS3MLVWTuI4XsnAYPncY,1153
+pytrms/clients/__init__.py,sha256=_IHR-GMeAemtrkeQR5I4lPvO9wVR0pEWuswgdi4Rw0I,263
+pytrms/clients/db_api.py,sha256=ZZuKz1PrWPL5Zu4FFgXY1Ovz7f1Evt_Kt1cDRP51sHs,17488
+pytrms/clients/dummy.py,sha256=BaCAhR30eE-ULu8U0bE-7L_cTdAeWsW0Dn1C_cwiCjw,1147
 pytrms/clients/ioniclient.py,sha256=cp37XSoCzLamjDzcUCrKbp530YMstQ0Eoj81r5tClL8,2390
 pytrms/clients/modbus.py,sha256=Mgxps17amE033P6cCJ5Bv4r8vdWZC2SiyxqfQ7KfEhA,26219
-pytrms/clients/mqtt.py,sha256=S5zZgRE3GST2cVyq3jsoJ-hhQM9U-jErpTn4LxXzrA0,32119
-pytrms/clients/ssevent.py,sha256=guRk7ny43KAB2SYTj6UvocdH786nu31iMFU-SeBob9Q,2946
+pytrms/clients/mqtt.py,sha256=ybtRbKeRfxz2bPOgOtlJDAkCP79fWEu47z7pliZHAKQ,31809
+pytrms/clients/ssevent.py,sha256=zj5LPkIbGm3APOJuol9GPc_A_zsas6gjY-w9sM-LQwo,4354
 pytrms/compose/__init__.py,sha256=hbjX-rzFlBnZpp7OP8edyZAw0r2-im1MtWxQNU8tG_A,28
 pytrms/compose/composition.py,sha256=VU0E50zIdqS4cIzTdMMDxWWCUd5jkLbuPcNAET93oqo,11779
 pytrms/data/IoniTofPrefs.ini,sha256=BGyTijnmtdGqa-kGbAuB1RysG4MPK9nlF9TR069tKwE,1887
-pytrms/data/ParaIDs.csv,sha256=H4ssQixGYvGMcYSdRcycmGbIrO2J8imh6FGwUNsmmM4,27395
+pytrms/data/ParaIDs.csv,sha256=CWOXx83OTmHRgsl39Si35DwND94UnvhdIrkekrnbpNg,27401
 pytrms/helpers.py,sha256=0GhSlX4zwMIQqNx2-G7WrLecoYIG7MVFZb5doODaenA,4985
-pytrms/instrument.py,sha256=jO37ZUlCkItXNzjT9Hh-mx6Eyt4VD4DBQATEiKUEb4M,4432
+pytrms/instrument.py,sha256=x0lBK5O9BBLNdRAZMnc4DGsQSCQe0Lu-WH5pgNGkoDI,5824
 pytrms/measurement.py,sha256=iHsEWmJhCSFxMON_N-5mtCmFqigBqGQM4AImqE7pS44,7629
-pytrms/peaktable.py,sha256=tFRNNJoztV-l28Ml6W0K0qPq-A_BttH7NiRUdt6xzdM,17202
+pytrms/peaktable.py,sha256=w76wPgVARQH8bOppDejpvVHjSDY88ZZYkGBMmgRFmTM,17195
 pytrms/plotting/__init__.py,sha256=sfL4k2PeBmzIf-5Z_2rnkeM8As3psbPxaVvmpi1T48Q,62
 pytrms/plotting/plotting.py,sha256=WzP4Is2PSu_NdhY73HsCU8iEHmLgnIgNY-opsxwIjH8,675
 pytrms/readers/__init__.py,sha256=2r9dXwPRqYkIGpM0EjY-m_Ti3qtxE0jeC9FnudDDoXc,72
 pytrms/readers/ionitof_reader.py,sha256=c8W5aglrY1bmuljnaAqx6TGWAPGXXMkuHjJ1aRw3Wrc,17624
-pytrms-0.9.7.dist-info/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
-pytrms-0.9.7.dist-info/METADATA,sha256=04R29OtNVEqD7vJvBBdZQOFPgGYt9ZkIgNXk4GWtqcU,812
-pytrms-0.9.7.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-pytrms-0.9.7.dist-info/RECORD,,
+pytrms-0.9.8.dist-info/LICENSE,sha256=gXf5dRMhNSbfLPYYTY_5hsZ1r7UU1OaKQEAQUhuIBkM,18092
+pytrms-0.9.8.dist-info/METADATA,sha256=ZA7Pb3jx131IEc0pjISnvg6vpXlmiPdGoIi3Uot7hJM,812
+pytrms-0.9.8.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+pytrms-0.9.8.dist-info/RECORD,,