chartremotely 0.2.9__tar.gz → 0.2.11__tar.gz

{chartremotely-0.2.9 → chartremotely-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartremotely
-Version: 0.2.9
+Version: 0.2.11
 Summary: Remote control of desktop charting applications on macOS
 Author: Lonnie VanZandt
 License: 

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely/ax.py

@@ -22,7 +22,7 @@ from __future__ import annotations
 import time
 
 import Quartz
-from AppKit import NSWorkspace
+from AppKit import NSRunningApplication, NSWorkspace
 from ApplicationServices import (
     AXUIElementCopyActionNames,
     AXUIElementCopyAttributeValue,
@@ -57,11 +57,25 @@ class NotRunning(RuntimeError):
     """thinkorswim is not running."""
 
 
+def app_for(pid: int):
+    """The running application with ``pid``, looked up now; None if gone.
+
+    Never from ``NSWorkspace.runningApplications()``: that list only
+    refreshes on a run loop, which the listener and relay never spin, so an
+    app launched (or quit) after they started is missing from it (or lingers).
+    """
+    return NSRunningApplication.runningApplicationWithProcessIdentifier_(pid)
+
+
 def running_app():
-    for a in NSWorkspace.sharedWorkspace().runningApplications():
-        if APP_NAME.lower() in (a.localizedName() or "").lower():
-            return a
-    raise NotRunning(f"{APP_NAME} is not running")
+    """thinkorswim, found through the window server's live list of windows."""
+    for w in Quartz.CGWindowListCopyWindowInfo(
+            Quartz.kCGWindowListOptionAll, Quartz.kCGNullWindowID) or []:
+        if APP_NAME.lower() in (w.get("kCGWindowOwnerName") or "").lower():
+            app = app_for(w["kCGWindowOwnerPID"])
+            if app is not None:
+                return app
+    raise NotRunning(f"{APP_NAME} is not open on this Mac")
 
 
 def handle(app=None):

chartremotely-0.2.11/chartremotely/popups.py

@@ -0,0 +1,258 @@
+"""Close thinkorswim's popups before anyone looks at the chart.
+
+Two popups get left open over the chart, and a picture taken then shows them:
+
+* the symbol field's autocomplete list (PLTR:XTSE, PLTRX, ...), which hangs
+  under the field after a symbol is typed and often outlives the Return that
+  committed it;
+* the aggregation (time frame) menu, which stays open after a preset is
+  picked or the current one is read.
+
+Neither answers the obvious remedies. An Escape posted to thinkorswim lands on
+whatever holds keyboard focus, which after a commit is nothing at all - so it
+is silently dropped. What works, measured on thinkorswim build 1993:
+
+* the aggregation menu closes when its toggle is pressed again (``AXPress``);
+  the toggle's ``AXValue`` is 1 while the menu shows;
+* the autocomplete list closes on Escape once the symbol field has focus.
+  Escape only hides the list: text typed but not yet committed stays in the
+  field, so it never cancels an entry;
+* focus leaves the field when the chart's own title strip (the line under
+  the field reading "PLTR 10 D 30m") is focused. Setting the field's
+  ``AXFocused`` to false is accepted and ignored.
+
+A Swing field commits its text when it loses focus, so focus is moved off the
+field only when that text is what the chart already shows. Otherwise the field
+keeps focus and its pending text, and nothing changes.
+
+The decisions are pure and live at module scope, over a :class:`Seen`
+snapshot, so they are tested where PyObjC is absent. :func:`dismiss` gathers
+the snapshots and acts; its macOS imports are deferred.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+Rect = tuple[float, float, float, float]
+
+#: Longest dismiss() spends closing popups.
+TIMEOUT = 1.5
+#: How often dismiss() looks again after acting.
+POLL = 0.1
+#: Longest dismiss() waits for one action to show before trying it again.
+ACT_WAIT = 0.5
+#: Points of slack when deciding a list hangs from the symbol field.
+SLACK = 8
+#: How far under the field's bottom edge to hit-test for a list or the title.
+PROBE_DY, PROBE_DX = 8, 8
+
+#: The first word of the chart's title strip: the symbol it is drawn for.
+CHART_SYMBOL = re.compile(r"^[./$^]?[A-Z0-9]{1,12}([/.][A-Z0-9]{1,3})?(:[A-Z]+)?$")
+
+CLOSE_SCALE, CLOSE_LIST, LEAVE_FIELD = "close scale menu", "close symbol list", "leave field"
+
+
+@dataclass(frozen=True)
+class Seen:
+    """What the chart's popups and symbol field looked like at one moment."""
+
+    scale_open: bool = False
+    list_open: bool = False
+    field_focused: bool = False
+    field_value: str | None = None
+    #: The chart's title strip, e.g. "PLTR 10 D 30m"; None while a list covers it.
+    title: str | None = None
+
+    @property
+    def clean(self) -> bool:
+        """Nothing is drawn over the chart."""
+        return not (self.scale_open or self.list_open)
+
+
+def hangs_under(field: Rect, table: Rect | None) -> bool:
+    """Whether ``table`` is the autocomplete list dropped from the symbol field.
+
+    thinkorswim paints that list inside the window, so the window server never
+    sees it; the accessibility tree reports it as a table whose top-left corner
+    sits on the field's bottom-left corner. ``field`` is the field's combo box.
+    """
+    if table is None:
+        return False
+    fx, fy, _, fh = field
+    tx, ty, tw, th = table
+    return (tw > 0 and th > 0 and abs(tx - fx) <= SLACK
+            and abs(ty - (fy + fh)) <= SLACK)
+
+
+def chart_symbol(title: str | None) -> str | None:
+    """The symbol a chart title strip names ("PLTR 10 D 30m" -> "PLTR"), or None."""
+    if not isinstance(title, str) or not title.strip():
+        return None
+    word = title.split()[0]
+    return word if CHART_SYMBOL.match(word) else None
+
+
+def shows(title: str | None, entry: str | None) -> bool:
+    """Whether the chart already shows what ``entry`` names.
+
+    A futures root typed as "/ES" is drawn as its front contract ("/ESZ26"),
+    so a root counts as shown by any of its contracts.
+    """
+    drawn = chart_symbol(title)
+    want = (entry or "").strip().upper()
+    if not drawn or not want:
+        return False
+    return drawn == want or (want.startswith("/") and drawn.startswith(want))
+
+
+def next_step(seen: Seen) -> str | None:
+    """The one thing to do next, or None when there is nothing safe left to do.
+
+    The menu is closed before the list: its toggle is pressed through the
+    tree, which needs no focus, whereas closing the list moves focus into the
+    field. Focus leaves the field only when the chart already shows its text,
+    because losing focus commits whatever the field holds.
+    """
+    if seen.scale_open:
+        return CLOSE_SCALE
+    if seen.list_open:
+        return CLOSE_LIST
+    if seen.field_focused and shows(seen.title, seen.field_value):
+        return LEAVE_FIELD
+    return None
+
+
+@dataclass(frozen=True)
+class Dismissed:
+    """What dismiss() did, and whether the chart was left uncovered."""
+
+    did: tuple[str, ...] = ()
+    clean: bool = True
+
+    def __bool__(self) -> bool:
+        return bool(self.did)
+
+    def __str__(self) -> str:
+        done = "; ".join(self.did) or "nothing open"
+        return done if self.clean else done + "; a popup is still open"
+
+
+def run(look: Callable[[], Seen], act: Callable[[str], None], *,
+        until: Callable[[Seen], bool] | None = None, timeout: float = TIMEOUT,
+        clock: Callable[[], float] = time.monotonic,
+        sleep: Callable[[float], None] = time.sleep) -> Dismissed:
+    """Look, act on the next step, and look again until nothing is left.
+
+    ``until``, when given, must also hold before it stops early: a symbol just
+    committed is waited for until the chart's title names it, so focus can
+    leave the field once it is safe to. One action is retried only after it
+    has had ACT_WAIT to show, so a slow repaint is not answered with a second
+    press of a toggle.
+    """
+    deadline = clock() + timeout
+    did: list[str] = []
+    last: tuple[str | None, float] = (None, -ACT_WAIT)
+    while True:
+        seen = look()
+        step = next_step(seen)
+        now = clock()
+        if step is None and (until is None or until(seen)) or now >= deadline:
+            return Dismissed(tuple(did), seen.clean)
+        if step is not None and (step != last[0] or now - last[1] >= ACT_WAIT):
+            act(step)
+            if step not in did:
+                did.append(step)
+            last = (step, now)
+        sleep(POLL)
+
+
+# --------------------------------------------------------------------------
+# macOS. Imported lazily so the decisions above stay importable anywhere.
+
+
+def _frame(ax, element) -> Rect | None:
+    p, s = ax.position(element), ax.size(element)
+    return (p.x, p.y, s.width, s.height) if p and s else None
+
+
+def _under_field(ax, ax_app, field):
+    """The combo's frame, the element just under it, and the list that is, if any."""
+    combo = ax.attr(field, "AXParent")
+    frame = _frame(ax, combo) if combo is not None else None
+    if frame is None:
+        return None, None, None
+    x, y, _, h = frame
+    hit = ax.element_at(ax_app, x + PROBE_DX, y + h + PROBE_DY)
+    table = None
+    for element in (hit, ax.attr(hit, "AXParent") if hit is not None else None):
+        if element is not None and ax.attr(element, "AXRole") == "AXTable":
+            table = element
+            break
+    return frame, hit, table
+
+
+def dismiss(app=None, expect: str | None = None, timeout: float = TIMEOUT) -> Dismissed:
+    """Close the symbol list and the scale menu, and take focus off the field.
+
+    ``expect`` is a symbol just committed: dismiss() then also waits, within
+    ``timeout``, for the chart's title to name it before it lets focus go.
+
+    Idempotent, and cheap when nothing is open: a few accessibility reads.
+    Call it with thinkorswim in front (hit-testing answers from the menu bar
+    otherwise), inside the chart lock, after the change it tidies up after.
+    A field or toggle that cannot be found is left alone rather than raised
+    about: tidying up must never turn a change that landed into an error.
+    """
+    from . import ax, config, symbol, timeframe
+
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    ax_app = ax.handle(app)
+    cfg = config.load()
+    try:
+        field, _ = symbol.locate(ax_app, cfg)
+    except symbol.NotFound:
+        field = None
+    try:
+        toggle, _ = timeframe._control(ax_app, cfg)
+    except timeframe.MenuError:
+        toggle = None
+    title = [None]
+
+    def look() -> Seen:
+        scale_open = toggle is not None and ax.attr(toggle, "AXValue") not in (0, "0", False, None)
+        if field is None:
+            return Seen(scale_open=scale_open)
+        frame, hit, table = _under_field(ax, ax_app, field)
+        list_open = frame is not None and hangs_under(
+            frame, _frame(ax, table) if table is not None else None)
+        title[0] = None if list_open else hit
+        return Seen(
+            scale_open=scale_open,
+            list_open=list_open,
+            field_focused=bool(ax.attr(field, "AXFocused")),
+            field_value=ax.attr(field, "AXValue"),
+            title=ax.attr(title[0], "AXValue") if title[0] is not None else None,
+        )
+
+    def act(step: str) -> None:
+        if step == CLOSE_SCALE:
+            ax.perform(toggle, "AXPress")
+        elif step == CLOSE_LIST:
+            # Escape reaches only the focused component; after a commit that
+            # is nothing, so the field is focused first.
+            if not ax.attr(field, "AXFocused"):
+                ax.set_attr(field, "AXFocused", True)
+                time.sleep(0.1)
+            ax.escape(pid)
+        elif step == LEAVE_FIELD:
+            # LEAVE_FIELD is only chosen when the element under the field
+            # read as the chart's title, so title[0] is that strip.
+            ax.set_attr(title[0], "AXFocused", True)
+
+    until = (lambda seen: shows(seen.title, expect)) if expect else None
+    return run(look, act, until=until, timeout=timeout)

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely/requestlog.py

@@ -51,3 +51,12 @@ def outcome(source: str, tool: str, where: str, error: str | None) -> None:
         print(" ".join(parts), file=sys.stderr, flush=True)
     except (OSError, ValueError):
         pass
+
+
+def note(source: str, text: str) -> None:
+    """One free-form line, e.g. what it took to bring the chart in front. Never raises."""
+    try:
+        print(f"{time.strftime('%Y-%m-%dT%H:%M:%S%z')} {source} {_clean(text, ERR_MAX)}",
+              file=sys.stderr, flush=True)
+    except (OSError, ValueError):
+        pass

chartremotely-0.2.11/chartremotely/screen.py

@@ -0,0 +1,116 @@
+"""Decisions about what is on screen, made from a snapshot of the window list.
+
+Getting the chart in front of someone takes macOS calls - unhide, activate,
+un-minimise, raise, hide what covers it - but deciding WHICH window is the
+chart, WHETHER it is on screen yet and WHAT covers it needs none of them. That
+half lives here, over plain dicts shaped like Quartz's window list, so it runs
+(and is tested) where PyObjC is absent. :mod:`window` feeds it.
+
+A window is a dict with ``kCGWindowOwnerPID``, ``kCGWindowLayer`` and
+``kCGWindowBounds`` (``X``, ``Y``, ``Width``, ``Height``), as
+``CGWindowListCopyWindowInfo`` reports it: front to back, on-screen only.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+
+Frame = tuple[float, float, float, float]
+
+#: Points of slack when matching the accessibility frame to the window list.
+TOLERANCE = 2.0
+
+
+def overlaps(a: dict, b: dict) -> bool:
+    """Whether two bounds dicts share any area."""
+    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 largest(windows: Iterable[dict], pid: int) -> dict | None:
+    """The largest window ``pid`` has on screen."""
+    best, best_area = None, -1.0
+    for w in windows:
+        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 showing(windows: Iterable[dict], pid: int, frame: Frame) -> dict | None:
+    """The on-screen window of ``pid`` whose bounds are ``frame``, or None.
+
+    ``frame`` is the chart window's (x, y, w, h) as the accessibility tree
+    reports it. Matching on it, rather than taking the app's largest window,
+    means a detached thinkorswim window left on screen does not count as the
+    chart being back.
+    """
+    for w in windows:
+        if w.get("kCGWindowOwnerPID") != pid:
+            continue
+        b = w.get("kCGWindowBounds") or {}
+        got = (b.get("X", 0), b.get("Y", 0), b.get("Width", 0), b.get("Height", 0))
+        if all(abs(g - f) <= TOLERANCE for g, f in zip(got, frame, strict=True)):
+            return w
+    return None
+
+
+def covering(windows: Iterable[dict], bounds: dict, pid: int,
+             regular: Iterable[int]) -> list[int]:
+    """Pids of ordinary apps with a window overlapping ``bounds``.
+
+    Only ``regular`` apps count: system overlays keep permanent full-screen
+    windows that are neither hideable nor actually in the way. Negative
+    layers are desktop furniture, never in front of the chart.
+    """
+    allowed = set(regular) - {pid}
+    found = [w["kCGWindowOwnerPID"] for w in windows
+             if w.get("kCGWindowOwnerPID") in allowed
+             and w.get("kCGWindowLayer", 0) >= 0
+             and overlaps(w.get("kCGWindowBounds") or {}, bounds)]
+    return list(dict.fromkeys(found))
+
+
+def wait_for(probe: Callable[[], object], timeout: float = 2.0, interval: float = 0.1,
+             clock: Callable[[], float] = time.monotonic,
+             sleep: Callable[[float], None] = time.sleep):
+    """Poll ``probe`` until it returns something truthy, for at most ``timeout`` seconds.
+
+    Returns that value, or None when time ran out. Always probes at least once.
+    """
+    deadline = clock() + timeout
+    while True:
+        found = probe()
+        if found:
+            return found
+        if clock() >= deadline:
+            return None
+        sleep(interval)
+
+
+@dataclass(frozen=True)
+class Presented:
+    """What it took to get the chart in front of the viewer."""
+
+    unhid: bool = False
+    unminimized: bool = False
+    raised: bool = False
+    hid: tuple[str, ...] = ()
+
+    def __bool__(self) -> bool:
+        return self.unhid or self.unminimized or self.raised or bool(self.hid)
+
+    def __str__(self) -> str:
+        done = [word for word, did in (("unhid", self.unhid),
+                                       ("unminimized", self.unminimized),
+                                       ("raised", self.raised)) if did]
+        if self.hid:
+            done.append("hid " + ", ".join(self.hid))
+        return "; ".join(done) or "already in front"

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely/symbol.py

@@ -13,11 +13,15 @@ import time
 
 import Quartz
 
-from . import ax, config, layout
+from . import ax, config, layout, popups
 
 # Accepts tickers, futures (/ES), indices (.SPX) and share classes (BRK/B).
 TICKER = re.compile(r"^[./$]?[A-Z]{1,6}([/.][A-Z]{1,2})?(:[A-Z]+)?$")
 
+#: Longest show() waits for the chart's title to name the new symbol.
+COMMIT_WAIT = 3.0
+
+
 class NotFound(RuntimeError):
     """The symbol field could not be located or did not validate."""
 
@@ -157,4 +161,10 @@ def show(ticker: str, app=None) -> str:
     ax.key(ax.KEY_RETURN, 0, pid)
     time.sleep(0.25)
     ax.key(ax.KEY_RETURN, 0, pid)
+
+    # The list can outlive both Returns and would sit over the chart - and
+    # over the chart's title, the one place that says the symbol took. Close
+    # it (Escape never discards a typed entry), wait for the title to name the
+    # ticker, then take focus off the field so nothing is left hanging.
+    popups.dismiss(app, expect=ticker, timeout=COMMIT_WAIT)
     return previous

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely/timeframe.py

@@ -7,6 +7,8 @@ which is the most awkward control in the application:
 * it ignores process-targeted mouse events entirely - no hover, no click
 * arrow keys do not move its selection
 * it dismisses when window activation changes
+* Escape does not close it (keyboard focus is elsewhere); pressing its
+  toggle again does - see :mod:`popups`
 
 Only a real HID click works, which means the target must be uncovered
 *before* the popup opens. Clearing occluders afterwards dismisses it.
@@ -21,7 +23,7 @@ from __future__ import annotations
 import re
 import time
 
-from . import ax, config, layout
+from . import ax, config, layout, popups
 from .scales import AS_IS, MNEMONIC, canon, to_code
 
 ITEM = re.compile(r"^\s*\d+\s*[DYW]\s*:\s*\S+", re.IGNORECASE)
@@ -138,7 +140,7 @@ def presets(app=None) -> list[str]:
     ax_app = ax.handle(app)
     _open(ax_app, config.load())
     rows = _rows(ax_app)
-    ax.escape(app.processIdentifier())
+    popups.dismiss(app)
     return [r["label"] for r in rows]
 
 
@@ -149,7 +151,7 @@ def current(app=None) -> tuple[str, str]:
     ax_app = ax.handle(app)
     _open(ax_app, config.load())
     rows = _rows(ax_app)
-    ax.escape(app.processIdentifier())
+    popups.dismiss(app)
     active = next((r for r in rows if r["active"]), None)
     if active is None:
         raise MenuError("could not read the current scale")
@@ -202,9 +204,8 @@ def set_scale(phrase: str, app=None) -> tuple[str, str]:
         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:
+        # Picked or refused, the menu must not stay over the chart.
+        popups.dismiss(app)
         ax.unhide_apps(hidden)
+    return label, MNEMONIC.get(canon(label), label)

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely/vocab.py

@@ -16,7 +16,7 @@ Two rules the callers depend on:
 
 from __future__ import annotations
 
-from . import guilock, registry, resolve, scales, snapshot, symbol, timeframe, window
+from . import guilock, registry, requestlog, resolve, scales, snapshot, symbol, timeframe, window
 from .answer import Answer
 
 ERR = "ERR "
@@ -26,6 +26,21 @@ def _short(text: str, limit: int = 120) -> str:
     return str(text).splitlines()[0][:limit] if text else "something went wrong"
 
 
+def _present() -> str | None:
+    """Get the chart in front of the viewer before driving it; see window.present.
+
+    Returns an ERR reply when it cannot be, else None. What it took (unhid,
+    raised, which apps it hid) goes to the log, never into the spoken reply.
+    """
+    try:
+        done = window.present()
+    except Exception as exc:
+        return ERR + _short(exc)
+    if done:
+        requestlog.note("present", str(done))
+    return None
+
+
 def cmd_resolve(spoken: str) -> str:
     """A spoken company name, to a ticker."""
     if not spoken.strip():
@@ -63,6 +78,9 @@ def set_chart(ticker: str, scale: str = "") -> Answer:
     ticker = ticker.strip().replace(" ", "")
     if not ticker:
         return Answer(ERR + "No symbol to show.")
+    refused = _present()
+    if refused:
+        return Answer(refused)
     try:
         symbol.show(ticker)
     except Exception as exc:
@@ -76,12 +94,6 @@ def set_chart(ticker: str, scale: str = "") -> Answer:
         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 Answer(f"Showing {ticker} at {word}. Good luck.", shown, word)
     try:
@@ -93,6 +105,9 @@ def set_chart(ticker: str, scale: str = "") -> Answer:
 
 def cmd_read() -> str:
     """Report the chart's current symbol and scale."""
+    refused = _present()
+    if refused:
+        return refused
     try:
         ticker = symbol.current()
         _, word = timeframe.current()
@@ -103,6 +118,9 @@ def cmd_read() -> str:
 
 def cmd_snapshot() -> str:
     """A picture of the chart pane, so a caller far away can see it."""
+    refused = _present()
+    if refused:
+        return refused
     try:
         return snapshot.as_reply(snapshot.shrink(window.capture()))
     except Exception as exc:

chartremotely-0.2.11/chartremotely/window.py

@@ -0,0 +1,170 @@
+"""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 . import ax, config, layout, popups, screen, snapshot, symbol
+
+#: NSApplicationActivateAllWindows | NSApplicationActivateIgnoringOtherApps:
+#: bring every thinkorswim window forward, even when another app is in front.
+ACTIVATE = 1 | 2
+#: Longest wait for the chart window to reach the screen after being raised.
+ON_SCREEN_WAIT = 2.0
+
+
+class NotOnScreen(RuntimeError):
+    """The chart window could not be brought on screen."""
+
+
+def _on_screen() -> list[dict]:
+    return list(Quartz.CGWindowListCopyWindowInfo(
+        Quartz.kCGWindowListOptionOnScreenOnly, Quartz.kCGNullWindowID) or [])
+
+
+def _frame(pid: int) -> dict | None:
+    """The largest on-screen thinkorswim window."""
+    return screen.largest(_on_screen(), pid)
+
+
+def _ax_frame(win) -> screen.Frame | None:
+    p, s = ax.position(win), ax.size(win)
+    return (p.x, p.y, s.width, s.height) if p and s else None
+
+
+def present(app=None) -> screen.Presented:
+    """Put the chart window in front of the viewer, before anything drives it.
+
+    Unhides thinkorswim, brings it forward, un-minimises and raises the chart
+    window (the one titled ``window_prefix``, which every driver works in),
+    waits until it is actually on screen - activation also switches to its
+    Space when it is full screen elsewhere - then hides the ordinary apps
+    overlapping it. Only regular apps are ever hidden: system overlays keep
+    permanent full-screen windows and are neither hideable nor in the way.
+
+    Run inside the chart lock, like every command that drives the chart.
+    """
+    app = app or ax.running_app()
+    pid = app.processIdentifier()
+    ax_app = ax.handle(app)
+    # Read from the process itself: NSRunningApplication's isHidden/isActive
+    # only refresh on a run loop, which the listener and relay never spin.
+    unhid = bool(ax.attr(ax_app, "AXHidden"))
+    raised = not ax.attr(ax_app, "AXFrontmost")
+    if unhid:
+        app.unhide()
+    app.activateWithOptions_(ACTIVATE)
+
+    prefix = config.load()["window_prefix"]
+    win = screen.wait_for(lambda: ax.window(ax_app, prefix), timeout=ON_SCREEN_WAIT)
+    if win is None:
+        raise NotOnScreen(f"no thinkorswim window titled {prefix!r}")
+    unminimized = bool(ax.attr(win, "AXMinimized"))
+    if unminimized:
+        ax.set_attr(win, "AXMinimized", False)
+    ax.perform(win, "AXRaise")
+    ax.set_attr(win, "AXMain", True)
+    ax.set_attr(win, "AXFocused", True)
+
+    def arrived():
+        frame = _ax_frame(win)
+        return frame and screen.showing(_on_screen(), pid, frame)
+
+    target = screen.wait_for(arrived, timeout=ON_SCREEN_WAIT)
+    if target is None:
+        raise NotOnScreen("the chart window did not come on screen")
+
+    hid = _uncover(pid, target["kCGWindowBounds"])
+    app.activateWithOptions_(ACTIVATE)
+    return screen.Presented(unhid=unhid, unminimized=unminimized,
+                            raised=raised or unminimized, hid=hid)
+
+
+def _uncover(pid: int, bounds: dict) -> tuple[str, ...]:
+    """Hide every ordinary app with a window over ``bounds``; their names."""
+    windows = _on_screen()
+    apps = {p: ax.app_for(p) for p in {w.get("kCGWindowOwnerPID") for w in windows} if p}
+    regular = {p: a for p, a in apps.items() if a is not None and a.activationPolicy() == 0}
+    hidden = []
+    # An app with a window on screen is not hidden, whatever a cached
+    # isHidden says; see present().
+    for p in screen.covering(windows, bounds, pid, regular):
+        a = regular[p]
+        a.hide()
+        hidden.append(a.localizedName() or str(p))
+    if hidden:
+        time.sleep(0.4)
+    return tuple(sorted(hidden))
+
+
+def capture(app=None) -> bytes:
+    """PNG of the chart's own pane, and nothing else in the window.
+
+    Any popup left over the chart is closed first; see :func:`popups.dismiss`.
+
+    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)
+    # Never photograph a symbol list or scale menu left over the chart.
+    popups.dismiss(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)

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chartremotely
-Version: 0.2.9
+Version: 0.2.11
 Summary: Remote control of desktop charting applications on macOS
 Author: Lonnie VanZandt
 License: 

{chartremotely-0.2.9 → chartremotely-0.2.11}/chartremotely.egg-info/SOURCES.txt

@@ -12,12 +12,14 @@ chartremotely/keystore.py
 chartremotely/layout.py
 chartremotely/mcpclient.py
 chartremotely/patron.py
+chartremotely/popups.py
 chartremotely/push.py
 chartremotely/registry.py
 chartremotely/relay.py
 chartremotely/requestlog.py
 chartremotely/resolve.py
 chartremotely/scales.py
+chartremotely/screen.py
 chartremotely/server.py
 chartremotely/services.py
 chartremotely/setup.py
@@ -37,10 +39,12 @@ chartremotely.egg-info/requires.txt
 chartremotely.egg-info/top_level.txt
 chartremotely/assets/shortcut-template.plist
 tests/test_patron.py
+tests/test_popups.py
 tests/test_push.py
 tests/test_relay.py
 tests/test_requestlog.py
 tests/test_resolve.py
+tests/test_screen.py
 tests/test_setup.py
 tests/test_snapshot.py
 tests/test_stamp_changelog.py

{chartremotely-0.2.9 → chartremotely-0.2.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "chartremotely"
-version = "0.2.9"
+version = "0.2.11"
 description = "Remote control of desktop charting applications on macOS"
 readme = "README.md"
 requires-python = ">=3.12"

chartremotely-0.2.11/tests/test_popups.py

@@ -0,0 +1,132 @@
+"""The pure half of closing thinkorswim's popups: what is open, and what to do next."""
+
+from chartremotely import popups
+from chartremotely.popups import CLOSE_LIST, CLOSE_SCALE, LEAVE_FIELD, Seen
+
+# The symbol combo and the list thinkorswim hung under it, as measured live.
+COMBO = (373, 119, 126, 25)
+LIST = (375, 142, 511, 190)
+
+
+def test_a_table_on_the_fields_bottom_left_corner_is_its_list():
+    assert popups.hangs_under(COMBO, LIST)
+
+
+def test_other_tables_are_not_the_list():
+    assert not popups.hangs_under(COMBO, None)
+    assert not popups.hangs_under(COMBO, (3, 662, 340, 1900))    # the watchlist
+    assert not popups.hangs_under(COMBO, (375, 300, 511, 190))   # lower in the pane
+    assert not popups.hangs_under(COMBO, (375, 142, 0, 0))       # collapsed, not drawn
+
+
+def test_the_charts_title_names_its_symbol():
+    assert popups.chart_symbol("PLTR 10 D 30m") == "PLTR"
+    assert popups.chart_symbol("/ESZ26 5 D 5m") == "/ESZ26"
+    assert popups.chart_symbol("BRK/B 1 Y 1D") == "BRK/B"
+    assert popups.chart_symbol("Lo: 166.03") is None
+    assert popups.chart_symbol("") is None
+    assert popups.chart_symbol(None) is None
+
+
+def test_the_chart_shows_an_entry_only_when_its_title_names_it():
+    assert popups.shows("PLTR 10 D 30m", "pltr ")
+    assert not popups.shows("PLTR 10 D 30m", "PLT")
+    assert popups.shows("/ESZ26 5 D 5m", "/ES")      # a futures root, drawn as its contract
+    assert not popups.shows("ESTC 5 D 5m", "ES")     # but not a mere prefix
+    assert not popups.shows(None, "PLTR")
+    assert not popups.shows("PLTR 10 D 30m", None)
+
+
+def test_nothing_open_and_nothing_focused_needs_nothing():
+    assert popups.next_step(Seen(title="PLTR 10 D 30m", field_value="PLTR")) is None
+    assert Seen().clean
+
+
+def test_the_menu_is_closed_before_the_list():
+    both = Seen(scale_open=True, list_open=True, field_value="PLTR")
+    assert not both.clean
+    assert popups.next_step(both) == CLOSE_SCALE
+    assert popups.next_step(Seen(list_open=True, field_value="PLTR")) == CLOSE_LIST
+
+
+def test_focus_leaves_the_field_only_when_the_chart_shows_its_text():
+    committed = Seen(field_focused=True, field_value="PLTR", title="PLTR 10 D 30m")
+    assert popups.next_step(committed) == LEAVE_FIELD
+    # Losing focus commits the field: a pending "PLT" must keep focus.
+    pending = Seen(field_focused=True, field_value="PLT", title="PLTR 10 D 30m")
+    assert popups.next_step(pending) is None
+    # A title that has not caught up yet is not proof either.
+    behind = Seen(field_focused=True, field_value="NVDA", title="PLTR 10 D 30m")
+    assert popups.next_step(behind) is None
+
+
+class Chart:
+    """A fake thinkorswim: popups that close when acted on, and a clock."""
+
+    def __init__(self, seen: Seen, title_after: float = 0.0, *, stuck: bool = False):
+        self.seen, self.title_after, self.stuck = seen, title_after, stuck
+        self.now, self.acts = 0.0, []
+
+    def clock(self):
+        return self.now
+
+    def sleep(self, seconds):
+        self.now += seconds
+
+    def look(self):
+        title = self.seen.title if self.now >= self.title_after else "OLD 1 D 1m"
+        return Seen(self.seen.scale_open, self.seen.list_open, self.seen.field_focused,
+                    self.seen.field_value, None if self.seen.list_open else title)
+
+    def act(self, step):
+        self.acts.append(step)
+        if self.stuck:
+            return
+        s = self.seen
+        if step == CLOSE_SCALE:
+            self.seen = Seen(False, s.list_open, s.field_focused, s.field_value, s.title)
+        elif step == CLOSE_LIST:
+            self.seen = Seen(s.scale_open, False, True, s.field_value, s.title)
+        elif step == LEAVE_FIELD:
+            self.seen = Seen(s.scale_open, s.list_open, False, s.field_value, s.title)
+
+    def run(self, **kw):
+        return popups.run(self.look, self.act, clock=self.clock, sleep=self.sleep, **kw)
+
+
+def test_run_closes_menu_then_list_then_lets_go_of_the_field():
+    chart = Chart(Seen(True, True, False, "PLTR", "PLTR 10 D 30m"))
+    done = chart.run()
+    assert chart.acts == [CLOSE_SCALE, CLOSE_LIST, LEAVE_FIELD]
+    assert done.clean and done.did == (CLOSE_SCALE, CLOSE_LIST, LEAVE_FIELD)
+
+
+def test_run_is_cheap_and_silent_when_nothing_is_open():
+    chart = Chart(Seen(field_value="PLTR", title="PLTR 10 D 30m"))
+    done = chart.run()
+    assert chart.acts == [] and chart.now == 0
+    assert done.clean and not done and str(done) == "nothing open"
+
+
+def test_run_leaves_a_pending_entry_in_the_field():
+    chart = Chart(Seen(list_open=True, field_value="PLT", title="PLTR 10 D 30m"))
+    done = chart.run()
+    assert chart.acts == [CLOSE_LIST]
+    assert done.clean and chart.seen.field_focused
+
+
+def test_run_waits_for_the_title_to_name_the_new_symbol_before_letting_go():
+    chart = Chart(Seen(list_open=True, field_value="NVDA", title="NVDA 10 D 30m"),
+                  title_after=0.8)
+    done = chart.run(until=lambda seen: popups.shows(seen.title, "NVDA"), timeout=3.0)
+    assert chart.acts == [CLOSE_LIST, LEAVE_FIELD]
+    assert 0.8 <= chart.now < 3.0 and done.clean
+
+
+def test_run_gives_up_at_the_deadline_and_says_so():
+    chart = Chart(Seen(scale_open=True, field_value="PLTR"), stuck=True)
+    done = chart.run(timeout=1.5)
+    assert not done.clean and chart.now >= 1.5
+    # A toggle is pressed again only after it has had time to show.
+    assert 2 <= len(chart.acts) <= 1.5 / popups.ACT_WAIT + 1
+    assert str(done).endswith("a popup is still open")

chartremotely-0.2.11/tests/test_screen.py

@@ -0,0 +1,77 @@
+"""The pure half of bringing the chart in front: which window, whether it is back, what covers it."""
+
+from chartremotely import screen
+
+TOS, SAFARI, MAIL, OVERLAY = 10, 20, 30, 40
+
+
+def win(pid, x, y, w, h, layer=0):
+    return {"kCGWindowOwnerPID": pid, "kCGWindowLayer": layer,
+            "kCGWindowBounds": {"X": x, "Y": y, "Width": w, "Height": h}}
+
+
+CHART = win(TOS, 0, 25, 1600, 1000)
+
+
+def test_overlap_needs_shared_area_not_a_shared_edge():
+    a = {"X": 0, "Y": 0, "Width": 100, "Height": 100}
+    assert screen.overlaps(a, {"X": 50, "Y": 50, "Width": 100, "Height": 100})
+    assert not screen.overlaps(a, {"X": 100, "Y": 0, "Width": 50, "Height": 50})
+    assert not screen.overlaps(a, {"X": 0, "Y": 100, "Width": 50, "Height": 50})
+
+
+def test_largest_takes_only_the_apps_own_windows():
+    windows = [win(SAFARI, 0, 0, 3000, 3000), win(TOS, 0, 0, 200, 200), CHART]
+    assert screen.largest(windows, TOS) is CHART
+    assert screen.largest(windows, MAIL) is None
+
+
+def test_the_chart_is_showing_only_when_its_own_frame_is_on_screen():
+    detached = win(TOS, 1700, 0, 400, 300)
+    assert screen.showing([detached], TOS, (0, 25, 1600, 1000)) is None
+    assert screen.showing([detached, CHART], TOS, (0, 25, 1600, 1000)) is CHART
+    # A point of rounding between the two APIs is not a different window.
+    assert screen.showing([CHART], TOS, (1, 24, 1600, 1001)) is CHART
+    assert screen.showing([CHART], SAFARI, (0, 25, 1600, 1000)) is None
+
+
+def test_covering_names_each_overlapping_ordinary_app_once():
+    windows = [win(SAFARI, 100, 100, 500, 500), win(SAFARI, 200, 200, 50, 50),
+               win(MAIL, 2000, 0, 300, 300), CHART]
+    assert screen.covering(windows, CHART["kCGWindowBounds"], TOS,
+                           {SAFARI, MAIL}) == [SAFARI]
+
+
+def test_covering_never_touches_overlays_the_desktop_or_the_chart_itself():
+    windows = [win(OVERLAY, 0, 0, 3000, 2000, layer=25),     # not a regular app
+               win(SAFARI, 0, 0, 3000, 2000, layer=-2147483603),  # desktop layer
+               CHART]
+    assert screen.covering(windows, CHART["kCGWindowBounds"], TOS,
+                           {SAFARI, TOS}) == []
+
+
+def test_wait_for_returns_the_first_truthy_probe():
+    answers = iter([None, None, "here"])
+    t = [0.0]
+    got = screen.wait_for(lambda: next(answers), timeout=2.0, interval=0.1,
+                          clock=lambda: t[0], sleep=lambda s: t.__setitem__(0, t[0] + s))
+    assert got == "here"
+    assert abs(t[0] - 0.2) < 1e-9
+
+
+def test_wait_for_gives_up_after_the_timeout_having_probed_at_least_once():
+    probes = []
+    t = [0.0]
+    got = screen.wait_for(lambda: probes.append(1), timeout=0.5, interval=0.1,
+                          clock=lambda: t[0], sleep=lambda s: t.__setitem__(0, t[0] + s))
+    assert got is None
+    assert 5 <= len(probes) <= 7
+
+
+def test_presented_says_what_it_took():
+    assert not screen.Presented()
+    assert str(screen.Presented()) == "already in front"
+    done = screen.Presented(unhid=True, raised=True, hid=("Mail", "Safari"))
+    assert done
+    assert str(done) == "unhid; raised; hid Mail, Safari"
+    assert str(screen.Presented(unminimized=True, raised=True)) == "unminimized; raised"

chartremotely-0.2.9/chartremotely/window.py

@@ -1,134 +0,0 @@
-"""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)