arcsecond 3.20.0__tar.gz → 3.20.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arcsecond
-Version: 3.20.0
+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.0 → 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 optional local host hints).
-
-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 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.")
@@ -72,12 +75,15 @@ _COMMON_OPTIONS = [
         ),
     ),
     click.option(
-        "--collect-host-info",
-        is_flag=True,
-        default=False,
+        "--collect-host-info/--no-host-info",
+        "collect_host_info",
+        default=None,
         help=(
-            "Additionally collect best-effort local OS hints (open ports, "
-            "COM ProgIDs matching TCS/Galil). Read-only."
+            "Best-effort local OS hints (open ports, COM ProgIDs matching "
+            "TCS/Galil), read-only. Collected automatically when HOST is this "
+            "machine, the only case in which they describe the Alpaca server's "
+            "host. --collect-host-info forces them for a remote HOST; "
+            "--no-host-info skips them."
         ),
     ),
     click.option(
@@ -104,37 +110,38 @@ def _default_output_path(kind: str) -> str:
     return str(Path.cwd() / f"alpaca_{kind}_probe_{stamp}.json")
 
 
+def _describe_host_hints(report: dict) -> str:
+    hints = report.get("host_hints")
+    if hints is None:
+        return f"skipped ({report.get('host_hints_skipped_reason', 'not collected')})"
+    if hints.get("collected_because") == HOST_HINTS_REASON_LOCAL:
+        return "collected (HOST is this machine)"
+    return "collected (--collect-host-info)"
+
+
 def _format_progress(label: str, ok: bool, detail: str | None) -> str:
     tag = click.style("[OK ]", fg="green") if ok else click.style("[ERR]", fg="red")
     suffix = f" — {detail}" if detail else ""
     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."
-    ),
-)
-@_add_options(_COMMON_OPTIONS)
-def probe_dome_cmd(
+def _run_probe(
+    kind: str,
+    runner: Callable[..., ProbeResult],
+    *,
     host: str,
     port: int,
     device_number: int,
     protocol: str,
     allow_active: bool,
-    collect_host_info: bool,
+    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:
@@ -150,7 +157,7 @@ def probe_dome_cmd(
     )
 
     try:
-        result = probe_dome(
+        result = runner(
             host=host,
             port=port,
             device_number=device_number,
@@ -177,4 +184,40 @@ def probe_dome_cmd(
     click.echo(click.style("Summary", bold=True))
     click.echo(f"  Probes:           {counts.ok}/{counts.total} OK")
     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)