chartremotely 0.2.0__py3-none-any.whl

chartremotely/timeframe.py

@@ -0,0 +1,210 @@
+"""Drive the chart's aggregation (time frame).
+
+The presets live in a Java *lightweight* popup painted inside the window,
+which is the most awkward control in the application:
+
+* its rows are ``AXStaticText`` with no actions, so nothing can be pressed
+* it ignores process-targeted mouse events entirely - no hover, no click
+* arrow keys do not move its selection
+* it dismisses when window activation changes
+
+Only a real HID click works, which means the target must be uncovered
+*before* the popup opens. Clearing occluders afterwards dismisses it.
+
+Spoken mnemonics are chosen for phonetic distance rather than literal
+accuracy. Digits are the worst thing to say to a recogniser - "fifteen" and
+"fifty" collide - so the vocabulary avoids them.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+from . import ax, config, layout
+from .scales import AS_IS, MNEMONIC, canon, to_code
+
+ITEM = re.compile(r"^\s*\d+\s*[DYW]\s*:\s*\S+", re.IGNORECASE)
+
+class MenuError(RuntimeError):
+    """The aggregation menu could not be opened or read."""
+
+
+def _is_style_control(element) -> bool:
+    if element is None or ax.attr(element, "AXRole") != "AXCheckBox":
+        return False
+    label = ax.attr(element, "AXTitle") or ax.attr(element, "AXDescription")
+    return label == "Style"
+
+
+def discover(ax_app, window_prefix: str) -> tuple[int, int] | None:
+    """Find the aggregation toggle by its labelled neighbour.
+
+    The toggle carries no label, but "Style" sits immediately right of it
+    and does. Anchoring on a named control rather than a coordinate is what
+    survives a different layout: find Style wherever it is, then step left.
+    """
+    style = layout.find_in_panes(ax_app, window_prefix, _is_style_control)
+    if style is None:
+        return None
+    element = ax.element_at(ax_app, *style)
+    origin = ax.position(element)
+    if origin is None:
+        return None
+    for dx in range(10, 160, 4):
+        x, y = int(origin.x) - dx, int(origin.y) + 12
+        candidate = ax.element_at(ax_app, x, y)
+        if candidate is None or ax.attr(candidate, "AXRole") != "AXCheckBox":
+            continue
+        label = ax.attr(candidate, "AXTitle") or ax.attr(candidate, "AXDescription")
+        if not label and "AXPress" in ax.actions(candidate):
+            return x, y
+    return None
+
+
+def learn(app=None) -> dict:
+    app = app or ax.running_app()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    cfg = config.load()
+    found = discover(ax_app, cfg["window_prefix"])
+    if found is None:
+        raise MenuError("aggregation control not found; is a chart visible?")
+    win = ax.window(ax_app, cfg["window_prefix"])
+    origin = ax.position(win)
+    return config.update(aggregation_dx=int(found[0] - origin.x),
+                         aggregation_dy=int(found[1] - origin.y))
+
+
+def _control(ax_app, cfg):
+    win = ax.window(ax_app, cfg["window_prefix"])
+    if win is None:
+        raise MenuError(f"no window titled {cfg['window_prefix']!r}")
+    origin = ax.position(win)
+    if cfg.get("aggregation_dx") is None:
+        raise MenuError("aggregation control not learned; run doctor")
+    x = int(origin.x) + cfg["aggregation_dx"]
+    y = int(origin.y) + cfg["aggregation_dy"]
+    return ax.element_at(ax_app, x, y), (x, y)
+
+
+def _open(ax_app, cfg):
+    """Open the popup if it is closed.
+
+    The control is a TOGGLE. Pressing it while the menu is already showing
+    closes it, so a blind press is a coin flip.
+    """
+    element, point = _control(ax_app, cfg)
+    if element is None:
+        raise MenuError(f"no aggregation control at {point}")
+    if ax.attr(element, "AXValue") in (0, "0", False, None):
+        ax.perform(element, "AXPress")
+        time.sleep(0.9)
+    return element
+
+
+def _rows(ax_app) -> list[dict]:
+    """Every preset the popup offers, with its centre and active flag.
+
+    The list is the user's favourites, so never assume a fixed set or order.
+    """
+    found: list[dict] = []
+    seen: set[str] = set()
+
+    def visit(element):
+        for name in ("AXValue", "AXTitle", "AXDescription"):
+            value = ax.attr(element, name)
+            if isinstance(value, str) and ITEM.match(value.strip()):
+                label = value.strip()
+                spot = ax.centre(element)
+                if spot and label not in seen:
+                    seen.add(label)
+                    parent = ax.attr(element, "AXParent")
+                    found.append({
+                        "label": label, "x": spot[0], "y": spot[1],
+                        "active": bool(parent is not None
+                                       and ax.attr(parent, "AXSelected")),
+                    })
+                break
+
+    for window in ax.attr(ax_app, "AXWindows") or []:
+        ax.walk(window, visit)
+    return found
+
+
+def presets(app=None) -> list[str]:
+    app = app or ax.running_app()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    _open(ax_app, config.load())
+    rows = _rows(ax_app)
+    ax.escape(app.processIdentifier())
+    return [r["label"] for r in rows]
+
+
+def current(app=None) -> tuple[str, str]:
+    """The active preset as (label, mnemonic), without changing anything."""
+    app = app or ax.running_app()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    _open(ax_app, config.load())
+    rows = _rows(ax_app)
+    ax.escape(app.processIdentifier())
+    active = next((r for r in rows if r["active"]), None)
+    if active is None:
+        raise MenuError("could not read the current scale")
+    label = active["label"]
+    return label, MNEMONIC.get(canon(label), label)
+
+
+def set_scale(phrase: str, app=None) -> tuple[str, str]:
+    """Select a preset. Returns (label, mnemonic)."""
+    if phrase.lower().strip() in AS_IS:
+        return current(app)
+
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    cfg = config.load()
+
+    # Uncover the target BEFORE opening the popup: hiding an application
+    # shuffles window activation, and a lightweight popup dismisses when
+    # that happens.
+    _, point = _control(ax_app, cfg)
+    probes = [point] + [(point[0] - 120 + dx, point[1] + dy)
+                        for dx in (0, 160, 320) for dy in (40, 200, 380)]
+    blockers: list[int] = []
+    for px, py in probes:
+        blockers += ax.occluders_at(px, py, pid)
+    hidden = ax.hide_apps(list(dict.fromkeys(blockers)))
+    time.sleep(0.4)
+
+    try:
+        _open(ax_app, cfg)
+        rows = _rows(ax_app)
+        if not rows:
+            raise MenuError("aggregation menu did not open")
+
+        want = to_code(phrase)
+        if not want:
+            # canon() yields "" for an unparseable phrase, and every string
+            # ends with "", so the loose match below would select whatever
+            # happened to be first. Refuse instead.
+            raise MenuError(f"could not parse timeframe {phrase!r}")
+        match = next((r for r in rows if canon(r["label"]) == want), None)
+        if match is None:
+            match = next((r for r in rows if canon(r["label"]).endswith(want)), None)
+        if match is None:
+            offered = ", ".join(r["label"] for r in rows)
+            raise MenuError(f"no preset matches {phrase!r}; this chart offers: {offered}")
+
+        ax.click(match["x"], match["y"], pid)
+        time.sleep(0.5)
+        label = match["label"]
+        return label, MNEMONIC.get(canon(label), label)
+    except Exception:
+        ax.escape(pid)
+        raise
+    finally:
+        ax.unhide_apps(hidden)

chartremotely/vocab.py

@@ -0,0 +1,140 @@
+"""The complete command vocabulary. This file is the security boundary.
+
+Everything a caller can ask the agent to do is in the dispatch table below.
+There is no command that opens an order ticket, submits a trade, moves
+money, or reads an account. Adding one means editing this file - in public,
+in this repository - which is the point.
+
+Two rules the callers depend on:
+
+* **Never raise.** Every path returns text. The operator relays this to a
+  Shortcut, and a Shortcut treats a non-zero exit or an exception as a hard
+  failure, aborting before it can read the message.
+* **Keep it short.** These strings get read aloud. Nobody wants a stack
+  trace spoken at them from across the room.
+"""
+
+from __future__ import annotations
+
+from . import push, registry, resolve, scales, snapshot, symbol, timeframe, window
+
+ERR = "ERR "
+
+
+def _short(text: str, limit: int = 120) -> str:
+    return str(text).splitlines()[0][:limit] if text else "something went wrong"
+
+
+def cmd_resolve(spoken: str) -> str:
+    """A spoken company name, to a ticker."""
+    if not spoken.strip():
+        return ERR + "I didn't catch a company name."
+    try:
+        ticker = resolve.resolve(spoken, registry.load())
+    except Exception as exc:
+        return ERR + _short(exc)
+    return ticker or ERR + f"no match for {spoken!r}"
+
+
+def cmd_scale(spoken: str) -> str:
+    """A spoken time frame, to a mnemonic - without touching the chart."""
+    phrase = spoken.strip()
+    if phrase.lower() in scales.AS_IS:
+        return "as is"
+    word = scales.mnemonic_for(phrase)
+    if word:
+        return word
+    return ERR + f"You say {scales.spoken_options()}."
+
+
+def cmd_set(ticker: str, scale: str = "") -> str:
+    """Put a ticker on the chart, optionally at a given scale.
+
+    Degrades deliberately: an unparseable scale leaves the chart alone and
+    says which scale it is actually on, so the answer is never ambiguous to
+    someone who cannot see the screen.
+    """
+    ticker = ticker.strip().replace(" ", "")
+    if not ticker:
+        return ERR + "No symbol to show."
+    try:
+        symbol.show(ticker)
+    except Exception as exc:
+        return ERR + _short(exc)
+
+    word = None
+    if scale.strip() and scale.strip().lower() not in scales.AS_IS:
+        try:
+            _, word = timeframe.set_scale(scale)
+        except Exception:
+            word = None
+
+    # Uncover the chart: a voice answer is only useful if the screen shows it.
+    try:
+        window.clear()
+    except Exception:
+        pass
+
+    if word:
+        return f"Showing {ticker} at {word}. Good luck."
+    try:
+        _, current = timeframe.current()
+        return f"Showing {ticker} at {current}, as is. Good luck."
+    except Exception:
+        return f"Showing {ticker}. Good luck."
+
+
+def cmd_read() -> str:
+    """Report the chart's current symbol and scale."""
+    try:
+        ticker = symbol.current()
+        _, word = timeframe.current()
+        return f"{ticker} at {word}"
+    except Exception as exc:
+        return ERR + _short(exc)
+
+
+def cmd_snapshot() -> str:
+    """A picture of the chart pane, so a caller far away can see it."""
+    try:
+        return snapshot.as_reply(snapshot.shrink(window.capture()))
+    except Exception as exc:
+        return ERR + _short(exc)
+
+
+def dispatch(request: str) -> str:
+    """Route one request. Anything unrecognised is treated as a company name.
+
+    The entire surface:
+
+        resolve <spoken name>              -> TICKER | ERR
+        scale   <spoken time frame>        -> mnemonic | ERR
+        set     <TICKER> | <time frame>    -> spoken summary
+        read                               -> current symbol and scale
+        snapshot                           -> data:image/jpeg;base64,... | ERR
+        <spoken name>                      -> resolve, then set
+    """
+    request = (request or "").strip()
+    if not request:
+        return ERR + "I didn't catch that."
+
+    verb, _, rest = request.partition(" ")
+    verb = verb.lower()
+
+    if verb == "resolve":
+        return cmd_resolve(rest)
+    if verb == "scale":
+        return cmd_scale(rest)
+    if verb == "read":
+        return cmd_read()
+    if verb == "snapshot":
+        return cmd_snapshot()
+    if verb == "set":
+        ticker, sep, scale = rest.partition("|")
+        return push.after_change(cmd_set(ticker, scale if sep else ""))
+
+    # Bare name: resolve and show it.
+    ticker = cmd_resolve(request)
+    if ticker.startswith(ERR):
+        return ticker
+    return push.after_change(cmd_set(ticker))

chartremotely/window.py

@@ -0,0 +1,134 @@
+"""Make the chart visible, and prove what it shows.
+
+A voice command answered from across the room is only useful if the chart
+is actually on screen, and only trustworthy if the caller can see that it
+changed. Both matter more remotely than locally: at the desk you can see it
+worked; from another building a silent failure is indistinguishable from
+success.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+import Quartz
+from AppKit import NSWorkspace
+
+from . import ax, config, layout, snapshot, symbol
+
+
+def _frame(pid: int) -> dict | None:
+    """Bounds of the largest on-screen thinkorswim window."""
+    best, best_area = None, -1
+    for w in Quartz.CGWindowListCopyWindowInfo(
+            Quartz.kCGWindowListOptionOnScreenOnly, Quartz.kCGNullWindowID):
+        if w.get("kCGWindowOwnerPID") != pid:
+            continue
+        b = w.get("kCGWindowBounds") or {}
+        area = b.get("Width", 0) * b.get("Height", 0)
+        if area > best_area:
+            best, best_area = w, area
+    return best
+
+
+def _overlaps(a: dict, b: dict) -> bool:
+    return not (a.get("X", 0) + a.get("Width", 0) <= b.get("X", 0)
+                or a.get("X", 0) >= b.get("X", 0) + b.get("Width", 0)
+                or a.get("Y", 0) + a.get("Height", 0) <= b.get("Y", 0)
+                or a.get("Y", 0) >= b.get("Y", 0) + b.get("Height", 0))
+
+
+def clear(app=None) -> list[str]:
+    """Hide every ordinary app overlapping the chart, then raise it.
+
+    Only regular apps are touched - system overlays keep permanent
+    full-screen windows and are neither hideable nor actually in the way.
+    """
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    target = _frame(pid)
+    if target is None:
+        return []
+    bounds = target["kCGWindowBounds"]
+
+    regular = {a.processIdentifier(): a
+               for a in NSWorkspace.sharedWorkspace().runningApplications()
+               if a.activationPolicy() == 0 and a.processIdentifier() != pid}
+
+    covering = {w["kCGWindowOwnerPID"]
+                for w in Quartz.CGWindowListCopyWindowInfo(
+                    Quartz.kCGWindowListOptionOnScreenOnly, Quartz.kCGNullWindowID)
+                if w.get("kCGWindowOwnerPID") in regular
+                and w.get("kCGWindowLayer", 0) >= 0
+                and _overlaps(w.get("kCGWindowBounds") or {}, bounds)}
+
+    hidden = []
+    for p in covering:
+        a = regular[p]
+        if not a.isHidden():
+            a.hide()
+            hidden.append(a.localizedName() or str(p))
+    if hidden:
+        time.sleep(0.4)
+    app.activateWithOptions_(2)
+    return sorted(hidden)
+
+
+def capture(app=None) -> bytes:
+    """PNG of the chart's own pane, and nothing else in the window.
+
+    Captured by window id rather than screen region, so it works even when
+    something is floating on top - which is what makes it usable as proof
+    that a remote command landed. Then cropped to the pane that holds the
+    chart's symbol field; see :func:`snapshot.chart_crop` for why the rest of
+    the window never leaves this machine.
+    """
+    app = app or ax.running_app()
+    target = _frame(app.processIdentifier())
+    if target is None:
+        raise ax.NotRunning("no thinkorswim window on screen")
+    b = target["kCGWindowBounds"]
+    bounds = (int(b["X"]), int(b["Y"]), int(b["Width"]), int(b["Height"]))
+
+    # Hit-testing answers from the menu bar unless the app is in front.
+    ax.activate(app)
+    ax_app = ax.handle(app)
+    prefix = config.load()["window_prefix"]
+    hit = symbol.discover(ax_app, prefix)
+    if hit is None:
+        raise snapshot.ChartNotIsolated("no chart is visible")
+    panes = layout.panes(ax_app, prefix)
+
+    with tempfile.TemporaryDirectory() as tmp:
+        shot = Path(tmp) / "window.png"
+        subprocess.run(["screencapture", "-x", "-o", "-l", str(target["kCGWindowNumber"]), str(shot)],
+                       check=True, capture_output=True)
+        crop = snapshot.chart_crop(hit, panes, bounds, _pixel_size(shot))
+        chart = Path(tmp) / "chart.png"
+        _crop(shot, chart, *crop)
+        return chart.read_bytes()
+
+
+def _image(path: Path):
+    from CoreFoundation import CFURLCreateWithFileSystemPath, kCFURLPOSIXPathStyle
+
+    url = CFURLCreateWithFileSystemPath(None, str(path), kCFURLPOSIXPathStyle, False)
+    return Quartz.CGImageSourceCreateImageAtIndex(Quartz.CGImageSourceCreateWithURL(url, None), 0, None)
+
+
+def _pixel_size(path: Path) -> tuple[int, int]:
+    image = _image(path)
+    return Quartz.CGImageGetWidth(image), Quartz.CGImageGetHeight(image)
+
+
+def _crop(src: Path, dst: Path, x: int, y: int, w: int, h: int) -> None:
+    from CoreFoundation import CFURLCreateWithFileSystemPath, kCFURLPOSIXPathStyle
+
+    region = Quartz.CGImageCreateWithImageInRect(_image(src), Quartz.CGRectMake(x, y, w, h))
+    out_url = CFURLCreateWithFileSystemPath(None, str(dst), kCFURLPOSIXPathStyle, False)
+    dest = Quartz.CGImageDestinationCreateWithURL(out_url, "public.png", 1, None)
+    Quartz.CGImageDestinationAddImage(dest, region, None)
+    Quartz.CGImageDestinationFinalize(dest)