arcsecond 3.20.1__tar.gz → 3.20.2__tar.gz

{arcsecond-3.20.1 → arcsecond-3.20.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcsecond
-Version: 3.20.1
+Version: 3.20.2
 Summary: CLI for arcsecond.io
 Project-URL: Homepage, https://github.com/arcsecond-io/cli
 Project-URL: Issues, https://github.com/arcsecond-io/cli/issues

{arcsecond-3.20.1 → arcsecond-3.20.2}/arcsecond/alpaca/commands.py

@@ -1,14 +1,14 @@
 """
 Click command group: ``arcsecond alpaca``.
 
-First citizen: ``arcsecond alpaca probe dome`` — a read-only diagnostic that
-captures what surface a given Alpaca dome server exposes (device metadata,
-``SupportedActions``, ``CommandString`` / ``CommandBool`` / ``CommandBlind``
-passthrough behaviour, and local host hints when the target is this machine).
-
-Structure leaves room for ``arcsecond alpaca probe telescope`` /
-``probe camera`` / ``probe focuser`` and ``arcsecond alpaca discover`` later
-under the same group.
+``arcsecond alpaca probe dome`` and ``arcsecond alpaca probe telescope`` are
+read-only diagnostics that capture what surface a given Alpaca device server
+exposes (device metadata, ``SupportedActions``, ``CommandString`` /
+``CommandBool`` / ``CommandBlind`` passthrough behaviour, and local host hints
+when the target is this machine), one JSON report per run.
+
+Structure leaves room for ``probe camera`` / ``probe focuser`` and
+``arcsecond alpaca discover`` later under the same group.
 """
 
 from __future__ import annotations
@@ -17,11 +17,14 @@ import json
 import os
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Callable
 
 import click
 
 from ..errors import ArcsecondError
-from .dome_probe import HOST_HINTS_REASON_LOCAL, ProbeProgress, probe_dome
+from .dome_probe import probe_dome
+from .probe import HOST_HINTS_REASON_LOCAL, ProbeProgress, ProbeResult
+from .telescope_probe import probe_telescope
 
 
 @click.group(name="alpaca", help="Diagnostics for local ASCOM Alpaca devices.")
@@ -122,20 +125,10 @@ def _format_progress(label: str, ok: bool, detail: str | None) -> str:
     return f"  {tag} {label}{suffix}"
 
 
-@probe_group.command(
-    name="dome",
-    help=(
-        "Probe a local Alpaca dome device read-only and write a JSON report.\n\n"
-        "Captures device metadata, SupportedActions, and the behaviour of the "
-        "legacy CommandString / CommandBool / CommandBlind passthroughs. "
-        "Useful for figuring out whether a proprietary driver (e.g. TCSGalil) "
-        "exposes any vendor-specific extension surface beyond the standard "
-        "ASCOM IDome interface. Local host hints (open ports, COM ProgIDs) "
-        "are added when HOST is this machine."
-    ),
-)
-@_add_options(_COMMON_OPTIONS)
-def probe_dome_cmd(
+def _run_probe(
+    kind: str,
+    runner: Callable[..., ProbeResult],
+    *,
     host: str,
     port: int,
     device_number: int,
@@ -144,10 +137,11 @@ def probe_dome_cmd(
     collect_host_info: bool | None,
     output_path: str | None,
 ) -> None:
-    output_path = output_path or _default_output_path("dome")
+    """Drive one probe from the terminal: banner, progress lines, report, summary."""
+    output_path = output_path or _default_output_path(kind)
 
     click.echo(
-        click.style("Alpaca dome probe", bold=True)
+        click.style(f"Alpaca {kind} probe", bold=True)
         + f" → {protocol}://{host}:{port} (device {device_number})"
     )
     if allow_active:
@@ -163,7 +157,7 @@ def probe_dome_cmd(
     )
 
     try:
-        result = probe_dome(
+        result = runner(
             host=host,
             port=port,
             device_number=device_number,
@@ -192,3 +186,38 @@ def probe_dome_cmd(
     click.echo(f"  SupportedActions: {supported_n} entries")
     click.echo(f"  Host hints:       {_describe_host_hints(result.report)}")
     click.echo(f"  Report written to {click.style(os.fspath(output_path), fg='cyan')}")
+
+
+@probe_group.command(
+    name="dome",
+    help=(
+        "Probe a local Alpaca dome device read-only and write a JSON report.\n\n"
+        "Captures device metadata, SupportedActions, and the behaviour of the "
+        "legacy CommandString / CommandBool / CommandBlind passthroughs. "
+        "Useful for figuring out whether a proprietary driver (e.g. TCSGalil) "
+        "exposes any vendor-specific extension surface beyond the standard "
+        "ASCOM IDome interface. Local host hints (open ports, COM ProgIDs) "
+        "are added when HOST is this machine."
+    ),
+)
+@_add_options(_COMMON_OPTIONS)
+def probe_dome_cmd(**options) -> None:
+    _run_probe("dome", probe_dome, **options)
+
+
+@probe_group.command(
+    name="telescope",
+    help=(
+        "Probe a local Alpaca telescope (mount) device read-only and write a "
+        "JSON report.\n\n"
+        "Captures device metadata, optics, site, pointing and tracking state, "
+        "capabilities, CanMoveAxis and AxisRates per movable axis, "
+        "SupportedActions, and the behaviour of the legacy CommandString / "
+        "CommandBool / CommandBlind passthroughs. Never moves the mount. "
+        "Local host hints (open ports, COM ProgIDs) are added when HOST is "
+        "this machine."
+    ),
+)
+@_add_options(_COMMON_OPTIONS)
+def probe_telescope_cmd(**options) -> None:
+    _run_probe("telescope", probe_telescope, **options)

arcsecond-3.20.2/arcsecond/alpaca/dome_probe.py

@@ -0,0 +1,89 @@
+"""
+Read-only diagnostic for an ASCOM Alpaca *dome* device.
+
+The standard ASCOM Alpaca ``IDome`` interface only exposes a single
+``OpenShutter`` / ``CloseShutter`` pair. Multi-shutter domes (e.g. DFM domes
+driven by TCSGalil) coordinate their shutters internally; if the driver does
+not advertise per-shutter custom actions via ``SupportedActions``, there is
+no canonical client-side way to drive the upper and lower shutters
+independently. This probe writes down exactly what surface a dome server
+exposes, so that decision can be made on evidence.
+
+The engine, the report layout and the safety rules live in :mod:`.probe`;
+this module only says which dome properties to read.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Iterable
+
+from .probe import ProbeProgress, ProbeResult, probe_device
+from .probe import iter_probe_labels as _iter_probe_labels
+
+# Read-only device descriptors and dome state, in the order we want them
+# presented in the report. Names are PascalCase to match the alpyca surface.
+_READ_ONLY_PROPERTIES: tuple[str, ...] = (
+    "Name",
+    "Description",
+    "DriverInfo",
+    "DriverVersion",
+    "InterfaceVersion",
+    "ShutterStatus",
+    "Altitude",
+    "Azimuth",
+    "AtHome",
+    "AtPark",
+    "Slewing",
+    "Slaved",
+    "CanFindHome",
+    "CanPark",
+    "CanSetAltitude",
+    "CanSetPark",
+    "CanSetShutter",
+    "CanSlave",
+    "CanSyncAzimuth",
+)
+
+
+def probe_dome(
+    host: str,
+    port: int,
+    device_number: int = 0,
+    *,
+    protocol: str = "http",
+    allow_active: bool = False,
+    collect_host_info: bool | None = None,
+    dome_factory: Callable[[str, int, str], Any] | None = None,
+    progress: ProbeProgress | None = None,
+) -> ProbeResult:
+    """
+    Build a JSON-serialisable diagnostic report for an Alpaca dome at
+    ``protocol://host:port`` (device_number). See :func:`.probe.probe_device`
+    for the ``collect_host_info`` semantics.
+
+    ``dome_factory(address, device_number, protocol)`` is only there for
+    tests — production callers leave it ``None`` and the real
+    ``alpaca.dome.Dome`` is used.
+    """
+    if dome_factory is None:
+        from alpaca.dome import Dome  # local import: keep cost off cold paths
+
+        dome_factory = Dome
+
+    return probe_device(
+        "dome",
+        host,
+        port,
+        device_number,
+        properties=_READ_ONLY_PROPERTIES,
+        device_factory=dome_factory,
+        protocol=protocol,
+        allow_active=allow_active,
+        collect_host_info=collect_host_info,
+        progress=progress,
+    )
+
+
+def iter_probe_labels() -> Iterable[str]:
+    """Convenience for tests / docs: enumerate the labels emitted by a run."""
+    return _iter_probe_labels(_READ_ONLY_PROPERTIES)

arcsecond-3.20.1/arcsecond/alpaca/dome_probe.py → arcsecond-3.20.2/arcsecond/alpaca/probe.py

@@ -1,27 +1,20 @@
 """
-Read-only diagnostic for an ASCOM Alpaca *dome* device.
-
-The standard ASCOM Alpaca ``IDome`` interface only exposes a single
-``OpenShutter`` / ``CloseShutter`` pair. Multi-shutter domes (e.g. DFM domes
-driven by TCSGalil) coordinate their shutters internally; if the driver does
-not advertise per-shutter custom actions via ``SupportedActions``, there is
-no canonical client-side way to drive the upper and lower shutters
-independently.
-
-This module produces a structured JSON report describing exactly what surface
-a given Alpaca dome server exposes:
-
-* environment / connectivity
-* standard read-only device metadata and dome state
-* the raw ``SupportedActions`` list
-* legacy ``CommandString`` / ``CommandBool`` / ``CommandBlind`` passthrough
-  behaviour against a small set of safe candidate commands
-* best-effort local host hints (open ports, COM ProgIDs), collected
-  automatically when the target is this machine, the only case in which
-  they describe the Alpaca server's host at all
-
-It never issues motion-class commands. ``CommandBlind`` and active Galil DMC
-verbs are gated behind ``allow_active=True``.
+The read-only probe engine shared by every ``arcsecond alpaca probe <device>``
+command.
+
+A probe never issues motion-class commands. It reads a device's standard
+properties, its ``SupportedActions`` list, and how the legacy
+``CommandString`` / ``CommandBool`` / ``CommandBlind`` passthroughs behave
+against a small set of safe candidate commands, and writes it all out as one
+JSON report in which every outcome, including every error, is data.
+
+``CommandBlind`` and active Galil DMC verbs are gated behind
+``allow_active=True``. Local host hints (open ports, COM ProgIDs) are attached
+automatically when the target is this machine, the only case in which they
+describe the Alpaca server's host at all.
+
+Device modules (``dome_probe``, ``telescope_probe``) own only what differs per
+device: the property list, the alpyca class, and any extra read-only section.
 """
 
 from __future__ import annotations
@@ -35,35 +28,14 @@ import sys
 import traceback
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import Any, Callable, Iterable
-
-# Read-only device descriptors and dome state, in the order we want them
-# presented in the report. Names are PascalCase to match the alpyca surface.
-_READ_ONLY_PROPERTIES: tuple[str, ...] = (
-    "Name",
-    "Description",
-    "DriverInfo",
-    "DriverVersion",
-    "InterfaceVersion",
-    "ShutterStatus",
-    "Altitude",
-    "Azimuth",
-    "AtHome",
-    "AtPark",
-    "Slewing",
-    "Slaved",
-    "CanFindHome",
-    "CanPark",
-    "CanSetAltitude",
-    "CanSetPark",
-    "CanSetShutter",
-    "CanSlave",
-    "CanSyncAzimuth",
-)
+from enum import Enum
+from typing import Any, Callable, Iterable, Mapping
 
 # Safe Galil DMC read-style verbs: print/report values without commanding
 # motion. ``MG`` is "message" (print expression), ``TE`` is "tell error",
-# ``TP`` is "tell position".
+# ``TP`` is "tell position". They probe whether a driver forwards
+# CommandString at all; a driver without the member (the DFM TCSGalil ones)
+# fails every one of them, and that is the finding.
 _READ_ONLY_COMMANDS: tuple[str, ...] = (
     "MG TIME",
     "MG _BGA",
@@ -125,8 +97,6 @@ def _coerce_jsonable(value: Any) -> Any:
     """Make values from alpyca safe to dump as JSON."""
     # IntEnum is a subclass of int, so check it *before* the primitive branch.
     # We want {"name": "shutterClosed", "value": 1} not just 1.
-    from enum import Enum
-
     if isinstance(value, Enum):
         return {"name": value.name, "value": value.value}
     if isinstance(value, (str, int, float, bool)) or value is None:
@@ -135,10 +105,18 @@ def _coerce_jsonable(value: Any) -> Any:
         return [_coerce_jsonable(item) for item in value]
     if isinstance(value, dict):
         return {str(k): _coerce_jsonable(v) for k, v in value.items()}
+    if isinstance(value, datetime):
+        return value.isoformat()
+    # alpyca's ``Rate`` (from AxisRates) carries a range and nothing else.
+    if hasattr(value, "Minimum") and hasattr(value, "Maximum"):
+        return {
+            "minimum": _coerce_jsonable(value.Minimum),
+            "maximum": _coerce_jsonable(value.Maximum),
+        }
     return str(value)
 
 
-def _capture(call: Callable[[], Any]) -> dict:
+def capture(call: Callable[[], Any]) -> dict:
     """Run ``call()`` and capture either its value or its exception."""
     try:
         raw = call()
@@ -150,7 +128,21 @@ def _capture(call: Callable[[], Any]) -> dict:
     return {"ok": True, "value": _truncate(_coerce_jsonable(raw))}
 
 
+def record(
+    outcome: dict, label: str, progress: ProbeProgress, counts: ProbeCounts
+) -> dict:
+    """Count one captured outcome and report it to the caller; returns it."""
+    counts.total += 1
+    if outcome["ok"]:
+        counts.ok += 1
+        progress.emit(label, True, str(outcome["value"]))
+    else:
+        progress.emit(label, False, outcome["error"])
+    return outcome
+
+
 def _build_environment(
+    kind: str,
     host: str,
     port: int,
     device_number: int,
@@ -168,6 +160,7 @@ def _build_environment(
 
     return {
         "timestamp_utc": datetime.now(timezone.utc).isoformat(),
+        "device_type": kind,
         "host": host,
         "port": port,
         "device_number": device_number,
@@ -181,29 +174,25 @@ def _build_environment(
 
 
 def _probe_device_metadata(
-    dome: Any,
+    device: Any,
+    properties: Iterable[str],
     progress: ProbeProgress,
     counts: ProbeCounts,
 ) -> dict:
     section: dict = {}
-    for name in _READ_ONLY_PROPERTIES:
-        outcome = _capture(lambda n=name: getattr(dome, n))
-        section[name] = outcome
-        counts.total += 1
-        if outcome["ok"]:
-            counts.ok += 1
-            progress.emit(name, True, str(outcome["value"]))
-        else:
-            progress.emit(name, False, outcome["error"])
+    for name in properties:
+        section[name] = record(
+            capture(lambda n=name: getattr(device, n)), name, progress, counts
+        )
     return section
 
 
 def _probe_supported_actions(
-    dome: Any,
+    device: Any,
     progress: ProbeProgress,
     counts: ProbeCounts,
 ) -> dict:
-    outcome = _capture(lambda: dome.SupportedActions)
+    outcome = capture(lambda: device.SupportedActions)
     counts.total += 1
     if outcome["ok"]:
         counts.ok += 1
@@ -230,7 +219,7 @@ def _send_command(
 
 
 def _probe_command_passthrough(
-    dome: Any,
+    device: Any,
     *,
     allow_active: bool,
     progress: ProbeProgress,
@@ -247,7 +236,7 @@ def _probe_command_passthrough(
         commands = commands + _ACTIVE_COMMANDS
 
     for cmd in commands:
-        entry = _send_command(dome.CommandString, cmd, False)
+        entry = _send_command(device.CommandString, cmd, False)
         section["command_string"].append(entry)
         counts.total += 1
         counts.ok += 1 if entry["ok"] else 0
@@ -257,7 +246,7 @@ def _probe_command_passthrough(
             entry.get("error") or str(entry.get("response", ""))[:80],
         )
 
-        entry = _send_command(dome.CommandBool, cmd, False)
+        entry = _send_command(device.CommandBool, cmd, False)
         section["command_bool"].append(entry)
         counts.total += 1
         counts.ok += 1 if entry["ok"] else 0
@@ -270,7 +259,7 @@ def _probe_command_passthrough(
     if allow_active:
         # CommandBlind is fire-and-forget — only attempt under --allow-active.
         for cmd in commands:
-            entry = _send_command(dome.CommandBlind, cmd, False)
+            entry = _send_command(device.CommandBlind, cmd, False)
             section["command_blind"].append(entry)
             counts.total += 1
             counts.ok += 1 if entry["ok"] else 0
@@ -421,104 +410,109 @@ def _collect_host_hints() -> dict:
     return _collect_posix_host_hints()
 
 
-def probe_dome(
+def _attach_host_hints(
+    report: dict, host: str, target_is_local: bool, collect_host_info: bool | None
+) -> None:
+    if collect_host_info is None:
+        collect_host_info = target_is_local
+        reason = HOST_HINTS_REASON_LOCAL
+    else:
+        reason = HOST_HINTS_REASON_REQUESTED
+
+    if collect_host_info:
+        report["host_hints"] = {"collected_because": reason, **_collect_host_hints()}
+    elif reason == HOST_HINTS_REASON_REQUESTED:
+        report["host_hints_skipped_reason"] = "Disabled by the caller."
+    else:
+        report["host_hints_skipped_reason"] = (
+            f"{host} is not this machine, so the hints would describe the wrong "
+            "host; pass --collect-host-info to force them."
+        )
+
+
+ExtraProbe = Callable[[Any, ProbeProgress, ProbeCounts], Any]
+
+
+def probe_device(
+    kind: str,
     host: str,
     port: int,
     device_number: int = 0,
     *,
+    properties: tuple[str, ...],
+    device_factory: Callable[[str, int, str], Any],
     protocol: str = "http",
     allow_active: bool = False,
     collect_host_info: bool | None = None,
-    dome_factory: Callable[[str, int, str], Any] | None = None,
+    extra_probes: Mapping[str, ExtraProbe] | None = None,
     progress: ProbeProgress | None = None,
 ) -> ProbeResult:
     """
-    Build a JSON-serialisable diagnostic report for an Alpaca dome at
-    ``protocol://host:port`` (device_number).
+    Build a JSON-serialisable diagnostic report for the Alpaca ``kind`` device
+    at ``protocol://host:port`` (device_number).
+
+    ``properties`` are read in order into ``device_metadata``. Each
+    ``extra_probes`` entry adds a section under its key, right after the
+    metadata; it receives the device, the progress sink and the counts.
 
     ``collect_host_info`` left at ``None`` attaches the local host hints when
     ``host`` is this machine and skips them otherwise, recording which in the
     report. ``True`` forces them for a remote target (they still describe the
     probing machine, not the target); ``False`` skips them for a local one.
 
-    ``dome_factory(address, device_number, protocol)`` is only there for
-    tests — production callers leave it ``None`` and the real
-    ``alpaca.dome.Dome`` is used.
+    ``device_factory(address, device_number, protocol)`` is the alpyca class
+    in production and a stand-in in tests.
     """
     progress = progress or ProbeProgress()
     counts = ProbeCounts()
     address = f"{host}:{port}"
 
-    if dome_factory is None:
-        from alpaca.dome import Dome  # local import: keep cost off cold paths
-
-        dome_factory = Dome
-
-    # Build dome client. A failure here is fatal (host unreachable, or the
+    # Build the client. A failure here is fatal (host unreachable, or the
     # alpyca constructor itself blew up) so we surface it to the caller.
     try:
-        dome = dome_factory(address, device_number, protocol)
+        device = device_factory(address, device_number, protocol)
     except Exception as exc:  # noqa: BLE001
         raise RuntimeError(
-            f"Could not construct Alpaca Dome client for "
+            f"Could not construct Alpaca {kind.capitalize()} client for "
             f"{protocol}://{address} (device {device_number}): "
             f"{type(exc).__name__}: {exc}\n" + traceback.format_exc()
         ) from exc
 
-    connected_outcome = _capture(lambda: dome.Connected)
-    counts.total += 1
-    counts.ok += 1 if connected_outcome["ok"] else 0
-    progress.emit(
-        "Connected",
-        connected_outcome["ok"],
-        connected_outcome.get("error") or str(connected_outcome.get("value")),
+    connected_outcome = record(
+        capture(lambda: device.Connected), "Connected", progress, counts
     )
 
     target_is_local = is_local_target(host)
     environment = _build_environment(
-        host, port, device_number, protocol, connected_outcome
+        kind, host, port, device_number, protocol, connected_outcome
     )
     environment["target_is_local"] = target_is_local
 
-    device_metadata = _probe_device_metadata(dome, progress, counts)
-    supported_actions = _probe_supported_actions(dome, progress, counts)
-    command_passthrough = _probe_command_passthrough(
-        dome,
+    report: dict = {
+        "environment": environment,
+        "device_metadata": _probe_device_metadata(device, properties, progress, counts),
+    }
+    for key, run in (extra_probes or {}).items():
+        report[key] = run(device, progress, counts)
+    report["supported_actions"] = _probe_supported_actions(device, progress, counts)
+    report["command_passthrough"] = _probe_command_passthrough(
+        device,
         allow_active=allow_active,
         progress=progress,
         counts=counts,
     )
 
-    report: dict = {
-        "environment": environment,
-        "device_metadata": device_metadata,
-        "supported_actions": supported_actions,
-        "command_passthrough": command_passthrough,
-    }
-
-    if collect_host_info is None:
-        collect_host_info = target_is_local
-        reason = HOST_HINTS_REASON_LOCAL
-    else:
-        reason = HOST_HINTS_REASON_REQUESTED
-
-    if collect_host_info:
-        report["host_hints"] = {"collected_because": reason, **_collect_host_hints()}
-    elif reason == HOST_HINTS_REASON_REQUESTED:
-        report["host_hints_skipped_reason"] = "Disabled by the caller."
-    else:
-        report["host_hints_skipped_reason"] = (
-            f"{host} is not this machine, so the hints would describe the wrong "
-            "host; pass --collect-host-info to force them."
-        )
-
+    _attach_host_hints(report, host, target_is_local, collect_host_info)
     return ProbeResult(report=report, counts=counts)
 
 
-def iter_probe_labels() -> Iterable[str]:
+def iter_probe_labels(
+    properties: Iterable[str], extra_labels: Iterable[str] = ()
+) -> Iterable[str]:
     """Convenience for tests / docs: enumerate the labels emitted by a run."""
     yield "Connected"
-    yield from _READ_ONLY_PROPERTIES
+    yield from properties
+    yield from extra_labels
     yield "SupportedActions"
     for cmd in _READ_ONLY_COMMANDS:
         yield f"CommandString({cmd!r})"