muxit 0.1.0__py3-none-any.whl

muxit/__init__.py

@@ -0,0 +1,46 @@
+"""Drive the instruments you set up in Muxit from Python.
+
+    import muxit
+
+    m = muxit.connect()            # Muxit on this computer
+    psu = m.connector("psu")
+    psu.voltage = 3.0              # write
+    print(psu.voltage)             # read (Muxit's latest polled value)
+    psu.reset()                    # action
+
+Docs: https://docs.muxit.io/guides/python-client
+"""
+
+from ._version import __version__
+from .client import Muxit, Settings, connect
+from .connector import Connector
+from .errors import (
+    AuthenticationFailed,
+    ConnectionFailed,
+    LimitReached,
+    MuxitError,
+    NotFound,
+    ReadOnly,
+    SafetyBlocked,
+    SimulatedWarning,
+    Timeout,
+    UnknownName,
+)
+
+__all__ = [
+    "__version__",
+    "connect",
+    "Muxit",
+    "Connector",
+    "Settings",
+    "MuxitError",
+    "ConnectionFailed",
+    "AuthenticationFailed",
+    "NotFound",
+    "UnknownName",
+    "ReadOnly",
+    "SafetyBlocked",
+    "LimitReached",
+    "Timeout",
+    "SimulatedWarning",
+]

muxit/__main__.py

@@ -0,0 +1,286 @@
+"""Command line: check the connection and try things without writing Python.
+
+    python -m muxit doctor                  # is everything set up?
+    python -m muxit list [connector]        # what is there
+    python -m muxit get psu voltage
+    python -m muxit set psu voltage 3
+    python -m muxit call psu reset
+    python -m muxit demo                    # read and write the built-in test device
+
+Every command takes --host, --port, --password, --token and --timeout, or the
+MUXIT_HOST / MUXIT_PORT / MUXIT_PASSWORD / MUXIT_TOKEN / MUXIT_TIMEOUT variables.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import platform
+import socket
+import sys
+import time
+import warnings
+from typing import Any, List, Optional
+
+from . import errors
+from ._version import __version__
+from .client import Muxit, Settings, login
+
+
+def _out(text: str = "") -> None:
+    print(text, flush=True)
+
+
+def _status(tag: str, text: str) -> None:
+    # ASCII tags: a Windows console may not print check marks.
+    _out(f"  [{tag:^4}] {text}")
+
+
+def _value(text: str) -> Any:
+    """Command-line value: JSON when it parses (3, true, [1,2], {"a":1}), else the plain string."""
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _show(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False) if not isinstance(value, str) else value
+
+
+def _connect(args: argparse.Namespace) -> Muxit:
+    return Muxit(args.host, args.port, password=args.password, token=args.token, timeout=args.timeout)
+
+
+# ── doctor ───────────────────────────────────────────────────────
+
+def doctor(args: argparse.Namespace) -> int:
+    _out(f"muxit {__version__} (Python {platform.python_version()}, {platform.system()})")
+    _out()
+    try:
+        s = Settings(args.host, args.port, args.password, args.token, args.timeout)
+    except errors.MuxitError as e:
+        _status("FAIL", str(e))
+        return 1
+    _out("Settings")
+    _status("", f"host     {s.host}   (from {s.source['host']})")
+    _status("", f"port     {s.port}   (from {s.source['port']})")
+    _status("", f"password {'set' if s.password else 'not set'}   (from {s.source['password']})")
+    if s.token:
+        _status("", f"token    set   (from {s.source['token']})")
+    _status("", f"address  {s.ws_url}")
+    _out()
+
+    _out("Checks")
+    try:
+        with socket.create_connection((s.host, s.port), timeout=min(s.timeout, 5)):
+            pass
+        _status("OK", f"something is listening on {s.host}:{s.port}")
+    except OSError as e:
+        _status("FAIL", f"nothing answers on {s.host}:{s.port} ({e})")
+        if s.is_local:
+            _out("         Start Muxit on this computer, or check the port in its startup banner.")
+        else:
+            _out("         Is Muxit running on that computer, with remote access on (Settings > Remote")
+            _out(f"         access), and does its firewall allow port {s.port}? Try the IP address too.")
+        return 1
+
+    if s.password and not s.token:
+        try:
+            s.token = login(s)
+            _status("OK", "logged in with the password")
+        except errors.MuxitError as e:
+            _status("FAIL", str(e))
+            return 1
+
+    try:
+        m = Muxit(s.host, s.port, token=s.token, timeout=s.timeout)
+    except errors.MuxitError as e:
+        _status("FAIL", str(e))
+        return 1
+
+    problems = 0
+    with m:
+        _status("OK", "connected to Muxit")
+        if m.token_source:
+            _status("OK", f"access token read from workspace {m.token_source}")
+        try:
+            lic = m.license()
+            used, cap = lic.get("currentConnectors"), lic.get("maxConnectors")
+            cap_text = "unlimited" if cap in (None, -1) else str(cap)
+            _status("OK", f"license tier {lic.get('tierName') or lic.get('tierId', '?')}, "
+                          f"connectors {used if used is not None else '?'} of {cap_text}")
+        except errors.MuxitError as e:
+            _status("WARN", f"could not read the license: {e}")
+
+        try:
+            level = m.safety().get("level", "?")
+            if level == "Observe":
+                problems += 1
+                _status("WARN", "safety level is Observe: writes and actions are SIMULATED, nothing")
+                _out("         reaches a device. Pick another level with the safety chip in the Muxit")
+                _out("         window (Free can use Unrestricted).")
+            else:
+                _status("OK", f"safety level {level}")
+        except errors.MuxitError as e:
+            _status("WARN", f"could not read the safety level: {e}")
+
+        try:
+            names = m.connectors()
+        except errors.MuxitError as e:
+            _status("FAIL", f"could not list connectors: {e}")
+            return 1
+        if not names:
+            _status("WARN", "Muxit has no connectors loaded yet: add one in the Muxit window")
+        else:
+            _status("OK", f"{len(names)} connector(s): {', '.join(names)}")
+    _out()
+    _out("Ready. In Python:" if not problems else "Connected, with the warning above. In Python:")
+    parts = [] if s.source["host"] == "default" else [f'"{s.host}"']
+    if s.port != 8765:
+        parts.append(f"port={s.port}")
+    _out(f"    import muxit; m = muxit.connect({', '.join(parts)})")
+    return 0
+
+
+# ── list / get / set / call ──────────────────────────────────────
+
+def list_cmd(args: argparse.Namespace) -> int:
+    with _connect(args) as m:
+        if args.connector:
+            _out(m.connector(args.connector).describe())
+            return 0
+        names = m.connectors()
+        if not names:
+            _out("No connectors loaded.")
+        for name in names:
+            _out(name)
+    return 0
+
+
+def get_cmd(args: argparse.Namespace) -> int:
+    with _connect(args) as m:
+        _out(_show(m.connector(args.connector).read(args.property)))
+    return 0
+
+
+def set_cmd(args: argparse.Namespace) -> int:
+    with _connect(args) as m:
+        c = m.connector(args.connector)
+        setattr(c, args.property, _value(args.value))  # checks read-only and spelling first
+        _out(f"{args.connector}.{args.property} = {args.value}")
+    return 0
+
+
+def call_cmd(args: argparse.Namespace) -> int:
+    with _connect(args) as m:
+        result = m.connector(args.connector).call(args.action, *[_value(a) for a in args.args])
+        if result is not None:
+            _out(_show(result))
+    return 0
+
+
+# ── demo ─────────────────────────────────────────────────────────
+
+def demo(args: argparse.Namespace) -> int:
+    with _connect(args) as m:
+        names = m.connectors()
+        target: Optional[str] = args.connector
+        if target is None:
+            for name in names:
+                if str(m.schema(name).get("driver", "")).lower() == "testdevice":
+                    target = name
+                    break
+        if target is None:
+            _out("No TestDevice connector found. The default workspace has one called 'test-device';")
+            _out("or pass the name of another connector: python -m muxit demo <name>")
+            return 1
+        dev = m.connector(target)
+        _out(f"Using connector {target!r}")
+        _out()
+        _out(f">>> dev = m.connector({target!r})")
+        before = dev.temperature
+        _out(">>> dev.temperature")
+        _out(f"{before}")
+        new = 42.0 if before != 42.0 else 37.5
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            _out(f">>> dev.temperature = {new}")
+            dev.temperature = new
+            time.sleep(0.5)  # driver properties are polled; give the poll a cycle
+            after = dev.temperature
+            _out(">>> dev.temperature")
+            _out(f"{after}")
+            _out(">>> dev.calculate(2, 3)")
+            _out(f"{dev.calculate(2, 3)}")
+            dev.temperature = before
+        if any(issubclass(w.category, errors.SimulatedWarning) for w in caught):
+            _out()
+            _out("NOTE: Muxit's safety level is Observe, so the write was simulated and the action")
+            _out("returned nothing. Pick another level with the safety chip in the Muxit window.")
+            return 0
+        _out()
+        _out(f"Wrote {new}, read back {after}; restored {before}. Everything works.")
+    return 0
+
+
+# ── entry point ──────────────────────────────────────────────────
+
+def _parser() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--host", help="IP address or host name of the Muxit computer (default 127.0.0.1)")
+    common.add_argument("--port", type=int, help="Muxit port (default 8765)")
+    common.add_argument("--password", help="remote-access password (only for another computer)")
+    common.add_argument("--token", help="remote-access token instead of a password")
+    common.add_argument("--timeout", type=float, help="seconds to wait for an answer (default 10)")
+
+    p = argparse.ArgumentParser(prog="python -m muxit", description="Muxit from the command line.")
+    p.add_argument("--version", action="version", version=f"muxit {__version__}")
+    sub = p.add_subparsers(dest="command", metavar="command")
+
+    sub.add_parser("doctor", parents=[common], help="check the connection and settings").set_defaults(fn=doctor)
+
+    q = sub.add_parser("list", parents=[common], help="list connectors, or one connector's properties and actions")
+    q.add_argument("connector", nargs="?")
+    q.set_defaults(fn=list_cmd)
+
+    q = sub.add_parser("get", parents=[common], help="read a property")
+    q.add_argument("connector")
+    q.add_argument("property")
+    q.set_defaults(fn=get_cmd)
+
+    q = sub.add_parser("set", parents=[common], help="write a property")
+    q.add_argument("connector")
+    q.add_argument("property")
+    q.add_argument("value", help="a number, true/false, JSON, or text")
+    q.set_defaults(fn=set_cmd)
+
+    q = sub.add_parser("call", parents=[common], help="call an action")
+    q.add_argument("connector")
+    q.add_argument("action")
+    q.add_argument("args", nargs="*", help="arguments (numbers, true/false, JSON, or text)")
+    q.set_defaults(fn=call_cmd)
+
+    q = sub.add_parser("demo", parents=[common], help="read and write the built-in test device")
+    q.add_argument("connector", nargs="?", help="connector to use (default: the first TestDevice)")
+    q.set_defaults(fn=demo)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "fn", None):
+        parser.print_help()
+        return 0
+    try:
+        return args.fn(args)
+    except errors.MuxitError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

muxit/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"