nucosObs 0.4.18__py3-none-any.whl

nucosObs/__init__.py

@@ -0,0 +1,110 @@
+"""Helper functions and globals used by ``nucosObs``."""
+
+import asyncio as aio
+from .version import version as __version__
+from concurrent.futures import ThreadPoolExecutor
+
+
+class Runtime:
+    """Own the event loop and mutable state for an observer application."""
+
+    def __init__(self, loop=None):
+        self.loop = loop or aio.new_event_loop()
+        self.pool = ThreadPoolExecutor(4)
+        self.allObs = []
+        self.allObservables = []
+        self.debug = [False]
+        self._tasks = set()
+        self._shutdown = False
+
+    def create_task(self, coroutine):
+        """Create and track work owned by this runtime."""
+        task = self.loop.create_task(coroutine)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return task
+
+    async def shutdown(self):
+        """Request observer shutdown and return a structured state report."""
+        open_observers = [observer for observer in self.allObs if not observer.stop]
+        pending_tasks = [task for task in self._tasks if not task.done()]
+        report = {
+            "already_shutdown": self._shutdown,
+            "observers": {
+                "total": len(self.allObs),
+                "open": len(open_observers),
+            },
+            "tasks": {"pending": len(pending_tasks), "cancelled": 0},
+        }
+        if self._shutdown:
+            return report
+
+        self._shutdown = True
+        for observer in self.allObs:
+            observer.stop = True
+            observer.stopSchedule()
+        for observable in self.allObservables:
+            await observable.put({"action": "stop_observer"})
+        for task in pending_tasks:
+            task.cancel()
+        if pending_tasks:
+            await aio.gather(*pending_tasks, return_exceptions=True)
+        report["tasks"]["cancelled"] = len(pending_tasks)
+        return report
+
+    def main_loop(self, ui, test=False):
+        """Run this runtime's observers and optional UI coroutines."""
+        _run_main_loop(self, ui, test)
+
+    def close(self):
+        """Release this runtime's worker pool and event loop."""
+        self.pool.shutdown(wait=False)
+        if not self.loop.is_closed():
+            self.loop.close()
+
+
+pool = ThreadPoolExecutor(4)
+allObs = []
+allObservables = []
+
+# Create a default event loop on import so that modules relying on the loop
+# do not trigger a deprecation warning with ``get_event_loop``.
+loop = aio.new_event_loop()
+aio.set_event_loop(loop)
+debug = [False]
+
+
+def get_all_pending_futures(ui=[]):
+    """Return coroutines for all registered observers and schedules."""
+    obs = [o.observe for o in allObs]
+    schedules = [o.scheduleLoop
+                 for o in allObs if o.schedule_task is not None]
+    return [*ui, *obs, *schedules]
+
+
+def _run_main_loop(runtime, ui, test=False):
+    """Run the event loop with all observers and optional UI coroutines."""
+    # the workers should be closed first
+    obs = [o.observe() for o in runtime.allObs]
+    if runtime.debug[-1]:
+        print([o.name for o in runtime.allObs])
+    schedules = [o.scheduleLoop()
+                 for o in runtime.allObs if o.schedule_task is not None]
+
+    async def run_all():
+        await aio.gather(*ui, *obs, *schedules)
+
+    runtime.loop.run_until_complete(run_all())
+    if runtime.debug[-1] and not test:
+        print("try to close loop")
+    if not test:
+        runtime.loop.close()
+
+
+def main_loop(ui, test=False):
+    """Run the default module runtime with observers and UI coroutines."""
+    _run_main_loop(__import__(__name__), ui, test)
+
+
+# from nucosObs.observable import Observable
+# from nucosObs.observer import BroadcastObserver

nucosObs/__main__.py

@@ -0,0 +1,72 @@
+"""Command-line diagnostics for nucosObs installations."""
+
+import argparse
+import json
+import platform
+from importlib import metadata
+
+import nucosObs
+from nucosObs.version import version
+
+
+def _dependency_version(name):
+    try:
+        return metadata.version(name)
+    except metadata.PackageNotFoundError:
+        return "not installed"
+
+
+def diagnostics():
+    """Return the installed package and default runtime diagnostic state."""
+    return {
+        "package": "nucosObs",
+        "version": version,
+        "python": {
+            "installed": platform.python_version(),
+            "supported": ">=3.11",
+        },
+        "dependencies": {
+            "aiohttp": _dependency_version("aiohttp"),
+            "websockets": _dependency_version("websockets"),
+        },
+        "runtime": {
+            "debug_enabled": bool(nucosObs.debug[-1]),
+            "loop_closed": nucosObs.loop.is_closed(),
+            "observables": len(nucosObs.allObservables),
+            "observers": len(nucosObs.allObs),
+        },
+    }
+
+
+def main():
+    """Print package diagnostics for support and development workflows."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--json", action="store_true", help="print JSON output")
+    args = parser.parse_args()
+    report = diagnostics()
+    if args.json:
+        print(json.dumps(report, sort_keys=True))
+        return
+
+    print(f"{report['package']} {report['version']}")
+    print(
+        "Python: "
+        f"{report['python']['installed']} "
+        f"(supported {report['python']['supported']})"
+    )
+    print(
+        "Dependencies: "
+        f"aiohttp {report['dependencies']['aiohttp']}, "
+        f"websockets {report['dependencies']['websockets']}"
+    )
+    print(
+        "Runtime: "
+        f"observers={report['runtime']['observers']}, "
+        f"observables={report['runtime']['observables']}, "
+        f"loop_closed={report['runtime']['loop_closed']}, "
+        f"debug_enabled={report['runtime']['debug_enabled']}"
+    )
+
+
+if __name__ == "__main__":
+    main()

nucosObs/aiohttpWebsocketInterface.py

@@ -0,0 +1,265 @@
+"""Websocket interface implementation using ``aiohttp``."""
+
+import asyncio as aio
+import inspect
+import secrets
+from aiohttp import web
+import aiohttp
+try:
+    import simplejson as json
+except:
+    import json
+
+try:
+    from nucosCR import random, hexdigest_n
+    isCR = True
+except:
+    import random
+    isCR = False
+
+from nucosObs import loop, debug
+from nucosObs.observer import broadcast
+
+
+def _token(length):
+    if isCR:
+        return random(length).decode()
+    return secrets.token_urlsafe(length)
+
+
+class AiohttpWebsocketInterface(object):
+    """A websocket interface based on ``aiohttp``."""
+    def __init__(self, app, broker, doAuth=False, closeOnClientQuit=False, 
+                    authenticator=None,onCloseCallback=None, heartbeat=None,
+                    closeSanely=None,
+                    receive_timeout=None, sslClient=None, sslServer=None,
+                    route="/ws", backend="default", on_error=None):
+        """Create the interface and register a websocket route."""
+        self.app = app
+        self.onCloseCallback = onCloseCallback
+        self.backend = backend
+        self.ws = {}
+        self.doAuth = doAuth
+        self.closeSanely = closeSanely
+        self.broker = broker
+        self.server = None
+        self.authenticator = authenticator
+        self.nonce = {}
+        self.isAuthenticated = {}
+        self.connectedUser = {}
+        self.isRefused = []
+        self.closeOnClientQuit = closeOnClientQuit
+        self.sslClient = sslClient
+        self.sslServer = sslServer
+        self.client_session = None
+        self.approved = []
+        self.receive_timeout = receive_timeout
+        self.heartbeat = heartbeat
+        self.ids = []
+        self.id_0 = None
+        self.on_error = on_error
+        app.router.add_route('GET', route, self.handler)
+
+    async def _report_error(self, context, error):
+        if self.on_error is not None:
+            result = self.on_error(context, error)
+            if inspect.isawaitable(result):
+                await result
+
+    async def send(self, msg, user):
+        """Send ``msg`` to the websocket connection belonging to ``user``."""
+        id_ = self.connectedUser.get(user)
+        if id_ is None:
+            return
+        else:
+            try:
+                await self.ws[id_].send_str(msg)
+            except Exception as error:
+                await self._report_error("send", error)
+
+    async def send_by_id(self, msg, id_):
+        """
+        """
+        if id_ in self.ws:
+            await self.ws[id_].send_str(msg)
+
+    async def send_by_client(self, msg, client):
+        """
+        client is the numbering
+        wait until connected
+        """
+        while True:
+            try:
+                id_ = self.ids[client]
+                break
+            except:
+                # print("SEND failed", self.ids, client, msg)
+                await aio.sleep(0.2)
+        await self.ws[id_].send_str(msg)
+    async def broadcast(self, msg):
+        """Send ``msg`` to all connected websocket clients."""
+        for id_, ws in self.ws.items():
+            try:
+                await ws.send_str(msg)
+            except Exception as error:
+                await self._report_error("broadcast", error)
+
+    async def connect(self, host, port):
+        """Connect to a remote websocket server."""
+        if debug[-1]:
+            print("try to start client")
+        # self.server = await websockets.connect(self.handler, ip, port)
+        if self.sslClient:
+            protocol = "wss"
+        else:
+            protocol = "ws"
+        self.client_session = aiohttp.ClientSession()
+        options = {}
+        if self.sslClient is not None:
+            options["ssl"] = self.sslClient
+        websocket = await self.client_session.ws_connect(
+            '%s://%s:%s' % (protocol, host, str(port)), **options
+        )
+        self.ws['client'] = websocket
+        await self.listener(websocket, 'client')
+
+
+    async def handler(self, request):
+        """Handle incoming websocket upgrade requests."""
+        ws = web.WebSocketResponse(heartbeat=self.heartbeat)
+        await ws.prepare(request)
+        id_ =  ws.headers.get("Sec-Websocket-Accept")
+        self.ws.update({id_: ws})
+        self.id_0 = id_
+        self.ids.append(id_)  # store the first connection for easier reference
+        if debug[-1]:
+            print("Partner connected")     
+            print(self.ws)   
+        if self.doAuth:
+            self.nonce[id_] = _token(24)
+            context = {"name": "doAuth",
+                       "args": {"nonce": self.nonce[id_], "id": id_},
+                       "action": "authenticate",
+                       "backend": self.backend}
+            await ws.send_str(json.dumps(context)) #or send_bytes ??
+        try:
+            await self.listener(ws, id_)
+        except aio.TimeoutError:
+            if debug[-1]:
+                print("timeout....")
+            self.remove_connection(id_)
+            await ws.close()
+        # NOTE next line is mandatory for preventing a closed websocket to raise exception
+        return ws
+
+    async def shutdown(self):
+        """Close all websocket connections and notify observers."""
+        if debug[-1]:
+            print("in shutdown process ...")
+        await broadcast.put({"name": "broadcast", "args": [{"action": "stop_observer"}]})
+        for websocket in list(self.ws.values()):
+            await websocket.close()
+        if self.client_session is not None and not self.client_session.closed:
+            await self.client_session.close()
+                
+    async def _closeSanely_(self, id_old, user):
+        """
+        protects the hard shutdown if the same user is connected once again
+        """
+        if self.closeSanely:
+            try:
+                await self.closeSanely(user, id_old)
+            except Exception as error:
+                await self._report_error("close_sanely", error)
+                if debug[-1]:
+                    print("closeSanely callback failed:", error)
+            await aio.sleep(3.0)
+        if id_old in self.ws:
+            await self.ws[id_old].close()
+        self.remove_connection(id_old)
+
+    async def listener(self, ws, id_):
+        """Listen for messages on ``ws`` and forward them to the broker."""
+        user = "unknown"
+        while True:
+            # async for msg in ws: ---> replaced by ...
+            # if no message arrives after lately 20 secs the connection is closed
+            msg = await ws.receive(timeout=self.receive_timeout)  
+            if msg.type == aiohttp.WSMsgType.text:
+                data = msg.data
+                if id_ not in self.isAuthenticated and self.doAuth:
+                    id_out, user = await self.authenticator.startAuth(data, ws, self.nonce[id_])
+                    if id_out is not None and id_out == id_:
+                        self.isAuthenticated.update({id_: user})
+                        if user in self.connectedUser:
+                            id_old = self.connectedUser.pop(user)
+                            self.isAuthenticated.pop(id_old)
+                            try:
+                                aio.ensure_future(self._closeSanely_(id_old, user))
+                            except:
+                                pass
+                            finally:
+                                if debug[-1]:
+                                    print("closed one pending connection of user %s" % user)
+                            self.connectedUser.update({user: id_})
+                        else:
+                            self.connectedUser.update({user: id_})
+                        # print(self.connectedUser, self.ws)
+                    else:
+                        await self._report_error(
+                            "authentication", PermissionError("authentication rejected")
+                        )
+                        await self.ws[id_].close()
+                        break
+                else:
+                    await self.broker.put(data)
+            elif msg.type == aiohttp.WSMsgType.CLOSED:
+                print(f"closed by client {user}")
+                await self.ws[id_].close()
+                break
+            elif msg.type == aiohttp.WSMsgType.ERROR:
+                print(f"error by client {user}")
+                await self.ws[id_].close()
+                break
+            else:
+                if debug[-1]:
+                    print(f"an unknown text message arrived {msg.type} by {user}")
+                await self.ws[id_].close()
+                break
+        # print("out of order.........")
+        if id_ == "client":
+            await self.shutdown()
+        else:
+            self.remove_connection(id_)
+            if self.closeOnClientQuit:
+                if debug[-1]:
+                    print("client died ...")    
+                if len(self.ws) == 0:
+                    await self.broker.put("client exit")
+                    await self.shutdown()
+                    if self.onCloseCallback:
+                        try:
+                            await self.onCloseCallback(user)
+                        except Exception as error:
+                            await self._report_error("on_close", error)
+                            if debug[-1]:
+                                print("close callback failed:", error)
+        if debug[-1]:
+            print("--- connection of %s stopped " % user)
+        #if self.onCloseCallback:
+        #    await self.onCloseCallback(user)
+
+    def remove_connection(self, id_):
+        """Remove a connection from the internal registry."""
+        self.ws.pop(id_, None)
+        if id_ in self.ids:
+            self.ids.remove(id_)
+        if id_ in self.isAuthenticated:
+            user = self.isAuthenticated.pop(id_)
+            if self.connectedUser.get(user) == id_:
+                self.connectedUser.pop(user)
+        if debug[-1]:
+            print("after client left:")
+            print("user...",self.connectedUser)
+            print("ws.....",self.ws)
+

nucosObs/observable.py

@@ -0,0 +1,40 @@
+"""Observable helper used by observers to share events."""
+
+import asyncio as aio
+import nucosObs
+
+
+class NoConcurrentObserver(Exception):
+    def __init__(self, message):
+        self.message = message
+
+class Observable():
+    """
+    The observable can be observed by one or many observers. Observers are registered in their init.
+    The events are produced in tasks which are then put into the async loop from the beginning on.
+
+    """
+    def __init__(self, runtime=None):
+        self.runtime = runtime or nucosObs
+        self.loop = self.runtime.loop
+        self.q = {}
+        self.runtime.allObservables.append(self)
+
+    def register(self, observer, concurrent=[]):
+        if not concurrent:
+            self.q.update({observer.name: aio.Queue()})
+            observer._queue = self.q[observer.name]
+        else:
+            concurrentQueues = []
+            for c in concurrent:
+                if c in self.q:
+                    concurrentQueues.append(self.q[c])
+            if concurrentQueues:
+                observer._queue = concurrentQueues[0]
+            else:
+                raise NoConcurrentObserver("No known observers %s" % concurrent)
+
+    async def put(self, event):
+        for q in self.q.values():
+            await q.put(event)
+

nucosObs/observer.py

@@ -0,0 +1,253 @@
+"""Base classes and helpers for creating observers."""
+
+import asyncio as aio
+import inspect
+
+import nucosObs
+from nucosObs.observable import Observable
+
+
+def inThread(callback=False):
+    def wrapper(func):
+        """
+        Use this decorator to indicate that the function is not-async and time consuming and should be run in a separate thread.
+        The observer awaits the result, other observers are running normally.
+
+        :param callback: True if a callback is defined, default is False
+        :type callback: bool
+        """
+        func.inThread = True
+        func.callback = callback
+        return func
+    return wrapper
+
+
+class NoCallbackException(Exception):
+    """
+    Exception which is raised, if a callback is expected but not asigned to the callbacks dict.
+
+    """
+
+    def __init__(self, message):
+        self.message = message
+
+
+class Observer():
+    """
+    The callback class which reacts on observables. An Observer must register on observables.
+    Many Observers can register on one observable.
+    One Observer can register only on one observable and not many.
+
+    Concurrent observers are possible. Just add other observers by name in the parameter list concurrent.
+
+    Subclass Observer and add any async function which is then executed when invoked in the observables.
+    The parameters for that call must be operated in the parse function.
+
+    """
+
+    def __init__(self, name, observable, concurrent=[], runtime=None, on_error=None):
+        """
+        :param name: the name of the observer
+        :type name: str
+        :param observable: the observable to listen on
+        :type observable: observable
+        :param concurrent: all other concurrent observers (or just one of them, they share all on _queue)
+        :type concurrent: list
+        """
+        self.runtime = runtime or observable.runtime
+        if observable.runtime is not self.runtime:
+            raise ValueError("observer and observable must share a runtime")
+        self.name = name
+        self._queue = None
+        self.loop = self.runtime.loop
+        self.runtime.allObs.append(self)
+        observable.register(self, concurrent)
+        self.callbacks = {}
+        self.schedule_time = 1.0
+        self.schedule_task = None
+        self.schedule_args = []
+        self.schedule_kwargs = {}
+        self.stopTimeFraction = 10 # MEANS IN A 10TH FRACTION CAN BES THE LOOP STOPPED
+        self.stop = False
+        self.stopScheduleLoop = False
+        self._bridge_ = {}
+        self.on_error = on_error
+
+    async def _report_error(self, context, error):
+        if self.on_error is not None:
+            result = self.on_error(context, error)
+            if inspect.isawaitable(result):
+                await result
+
+    def scheduleRegular(self, method, t, *schedule_args, **schedule_kwargs):
+        self.schedule_task = method
+        self.schedule_args = schedule_args
+        self.schedule_kwargs = schedule_kwargs
+        self.schedule_time = t
+        # self.stopTimeFraction = 5
+        self.stopScheduleLoop = False
+
+    async def shutdown(self):
+        if self.runtime.debug[-1]:
+            print("shutdown now...")
+        self.stop = True
+        for observable in self.runtime.allObservables:
+            await observable.put({"action": "stop_observer"})
+
+    async def scheduleOnce(self, method, t, *args, **kwargs):
+        await aio.sleep(t)
+        await method(*args, **kwargs)
+
+    def parse(self, item):
+        """
+        Dict parse logic + str parse logic, overwrite if necessary
+
+        a message is of the form {"name": function-name, "args": [A,B,C,...] }
+        or "function-name A B C"
+
+        """
+        if isinstance(item, dict):
+            if "name" in item:
+                fct = item["name"]
+            else:
+                fct = None
+            if "args" in item:
+                args = item["args"]
+            else:
+                args = []
+            if hasattr(self, fct):
+                method = getattr(self, fct)
+                if hasattr(method, '__call__'):
+                    return True, method, args
+                else:
+                    return False, None, None
+            else:
+                return False, None, None
+        elif isinstance(item, str):
+            items = item.split(" ")
+            fct, args = items[0], items[1:]
+
+            if hasattr(self, fct):
+                # print(fct, args)
+                method = getattr(self, fct)
+                if hasattr(method, '__call__'):
+                    return True, method, args
+                else:
+                    return False, None, None
+            else:
+                return False, None, None
+        else:
+            return False, None, None
+
+    def startSchedule(self):
+        # print("START schedule")
+        self.stopScheduleLoop = False
+        if hasattr(self.runtime, "create_task"):
+            self.runtime.create_task(self.scheduleLoop())
+        else:
+            self.loop.create_task(self.scheduleLoop())
+
+    def stopSchedule(self):
+        self.stopScheduleLoop = True
+
+    async def scheduleLoop(self):
+        self.stop = False
+        while not self.stop and not self.stopScheduleLoop:
+            n = 0
+            while n < self.stopTimeFraction:
+                n += 1
+                await aio.sleep(self.schedule_time / self.stopTimeFraction)
+                if self.stop:
+                    break
+            if self.schedule_task:
+                await self.schedule_task(*self.schedule_args, **self.schedule_kwargs)
+        if self.runtime.debug[-1]:
+            print("leave scheduleLoop")
+
+    async def observe(self):
+        """
+        Do not overwrite the main observe logic, better overwrite the parse method for incoming string-messages.
+
+        """
+        self.stop = False
+        while not self.stop:
+            if self._queue is None:
+                break
+            item = await self._queue.get()
+            if self.runtime.debug[-1]:
+                print("observer %s received %s, type %s" %
+                      (self.name, item, type(item)))
+            try:
+                isCallable, method, args = self.parse(item)
+            except Exception as error:
+                await self._report_error("parse", error)
+                if self.runtime.debug[-1]:
+                    print("parse failed: %s" % item)
+                isCallable = False
+            if isCallable:
+                try:
+                    if hasattr(method, "inThread"):
+                        await aio.get_running_loop().run_in_executor(
+                            self.runtime.pool, method, *args
+                        )
+                    else:
+                        await method(*args)
+                    if hasattr(method, "callback") and method.callback:
+                        if method in self.callbacks:
+                            await self.callbacks[method]()
+                        else:
+                            raise NoCallbackException(
+                                "No callback known of method %s" % method)
+                except Exception as error:
+                    await self._report_error("handler", error)
+                    raise
+            elif isinstance(item, dict) and "action" in item:
+                if self.runtime.debug[-1]:
+                    print("....", item)
+                if item["action"] == "stop_observer":
+                    self.stop = True
+                break
+            elif isinstance(item, str) and "stop_observer" in item:
+                # print(".....", isCallable, method, args, item)
+                self.stop = True
+                break
+            else:
+                if self.runtime.debug[-1]:
+                    print("swallowed: %s %s" % (self.name, item))
+        if self.runtime.debug[-1]:
+            print("--- Observer: %s stopped %s" % (self.name, self.stop))
+
+    def set_bridge_method(self, method_name, method_hook):
+        """
+        Defines bridge methods which are just follow-ups to communicate with ApplicationSessions
+
+        """
+        self._bridge_.update({method_name: method_hook})
+
+    async def bridge(self, method, *args):
+        if self.runtime.debug[-1]:
+            print("bridge call %s" % method)
+        if method not in self._bridge_:
+            return
+        else:
+            await self._bridge_[method](*args)
+
+
+class BroadcastObserver(Observer):
+    def __init__(self, name, observable, concurrent=[], runtime=None, on_error=None):
+        super(BroadcastObserver, self).__init__(name, observable, concurrent, runtime, on_error)
+        self.obs = self.runtime.allObservables
+
+    async def broadcast(self, msg):
+        if self.runtime.debug[-1]:
+            print("broadcast ...", msg, type(msg))
+        if "action" in msg:
+            if self.runtime.debug[-1] and msg["action"] == "stop_observer":
+                print("shut down all observers ...")
+        for o in self.obs:
+            await o.put(msg)
+
+
+broadcast = Observable()
+broadcastObserver = BroadcastObserver("broadcastObserver", broadcast)
+

nucosObs/stdinInterface.py

@@ -0,0 +1,52 @@
+"""Simple stdin based interface to feed observables."""
+
+import sys
+import asyncio as aio
+
+import nucosObs
+from nucosObs import debug
+from nucosObs.observer import broadcast
+
+class StdinInterface(object):
+    """Interface reading commands from ``stdin``."""
+
+    def __init__(self, observable, input_stream=None, loop=None):
+        """Create the interface and attach ``observable`` for output."""
+        self.observable = observable
+        self.input_stream = input_stream or sys.stdin
+        self.loop = loop or getattr(observable, "loop", nucosObs.loop)
+        self.q = aio.Queue()
+        try:
+            self.loop.add_reader(self.input_stream, self.got_input)
+        except (OSError, ValueError, NotImplementedError):
+            pass
+        self.stop = False
+
+    def got_input(self):
+        """Callback for the event loop when input is available."""
+        self.loop.create_task(self.q.put(self.input_stream.readline()))
+
+    async def get_ui(self):
+        """Coroutine processing the input queue and dispatching commands."""
+        out = []
+        while not self.stop:
+            out = (await self.q.get()).strip()
+            if "leave_in" in out:
+                self.stop = True
+                t = float(out.split()[-1])
+                await aio.sleep(t)
+                await self.observable.put({"name": "shutdown", "args": []})
+                break
+            elif out.endswith('x'):
+                self.stop = True
+                await self.observable.put({"name": "shutdown", "args": []})
+                break
+            elif out.endswith('say'):
+                await self.observable.put({"name": "say", "args": []})
+            elif 'fact' in out:
+                await self.observable.put({"name": "fact", "args": [out.split(" ")[-1]]})
+            else:
+                await self.observable.put(out)
+        if debug[-1]:
+            print("Stdin-Interface stopped")
+

nucosObs/twoWayInterface.py

@@ -0,0 +1,57 @@
+"""Interface sending and receiving directives between observables."""
+
+import asyncio as aio
+
+import nucosObs
+from nucosObs import debug
+from nucosObs.observer import broadcast
+
+class TwoWayInterface(object):
+    """Interface that forwards messages between multiple observables."""
+
+    def __init__(self, observables_dict, send_all=False):
+        """Create interface with mapping of names to observables."""
+        self.loop = nucosObs.loop
+        # Remove deprecated loop parameter when creating the queue
+        self.q = aio.Queue()
+        self.observables_dict = observables_dict
+        self.stop = False
+        self.send_all = send_all
+
+    async def put(self, txt):
+        """Put a new directive into the internal queue."""
+        await self.q.put(txt)
+
+    async def get_ui(self):
+        """Process directives from :func:`put` until a stop command arrives."""
+        self.stop = False
+        while not self.stop:
+            directive = dict(await self.q.get())
+            if debug[-1]:
+                print("interface received", directive)
+            if "action" in directive:
+                action = directive["action"]
+                if "waitTime" in action:
+                    t = float(action.split()[-1])
+                    await aio.sleep(t)
+                    continue
+                if action.endswith('stop interface'):
+                    self.stop = True
+                    await broadcast.put({"name": "broadcast", "args": [{"action": "stop_observer"}]})
+                    break
+                if "leave_in" in action:
+                    self.stop = True
+                    t = float(action.split()[-1])
+                    await aio.sleep(t)
+                    break
+            if "obs" in directive:
+                nameObs = directive.pop("obs")
+                if nameObs in self.observables_dict:
+                    await self.observables_dict[nameObs].put(directive)
+            elif self.send_all:
+                for observable in self.observables_dict.values():
+                    await observable.put(dict(directive))
+
+
+        if debug[-1]:
+            print("--- Interface stopped")

nucosObs/version.py

@@ -0,0 +1 @@
+version='0.4.18'

nucosObs/websocketInterface.py

@@ -0,0 +1,154 @@
+"""Basic ``websockets`` based interface for observers."""
+
+import websockets
+import asyncio as aio
+import inspect
+import secrets
+try:
+    import simplejson as json
+except:
+    import json
+
+try:
+    from nucosCR import random, hexdigest_n
+    isCR = True
+except:
+    import random
+    isCR = False
+
+from nucosObs import loop, debug
+from nucosObs.observer import broadcast
+# debug.append(True)
+
+
+def _token(length):
+    if isCR:
+        return random(length).decode()
+    return secrets.token_urlsafe(length)
+
+
+class WebsocketInterface(object):
+    """Simple websocket server/client using the ``websockets`` package."""
+
+    def __init__(self,
+                 broker,
+                 doAuth=False,
+                 closeOnClientQuit=False,
+                 authenticator=None,
+                 sslClient=None,
+                 sslServer=None,
+                 on_error=None):
+        """Initialize the interface and optionally enable authentication."""
+        self.ws = {}
+        self.doAuth = doAuth
+        self.broker = broker
+        self.server = None
+        self.authenticator = authenticator
+        self.nonce = {}
+        self.isAuthenticated = {}
+        self.isRefused = []
+        self.closeOnClientQuit = closeOnClientQuit
+        self.sslClient = sslClient
+        self.sslServer = sslServer
+        self.approved = []
+        self.on_error = on_error
+
+    async def _report_error(self, context, error):
+        if self.on_error is not None:
+            result = self.on_error(context, error)
+            if inspect.isawaitable(result):
+                await result
+
+    async def broadcast(self, msg, client=None):
+        """Broadcast ``msg`` to all clients or to ``client`` if given."""
+        for i, antenna in enumerate(self.ws.values()):
+            if client is None or i == client:
+                try:
+                    await antenna.send(msg)
+                except Exception as error:
+                    await self._report_error("broadcast", error)
+
+    async def connect(self, host, port):
+        """Connect as a client to ``host`` and ``port``."""
+        if debug[-1]:
+            print("try to start client")
+        # self.server = await websockets.connect(self.handler, ip, port)
+        if self.sslClient:
+            protocol = "wss"
+        else:
+            protocol = "ws"
+        websocket = await websockets.connect('%s://%s:%s/ws' % (protocol, host, str(port)), ssl=self.sslClient)
+        self.ws['client'] = websocket
+        await self.listener(websocket, 'client')
+
+    async def serve(self, ip, port):
+        """Start a websocket server bound to ``ip``/``port``."""
+        if debug[-1]:
+            print("try to start server")
+        self.server = await websockets.serve(self.handler, ip, port, ssl=self.sslServer)
+        print("started server", self.server)
+
+    async def handler(self, websocket):
+        """Handle a single websocket connection."""
+        id_ = _token(12)
+        self.ws[id_] = websocket
+        if debug[-1]:
+            print("Partner connected")        
+        if self.doAuth:
+            self.nonce[id_] = _token(24)
+            context = {"name": "doAuth",
+                       "args": {"nonce": self.nonce[id_], "id": id_},
+                       "action": "authenticate"}
+            await self.ws[id_].send(json.dumps(context))
+        await self.listener(self.ws[id_], id_)
+
+    async def shutdown(self):
+        """Close all open connections and inform observers."""
+        if debug[-1]:
+            print("in shutdown process ...")
+        await broadcast.put({"name": "broadcast", "args": [{"action": "stop_observer"}]})
+        if self.server is not None:
+            for k in [x for x in self.ws.keys()]:
+                await self.ws[k].close()
+
+    def remove_connection(self, id_):
+        """Remove all state associated with a websocket connection."""
+        self.ws.pop(id_, None)
+        self.nonce.pop(id_, None)
+        self.isAuthenticated.pop(id_, None)
+
+    async def listener(self, ws, id_):
+        """Read messages from ``ws`` and route them to the broker."""
+        user = "unknown"
+        while True:
+            try:
+                msg = await ws.recv()
+            except websockets.ConnectionClosed:
+                if id_ == "client":
+                    await self.shutdown()
+                else:
+                    self.remove_connection(id_)
+                    if self.closeOnClientQuit:
+                        if debug[-1]:
+                            print("client died ...")
+                        if len(self.ws) == 0:
+                            await self.broker.put("client exit")
+                            await self.shutdown()
+                break
+
+            if id_ not in self.isAuthenticated and self.doAuth:
+                id_out, user = await self.authenticator.startAuth(msg, ws, self.nonce[id_])
+                if id_out is not None and id_out == id_:
+                    self.isAuthenticated.update({id_: user})
+                else:
+                    await self._report_error(
+                        "authentication", PermissionError("authentication rejected")
+                    )
+                    self.remove_connection(id_)
+                    await ws.close()
+                    break
+            else:
+                await self.broker.put(msg)
+
+        if debug[-1]:
+            print("--- connection of %s stopped " % user)

nucosobs-0.4.18.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: nucosObs
+Version: 0.4.18
+Summary: nucosObs - an observer/observable toolbox based on asyncio
+Home-page: https://github.com/DocBO/nucosObs
+Author: Oliver Braun
+Author-email: oliver.braun@nucos.de
+License: MIT
+Project-URL: Source, https://github.com/NuCOS/nucosObs
+Project-URL: Issues, https://github.com/NuCOS/nucosObs/issues
+Project-URL: Changelog, https://github.com/NuCOS/nucosObs/blob/master/docs/CHANGELOG.md
+Project-URL: Security, https://github.com/NuCOS/nucosObs/security/policy
+Keywords: observer observable asyncio
+Classifier: Development Status :: 1 - Planning
+Classifier: Environment :: Console
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: websockets<17,>=15
+Requires-Dist: aiohttp<4,>=3.12
+Provides-Extra: test
+Requires-Dist: pytest<10,>=9; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=1; extra == "test"
+Requires-Dist: pytest-cov<8,>=7; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# nucosObs
+
+[![PyPI version](https://img.shields.io/pypi/v/nucosObs.svg)](https://pypi.org/project/nucosObs/)
+[![Tests](https://github.com/NuCOS/nucosObs/actions/workflows/tests.yml/badge.svg)](https://github.com/NuCOS/nucosObs/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+`nucosObs` is an observer-observable framework based on `asyncio`.
+
+## Status
+
+The project supports Python 3.11 through 3.13. Continuous integration runs the
+full pytest suite and builds a wheel for each supported version.
+
+## Install
+```
+pip install nucosObs
+```
+
+
+## Documentation
+
+A comprehensive user guide covering beginner to expert workflows is available:
+
+➡️ **[User Guide — docs/USER_GUIDE.md](docs/USER_GUIDE.md)**
+
+The guide includes tutorials for basic observer patterns, scheduling, threaded
+handlers, websocket interfaces, authentication, multi-tenant runtimes, error
+handling, and production deployments.
+
+The project also ships a small but handy toolbox to build applications using
+the observer/observable pattern with ``asyncio``.  It contains helper
+classes for observers, observables and a couple of interfaces (stdin,
+websockets and aiohttp based websockets) to communicate with running
+tasks.
+
+### Example
+
+```python
+import asyncio as aio
+
+from nucosObs import main_loop
+from nucosObs.observable import Observable
+from nucosObs.observer import Observer
+
+
+class HelloObserver(Observer):
+    async def say(self):
+        print("Hello")
+
+
+A = Observable()
+O = HelloObserver("O", A)
+aio.ensure_future(A.put({"name": "say"}))
+main_loop([])
+```
+
+See the ``examples`` directory for more advanced usage.
+
+## Event Model
+
+An observable delivers each event to every registered observer queue. Events
+can be dictionaries or command strings. Dictionary events use this shape:
+
+```python
+{"name": "method_name", "args": ["first argument", "second argument"]}
+```
+
+Observers process regular async handlers sequentially. A
+`{"action": "stop_observer"}` event stops an observer after its active handler
+has completed.
+
+## Threaded Handlers
+
+Use `@inThread()` for synchronous work that must not block the event loop. The
+handler runs in the runtime's thread pool. With `callback=True`, register an
+async callback for the bound handler in `observer.callbacks`; it runs after the
+threaded method finishes.
+
+```python
+from nucosObs.observer import Observer, inThread
+
+
+class Worker(Observer):
+    @inThread()
+    def calculate(self, value):
+        return value * 2
+```
+
+## Isolated Runtimes
+
+The module-level `main_loop()` API remains available for existing programs. For
+multiple applications in one process, create a `Runtime` and pass it to each
+observable and observer. Each runtime owns its event loop, registries, debug
+state, and thread pool.
+
+```python
+from nucosObs import Runtime
+from nucosObs.observable import Observable
+from nucosObs.observer import Observer
+
+
+runtime = Runtime()
+events = Observable(runtime=runtime)
+worker = Worker("worker", events, runtime=runtime)
+runtime.loop.create_task(events.put({"name": "calculate", "args": [21]}))
+runtime.loop.create_task(events.put({"action": "stop_observer"}))
+runtime.main_loop([])
+runtime.close()
+```
+
+## Websocket Authentication
+
+Both websocket interfaces send an authentication challenge when `doAuth=True`.
+The configured authenticator must provide an async
+`startAuth(message, websocket, nonce)` method and return
+`(connection_id, user)`. Returning a matching connection ID accepts the client;
+returning `None` rejects and closes it. Clients may send regular broker messages
+only after successful authentication.
+
+## Interfaces
+
+An **Interface** is a bridge between the external world and the observable /
+observer system. It reads data from an external source (stdin, a network
+socket, another observable) and puts structured events into an `Observable`,
+which then dispatches them to all registered `Observer` instances.
+
+### Supported Interface Types
+
+| Interface | Module | Purpose |
+|---|---|---|
+| `StdinInterface` | `nucosObs.stdinInterface` | Reads commands from standard input (terminal) |
+| `TwoWayInterface` | `nucosObs.twoWayInterface` | Routes events between named observables within the same process |
+| `WebsocketInterface` | `nucosObs.websocketInterface` | WebSocket server/client using the [`websockets`](https://pypi.org/project/websockets/) library |
+| `AiohttpWebsocketInterface` | `nucosObs.aiohttpWebsocketInterface` | WebSocket server/client using the [`aiohttp`](https://pypi.org/project/aiohttp/) framework |
+
+### Websocket Backend Comparison
+
+| Feature | `WebsocketInterface` | `AiohttpWebsocketInterface` |
+|---|---|---|
+| **Library** | `websockets` (lightweight) | `aiohttp` (full web framework) |
+| **Use case** | Dedicated WebSocket server/client | WebSocket alongside an HTTP server |
+| **TLS / SSL** | Yes (`sslServer`, `sslClient`) | Yes (`sslServer`, `sslClient`) |
+| **Authentication** | Yes (`doAuth`) | Yes (`doAuth`) |
+| **Heartbeat / ping** | No | Yes (`heartbeat`) |
+| **Receive timeout** | No | Yes (`receive_timeout`) |
+| **User-aware send** | Manual via connection dict | `send(msg, user)` by username |
+| **Duplicate user handling** | Manual | Built-in via `connectedUser` + `closeSanely` |
+
+Use `WebsocketInterface` when you need a simple, standalone WebSocket
+endpoint. Use `AiohttpWebsocketInterface` when you already run an `aiohttp`
+web application, need heartbeats and timeouts, or want user-aware message
+delivery.
+
+### Interface Lifecycle
+
+1. An interface reads or receives input (stdin line, WebSocket message,
+   internal event).
+2. It converts the input into an event (dict or string).
+3. It calls `await observable.put(event)` to dispatch the event.
+4. All observers registered on that observable process the event.
+5. The interface handles shutdown via stop commands or connection closure.
+
+## Diagnostics
+
+Run `python -m nucosObs` to print the installed package version, dependency
+versions, supported Python range, and default runtime state. Add `--json` for
+machine-readable output suitable for support reports.
+
+## License
+
+Distributed under the [MIT License](LICENSE.txt).
+
+## Platforms
+No specific platform dependency. Python 3.11 or later is required.
+
+## Testing
+Install development dependencies with `pip install -r requirements-dev.txt`,
+then run the test suite with `python -m pytest`.
+
+The repository runs this command in GitHub Actions on Python 3.11 through 3.13.
+
+For a coverage-grounded view of current readiness and compatible next steps,
+see [docs/FINAL_READINESS.md](docs/FINAL_READINESS.md).
+
+## Contributing and Support
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations. Report
+security vulnerabilities according to [SECURITY.md](SECURITY.md); for general
+questions or reproducible bugs, open a GitHub issue.
+
+

nucosobs-0.4.18.dist-info/RECORD

@@ -0,0 +1,14 @@
+nucosObs/__init__.py,sha256=RrTJW95-ExDc2amp4Bvc3A-_eBppdZToyLQPfBR3cbk,3658
+nucosObs/__main__.py,sha256=Ww1NzQ4QmphRyi7KPF7Usd3fwR_Z9bTVPjjluAlVVl8,2067
+nucosObs/aiohttpWebsocketInterface.py,sha256=s99sOCd3Xj0Xdr6iqPrQRH7vZha6rVZWtkWeUe_fBcI,10023
+nucosObs/observable.py,sha256=RgCQYa1rtuAXT56ulLsolGPnfX0a24BDFHyNTBtJE04,1267
+nucosObs/observer.py,sha256=yGaJ3hxHw8o-HgGg8Qln9HYj-vuN9B0SPasYkq1tlTI,9049
+nucosObs/stdinInterface.py,sha256=rJVd4uH1eEHGJCUF540qW2j1lzj_YF9xy5yVKBidrcM,1910
+nucosObs/twoWayInterface.py,sha256=mDX45AGVNkfyjOP5lptxT2Ht9ZyqJM902w_SQt3HoV8,2146
+nucosObs/version.py,sha256=0F0B9vPs57KVGdvLhp42jgzlRSLU-rk-Sc1yQgYRFII,17
+nucosObs/websocketInterface.py,sha256=Ri0HtEEm_mRFwgR-iDTBIYMfbNftYbanxz43wF402KY,5392
+nucosobs-0.4.18.dist-info/licenses/LICENSE.txt,sha256=L1fvEaPErlAL_IsISHXztBwujHIDZJAbjUi-Ufqmc78,1103
+nucosobs-0.4.18.dist-info/METADATA,sha256=fKuCpM6RtQ0TS0fkd3soWhi919tmHGMOrOwCoJj6An0,8396
+nucosobs-0.4.18.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nucosobs-0.4.18.dist-info/top_level.txt,sha256=-LPXaG32QmL2NnSNvZsVGq8B8Rdy8SrsOqMUIr-dyRc,9
+nucosobs-0.4.18.dist-info/RECORD,,

nucosobs-0.4.18.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nucosobs-0.4.18.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2016-2026 Oliver Braun, Johannes Eckstein
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

nucosobs-0.4.18.dist-info/top_level.txt

@@ -0,0 +1 @@
+nucosObs