pendify 0.1.0__py3-none-any.whl

pendify/__init__.py

@@ -0,0 +1 @@
+"""Pairs this PC with a phone account by a QR on a loopback page, standard library only."""

pendify/__main__.py

@@ -0,0 +1,265 @@
+"""The commands.
+
+    python -m <package>              the pairing page and the watcher of the game client, together
+    python -m <package> --dry        the same, but the watcher never accepts: it alerts at the queue pop
+    python -m <package> --quiet      the same, started by the system at logon: no browser, and no message box
+                                     unless the start fails
+    python -m <package> ping <kind>  one alert with the stored pair, one fixed line per answer
+
+The page and the watcher stop together on Ctrl+C, on Ctrl+Break and on the page's quit button, which
+removes the run file and exits 0. One instance per config folder: a second start opens the running page
+and exits 0, and one made while that program is still closing after its quit waits for it to end and starts.
+Where no console is attached (a pythonw start), the line a start ends on is also shown in a
+message box. `--data-dir`, `--worker` and `--client-lockfile` are the
+test overrides, loopback only, so a test run reads neither the profile, the Worker nor the client's files.
+"""
+import argparse
+import os
+import signal
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+from . import alert, client, config, page, pairing, runfile, watcher, worker
+from .autostart import Autostart
+
+TICK_SECONDS = 1.0
+STOP_SECONDS = 5.0
+# How long a start waits for a copy that is closing to let its run file go: one tick and the two STOP_SECONDS waits
+# of its stop, with room.
+CLOSING_WAIT_SECONDS = 15.0
+REFUSED_LINE = "refused: the pairing of this PC was not accepted; link it again from the page"
+NOT_LINKED_LINE = "not linked: start the program without arguments and link this PC first"
+ALREADY_RUNNING_LINE = "already running: opening the page of the program that runs"
+# A quiet second start opens nothing, so its line promises nothing.
+QUIET_RUNNING_LINE = "already running"
+PAGE_NOT_KNOWN_LINE = ("already running: the page of the program that runs is not known yet; start it again in a "
+                       "moment to open it")
+CLAIM_FAILED_LINE = "cannot start: the run file cannot be replaced: {path}"
+FOLDER_FAILED_LINE = "cannot start: the config folder cannot be written: {path}"
+_MB_ICONINFORMATION = 0x40
+_MB_SETFOREGROUND = 0x10000
+
+
+def _data_dir(value):
+    if not value.strip():
+        raise argparse.ArgumentTypeError("the data directory is empty")
+    return Path(value)
+
+
+def _client_lockfile(value):
+    if not value.strip():
+        raise argparse.ArgumentTypeError("the lockfile path is empty")
+    return Path(value)
+
+
+def _worker_address(value):
+    try:
+        return worker.loopback_base(value)
+    except ValueError as refused:
+        raise argparse.ArgumentTypeError(str(refused)) from None
+
+
+def _arguments(argv):
+    # The options are accepted before and after the command; SUPPRESS keeps one side from erasing the other.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--data-dir", type=_data_dir, default=argparse.SUPPRESS,
+                        help="a directory used instead of %%APPDATA%%, for test runs")
+    common.add_argument("--worker", type=_worker_address, default=argparse.SUPPRESS,
+                        help="http://127.0.0.1:<port> or http://localhost:<port> instead of the Worker, for test runs")
+    common.add_argument("--client-lockfile", type=_client_lockfile, default=argparse.SUPPRESS,
+                        help="a lockfile read instead of the client's, its client reached over plain http on "
+                             "127.0.0.1, for test runs")
+    parser = argparse.ArgumentParser(prog=f"python -m {__package__}", parents=[common],
+                                     description="Pairs this PC by a QR on a loopback page, watches the game "
+                                                 "client and sends alerts.")
+    parser.add_argument("--dry", action="store_true", help="watch and alert, but never accept")
+    parser.add_argument("--quiet", action="store_true",
+                        help="a start by the system: no browser, and no message box for a start that ends well")
+    commands = parser.add_subparsers(dest="command")
+    ping = commands.add_parser("ping", parents=[common], help="send one alert with the stored pair")
+    ping.add_argument("kind", choices=worker.KINDS)
+    return parser.parse_args(argv)
+
+
+def _ping_line(result):
+    if isinstance(result, worker.Sent):
+        return "sent"
+    if isinstance(result, worker.Refused):
+        return REFUSED_LINE
+    if isinstance(result, worker.NotDelivered):
+        return f"not delivered (HTTP {result.status})"
+    return f"failed: {result.reason}"
+
+
+def _ping(store, base, kind, timeout):
+    pair = store.read()  # never a first load: a ping mints nothing
+    if pair is None or pair.link_id is None:
+        print(NOT_LINKED_LINE)
+        return 2
+    result = worker.ping(pair.link_id, pair.secret, kind, base=base, timeout=timeout)
+    print(_ping_line(result))
+    return 0 if isinstance(result, worker.Sent) else 1
+
+
+def _watcher(args, store, state, base, timeout, stop, delay, beep):
+    """The watcher and its alert. The test override reads its one lockfile, with no process read, and
+    reaches its client over plain http on 127.0.0.1."""
+    lockfile = getattr(args, "client_lockfile", None)
+    if lockfile is None:
+        credentials, addresses = client.ClientCredentials(), client.real_addresses
+    else:
+        credentials, addresses = client.ClientCredentials((str(lockfile),), run=None), client.loopback_addresses
+    alerter = alert.Alerter(store, state, lambda link_id, secret, kind: worker.ping(
+        link_id, secret, kind, base=base, timeout=timeout), beep=beep)
+    return watcher.Watcher(credentials, alerter, accept=not args.dry, addresses=addresses, delay=delay,
+                           stop=stop), alerter
+
+
+def _console_attached():
+    """False only on Windows with no terminal on stdout and no console window: a pythonw start, where a
+    printed line reaches nobody."""
+    if os.name != "nt":
+        return True
+    if sys.stdout is not None and sys.stdout.isatty():
+        return True
+    import ctypes
+    from ctypes import wintypes
+
+    kernel32 = ctypes.WinDLL("kernel32")
+    kernel32.GetConsoleWindow.restype = wintypes.HWND
+    return bool(kernel32.GetConsoleWindow())
+
+
+def _message_box(line):
+    """The line in a Windows message box, the one place a start with no console can show it."""
+    import ctypes
+    from ctypes import wintypes
+
+    user32 = ctypes.WinDLL("user32")
+    user32.MessageBoxW.argtypes = (wintypes.HWND, wintypes.LPCWSTR, wintypes.LPCWSTR, wintypes.UINT)
+    user32.MessageBoxW(None, line, __package__, _MB_ICONINFORMATION | _MB_SETFOREGROUND)
+
+
+def _ends(line, code, show):
+    """The line a start ends on: printed as ever, and shown where no console is attached."""
+    print(line, flush=True)
+    show(line)
+    return code
+
+
+def _serve(args, store, base, timeout, opener, stop, delay, beep, show, clock, sleep, autostart):
+    # A quiet start is the system's, at logon: it never opens the browser, and a start that ends well shows no box.
+    calm = (lambda line: None) if args.quiet else show
+    run = runfile.RunFile(store.path.parent, clock=clock, sleep=sleep)
+    try:
+        holder = run.claim()
+        if holder is not None and holder["closing"] and run.wait_released(holder, CLOSING_WAIT_SECONDS):
+            holder = run.claim()  # the closing copy let its file go: this start claims it as a first one does
+    except runfile.FolderNotWritable as refused:
+        return _ends(FOLDER_FAILED_LINE.format(path=refused.filename), 1, show)
+    except OSError:
+        return _ends(CLAIM_FAILED_LINE.format(path=run.path), 1, show)
+    if holder is not None:
+        if holder["closing"]:  # still closing at the bound: its page is going, so it is never opened
+            return _ends(QUIET_RUNNING_LINE if args.quiet else PAGE_NOT_KNOWN_LINE, 0, calm)
+        port = holder["port"] if holder["port"] is not None else run.holder_port(holder)
+        if port is None:  # a winner with no page yet: nothing is opened; a quiet start promises no page either
+            return _ends(QUIET_RUNNING_LINE if args.quiet else PAGE_NOT_KNOWN_LINE, 0, calm)
+        if args.quiet:  # the system's start at logon: nothing opened, nothing shown, a line of its own
+            print(QUIET_RUNNING_LINE, flush=True)
+            return 0
+        print(ALREADY_RUNNING_LINE, flush=True)
+        opener(f"http://{page.ADDRESS}:{port}/")
+        show(ALREADY_RUNNING_LINE)
+        return 0
+    try:
+        state = pairing.PairingState(store, lambda secret: worker.check(secret, base=base, timeout=timeout))
+        watch, alerter = _watcher(args, store, state, base, timeout, stop, delay, beep)
+
+        def quit_page():
+            # The page's quit marks the record closing at once, since a tick can be held in a slow check before
+            # the finally runs, then sets the same stop event as Ctrl+C: the watcher, the page and the run file
+            # end below.
+            try:
+                run.mark_closing()
+            except OSError:
+                pass  # unmarked, the finally marks it again; the stop goes on
+            stop.set()
+
+        pairing_page = page.PairingPage(state, watch=watch.snapshot, on_quit=quit_page, on_pause=watch.pause,
+                                        on_resume=watch.resume, autostart=autostart, events=watch.events)
+        url = pairing_page.start()
+        watching = threading.Thread(target=watch.run, daemon=True)
+        try:
+            run.publish(pairing_page.port)
+            print(f"page: {url}", flush=True)
+            if not args.quiet and not opener(url):  # a start by a person opens the page, linked or not
+                print("open the address above in a browser", flush=True)
+            watching.start()
+            while True:
+                state.tick()
+                if stop.wait(TICK_SECONDS):
+                    break
+        except KeyboardInterrupt:
+            pass
+        finally:
+            stop.set()
+            # First, so a start made while this one stops waits for it instead of opening a closing page: Ctrl+C
+            # and Ctrl+Break are marked only here, and the page's quit, marked already, is marked again.
+            try:
+                run.mark_closing()
+            except OSError:
+                pass  # unmarked, a start meanwhile opens this page as before; the stop goes on
+            if watching.is_alive():
+                watching.join(STOP_SECONDS)
+            alerter.flush(STOP_SECONDS)
+            pairing_page.close()
+    finally:
+        run.release()
+    return 0
+
+
+def _break_as_interrupt():
+    """Ctrl+Break stops the program as Ctrl+C does; only on Windows and only on the main thread."""
+    if not hasattr(signal, "SIGBREAK") or threading.current_thread() is not threading.main_thread():
+        return None
+    return signal.signal(signal.SIGBREAK, signal.default_int_handler)
+
+
+def main(argv=None, *, opener=webbrowser.open, stop=None, timeout=worker.TIMEOUT_SECONDS, delay=None,
+         beep=alert.beep, box=_message_box, autostart=None, console=_console_attached, clock=time.monotonic,
+         sleep=time.sleep):
+    """`beep`, `box` and `autostart` are the seams of the sound, of the message box and of the start with Windows
+    (the per-user Run value when None): a test run passes silent ones and a fake. `console` says whether a printed
+    line reaches anybody; `clock` and `sleep` time the run file's re-reads."""
+    args = _arguments(sys.argv[1:] if argv is None else argv)
+    store = config.ConfigStore(getattr(args, "data_dir", None) or config.default_base_dir())
+    base = getattr(args, "worker", worker.BASE_URL)
+
+    def show(line):  # a start's last line, also in a message box where no console is attached
+        if not console():
+            box(line)
+
+    try:
+        if args.command == "ping":
+            return _ping(store, base, args.kind, timeout)
+        previous = _break_as_interrupt()
+        try:
+            return _serve(args, store, base, timeout, opener, stop or threading.Event(),
+                          delay or watcher.accept_delay, beep, show, clock, sleep,
+                          autostart if autostart is not None else Autostart())
+        finally:
+            if previous is not None:
+                signal.signal(signal.SIGBREAK, previous)
+    except config.ConfigError as failure:  # at start or mid-run: its one sentence, never a traceback
+        print(failure)
+        if args.command != "ping":  # a start ends on it
+            show(str(failure))
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pendify/alert.py

@@ -0,0 +1,132 @@
+"""An alert: the beep of S:161-169 and, with a stored link id, the ping of its kind off the watcher's thread.
+
+Every alert beeps and names a kind (S:336-355). The ping's result goes to the pairing state through record_ping,
+as lane lnk5a's ping command answers it, so three refusals in a row offer the relink, and its name and time stay
+for the page as the last ping. With no link id nothing is sent and nothing is queued. sound() is the beep
+alone, with no kind and no ping. The console gets fixed lines only. listen() names the one callback told each ping's
+result name and time right after they are recorded (the watcher's log, lane pclog).
+"""
+import threading
+import time
+
+from . import worker
+
+try:
+    import winsound
+except ImportError:  # not Windows: the beep is silent, as in the script
+    winsound = None
+
+BEEP_NOTES = (988, 1319)  # S:167
+BEEP_ROUNDS = 3  # S:166
+BEEP_MILLISECONDS = 160  # S:168
+PING_LINES = {"sent": "alert: sent to the phone", "refused": "alert: refused, link this PC again from the page",
+              "not_delivered": "alert: not delivered", "failed": "alert: failed"}
+CONFIG_UNREADABLE_LINE = "alert: the config file could not be read, nothing was sent"
+BEEP_FAILED_LINE = "alert: the sound device refused the beep"
+
+
+def _print(line):
+    print(line, flush=True)
+
+
+def _start_daemon(target):
+    thread = threading.Thread(target=target, daemon=True)
+    thread.start()
+    return thread
+
+
+def beep(sound=winsound, start=_start_daemon):
+    """The script's siren, three rounds of two notes, on a thread of its own; None without the module."""
+    if sound is None:
+        return None
+
+    def play():
+        try:
+            for _ in range(BEEP_ROUNDS):
+                for frequency in BEEP_NOTES:
+                    sound.Beep(frequency, BEEP_MILLISECONDS)
+        except RuntimeError:  # winsound's answer when the system cannot play it
+            _print(BEEP_FAILED_LINE)
+
+    return start(play)
+
+
+def _result_name(result):
+    if isinstance(result, worker.Sent):
+        return "sent"
+    if isinstance(result, worker.Refused):
+        return "refused"
+    if isinstance(result, worker.NotDelivered):
+        return "not_delivered"
+    return "failed"
+
+
+class Alerter:
+    def __init__(self, store, state, ping, *, beep=beep, start=None, log=None, wall=time.time):
+        self._store, self._state, self._ping, self._beep = store, state, ping, beep
+        self._start = start or _start_daemon
+        self._log = log or _print
+        self._wall = wall
+        self._lock = threading.Lock()
+        self._pending = []
+        self._last_ping = (None, None)
+        self._listener = None
+
+    def __call__(self, kind):
+        """Beeps; with a stored link id, sends the ping of `kind` on a thread of its own."""
+        self._beep()
+        try:
+            pair = self._store.read()  # read at each alert: a link made on the page counts at once
+        except OSError:
+            self._log(CONFIG_UNREADABLE_LINE)
+            return
+        if pair is None or pair.link_id is None:
+            return
+        done = threading.Event()
+        with self._lock:
+            self._pending = [event for event in self._pending if not event.is_set()] + [done]
+        self._start(lambda: self._send(pair, kind, done))
+
+    def listen(self, callback):
+        """`callback(name, at)` is told each ping's result name and wall time on the ping's thread, right after the
+        last ping records them; a later call replaces it. A callback that raises is swallowed: the record stands and
+        the ping's line is said."""
+        with self._lock:
+            self._listener = callback
+
+    def sound(self):
+        """Beeps and nothing else: no ping, nothing queued, the last ping as it was."""
+        self._beep()
+
+    def _send(self, pair, kind, done):
+        try:
+            try:
+                result = self._ping(pair.link_id, pair.secret, kind)
+            except Exception as failure:  # a refused input raises a fixed sentence; it still ends as failed
+                result = worker.Failed(type(failure).__name__)
+            self._state.record_ping(result)
+            name, at = _result_name(result), self._wall()
+            with self._lock:
+                self._last_ping = (name, at)
+                listener = self._listener
+            if listener is not None:
+                try:
+                    listener(name, at)
+                except Exception:  # the log's listener never costs the ping its record or its line
+                    pass
+            self._log(PING_LINES[name])
+        finally:
+            done.set()
+
+    def last_ping(self):
+        """The last ping's result name (sent, refused, not_delivered or failed) and its wall time; (None, None)
+        before any ping was made."""
+        with self._lock:
+            return self._last_ping
+
+    def flush(self, timeout):
+        """Waits up to `timeout` seconds for the pings in flight; True when none is left."""
+        deadline = time.monotonic() + timeout
+        with self._lock:
+            pending = list(self._pending)
+        return all(event.wait(max(0.0, deadline - time.monotonic())) for event in pending)

pendify/autostart.py

@@ -0,0 +1,105 @@
+"""The start with Windows: the per-user Run value, no administrator.
+
+The value `PendiFy` under HKEY_CURRENT_USER's Run key holds the start line of install.ps1 plus --quiet, so the
+program starts at logon with no browser. Only the page writes it, on its person's ask; a start never writes it,
+and install.ps1 only rewrites one that exists. The registry is a seam of three calls on one value under one key
+path; the real one imports winreg inside itself and takes the key path as an argument, so a test points it at a
+scratch key. Where winreg cannot be imported the start with Windows is not available, and the page shows and
+routes nothing of it. A registry failure is one sentence on stderr, by its type only, and changes nothing.
+"""
+import sys
+from pathlib import Path
+
+RUN_KEY = r"Software\Microsoft\Windows\CurrentVersion\Run"
+VALUE_NAME = "PendiFy"
+START_ARGS = "-m pendify --quiet"
+FAILED_LINE = "autostart: the start with Windows could not be {what} ({kind})"
+
+
+class WindowsRegistry:
+    """One value under one key path of HKEY_CURRENT_USER: read, write and delete, nothing else. Built, it reads
+    nothing; an import of winreg that fails is the caller's ImportError."""
+
+    def __init__(self, key_path=RUN_KEY, name=VALUE_NAME):
+        import winreg
+
+        self._winreg, self.key_path, self.name = winreg, key_path, name
+
+    def read(self):
+        """The value's text, or None when the key or the value is missing."""
+        winreg = self._winreg
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, self.key_path) as key:
+                return winreg.QueryValueEx(key, self.name)[0]
+        except FileNotFoundError:
+            return None
+
+    def write(self, text):
+        winreg = self._winreg
+        with winreg.CreateKeyEx(winreg.HKEY_CURRENT_USER, self.key_path, 0, winreg.KEY_SET_VALUE) as key:
+            winreg.SetValueEx(key, self.name, 0, winreg.REG_SZ, text)
+
+    def delete(self):
+        """The value removed; a missing key or value is nothing to remove, no error."""
+        winreg = self._winreg
+        try:
+            with winreg.OpenKey(winreg.HKEY_CURRENT_USER, self.key_path, 0, winreg.KEY_SET_VALUE) as key:
+                winreg.DeleteValue(key, self.name)
+        except FileNotFoundError:
+            pass
+
+
+def _say_failure(what, failure):
+    print(FAILED_LINE.format(what=what, kind=type(failure).__name__), file=sys.stderr, flush=True)
+
+
+class Autostart:
+    def __init__(self, registry=None, executable=None):
+        """`registry` is the seam of the three calls, the real Run value when None; `executable` is the
+        interpreter whose start line is written, this one when None."""
+        if registry is None:
+            try:
+                registry = WindowsRegistry()
+            except ImportError:  # no winreg on this system: no Run value to keep
+                registry = None
+        self.registry = registry
+        self.available = registry is not None
+        self._executable = executable or sys.executable
+
+    def enabled(self):
+        """True when the value exists; False when it does not, when not available, or when it cannot be read."""
+        if not self.available:
+            return False
+        try:
+            return self.registry.read() is not None
+        except OSError as failure:
+            _say_failure("read", failure)
+            return False
+
+    def enable(self):
+        """The value written with command(); True when written."""
+        return self._change("written", lambda: self.registry.write(self.command()))
+
+    def disable(self):
+        """The value deleted, a missing one being no error; True when it is gone."""
+        return self._change("removed", lambda: self.registry.delete())
+
+    def command(self):
+        """install.ps1's start line plus --quiet: pythonw.exe beside the interpreter when that file exists, else
+        the interpreter, quoted when its path holds a space (install.ps1's Format-Arg)."""
+        interpreter = Path(self._executable)
+        windowless = interpreter.with_name("pythonw.exe")
+        chosen = str(windowless if windowless.is_file() else interpreter)
+        if any(character.isspace() for character in chosen):
+            chosen = f'"{chosen}"'
+        return f"{chosen} {START_ARGS}"
+
+    def _change(self, what, change):
+        if not self.available:
+            return False
+        try:
+            change()
+        except OSError as failure:
+            _say_failure(what, failure)
+            return False
+        return True