starbash 0.3.3__tar.gz → 0.3.4__tar.gz

{starbash-0.3.3 → starbash-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starbash
-Version: 0.3.3
+Version: 0.3.4
 Summary: A tool for automating/standardizing/sharing astrophotography workflows.
 License-File: LICENSE
 Author: Kevin Hester
@@ -79,7 +79,12 @@ This project is still very young - but making good progress 😊!
 
 If you are interested in alpha-testing we ❤️ you.  This README should have enough instructions to get you going, but if you encounter **any** problems please file a github issue and we'll work together to fix them.
 
-![Sample session movie](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/vhs/sample-session.gif)
+(new!) We now have a full GUI (click the video to play)...
+
+<video src="https://github.com/user-attachments/assets/0791c47f-f8fa-4279-be06-f869d7212d8c" autoplay controls loop muted playsinline width="100%"></video>
+
+We have a CLI interface also...
+![CLI sample session](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/vhs/sample-session.gif)
 
 ## Current features
 
@@ -321,3 +326,4 @@ However, in some of my other open-source projects, I've seen the current hell PR
 
 Copyright 2025 Kevin Hester, kevinh@geeksville.com.
 Licensed under the [GPL v3](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/LICENSE)
+

{starbash-0.3.3 → starbash-0.3.4}/README.md

@@ -46,7 +46,12 @@ This project is still very young - but making good progress 😊!
 
 If you are interested in alpha-testing we ❤️ you.  This README should have enough instructions to get you going, but if you encounter **any** problems please file a github issue and we'll work together to fix them.
 
-![Sample session movie](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/vhs/sample-session.gif)
+(new!) We now have a full GUI (click the video to play)...
+
+<video src="https://github.com/user-attachments/assets/0791c47f-f8fa-4279-be06-f869d7212d8c" autoplay controls loop muted playsinline width="100%"></video>
+
+We have a CLI interface also...
+![CLI sample session](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/vhs/sample-session.gif)
 
 ## Current features
 
@@ -287,4 +292,4 @@ However, in some of my other open-source projects, I've seen the current hell PR
 ## License
 
 Copyright 2025 Kevin Hester, kevinh@geeksville.com.
-Licensed under the [GPL v3](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/LICENSE)
+Licensed under the [GPL v3](https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/LICENSE)

{starbash-0.3.3 → starbash-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "starbash"
-version = "0.3.3"
+version = "0.3.4"
 description = "A tool for automating/standardizing/sharing astrophotography workflows."
 authors = ["Kevin Hester <kevinh@geeksville.com>"]
 readme = "README.md"
@@ -61,6 +61,7 @@ doit-graph = ">=0.3.0"
 # harlequin = "^2.4.1"
 library-skills = "^0.0.19"
 semble = {version = "^0.6.0", extras = ["mcp"]}
+imageio-ffmpeg = "^0.6.0"
 
 [tool.poetry.scripts]
 starbash = "starbash.main:app"
@@ -71,6 +72,7 @@ markers = [
     "slow: marks tests as slow (deselect with '-m \"not slow\"')",
     "integration: marks tests as integration tests requiring /test-data (deselect with '-m \"not integration\"')",
     "gui: marks tests that build real Qt widgets (offscreen; deselect with '-m \"not gui\"')",
+    "gui_integration: marks the scripted gui_integration movie runs (needs ffmpeg + /test-data; deselect with '-m \"not gui_integration\"')",
 ]
 # -n auto enables parallel test execution plugin
 # By default we exclude only slow and integration tests. GUI tests DO run: PySide6
@@ -80,7 +82,12 @@ markers = [
 # --tb=short shows shorter tracebacks
 # -rfE shows summary of failed and error test outcomes at end (not passed)
 # --ignore excludes third-party test directories
-addopts = "-m 'not slow and not integration' -n auto --tb=short -rfE --ignore=GraXpert --ignore=starbash-recipes"
+addopts = "-m 'not slow and not integration and not gui_integration' -n auto --tb=short -rfE --ignore=GraXpert --ignore=starbash-recipes"
+
+# Note: the `gui_integration` movies are deselected by default on purpose: they drive a
+# whole user journey (setup wizard -> reindex -> processing run) and take minutes, so they
+# run on demand - `just test-integration-gui`, or `pytest -m gui_integration -n 0`.
+# The marker name uses an underscore so it is usable as `pytest.mark.gui_integration`.
 
 # Note: To limit captured output further, you can:
 # 1. Use --tb=line for minimal tracebacks

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/processed_target.py

@@ -85,6 +85,10 @@ class StageOption:
     parameters: list[ParameterOption]
     #: URL (``https://`` or ``file://``) of the recipe that declares this stage.
     recipe_url: str | None = None
+    #: Tool this stage runs (e.g. ``"siril"``), as declared by the recipe.
+    tool: str | None = None
+    #: Interchangeable role (e.g. ``"stack"``) the recipe declares, if any.
+    role: str | None = None
 
 
 @dataclass
@@ -189,7 +193,8 @@ def stage_declarations(recipes: Any) -> dict[str, dict[str, Any]]:
     Recipes are the authoritative source of a parameter's default and description
     (declared as ``[[stages.parameters]]``).  Scanning the recipe repos is cheap
     because their config is already loaded; later definitions win, mirroring repo
-    precedence.
+    precedence.  The stage's declared ``tool`` and optional ``role`` are carried
+    along too, for report rendering.
     """
     declarations: dict[str, dict[str, Any]] = {}
     for repo in recipes:
@@ -205,7 +210,14 @@ def stage_declarations(recipes: Any) -> dict[str, dict[str, Any]]:
             if not name:
                 continue
             entry = declarations.setdefault(
-                str(name), {"description": None, "parameters": {}, "recipe_url": None}
+                str(name),
+                {
+                    "description": None,
+                    "parameters": {},
+                    "recipe_url": None,
+                    "tool": None,
+                    "role": None,
+                },
             )
             if stage.get("description"):
                 entry["description"] = stage.get("description")
@@ -213,6 +225,11 @@ def stage_declarations(recipes: Any) -> dict[str, dict[str, Any]]:
             recipe_url = getattr(source, "url", None) if source is not None else None
             if recipe_url:
                 entry["recipe_url"] = str(recipe_url)
+            tool = stage.get("tool")
+            if isinstance(tool, dict) and tool.get("name"):
+                entry["tool"] = str(tool["name"])
+            if stage.get("role"):
+                entry["role"] = str(stage["role"])
             for param in stage.get("parameters") or []:
                 param_name = param.get("name")
                 if not param_name:
@@ -1027,6 +1044,8 @@ class ProcessedTarget:
                     excluded=bool(entry.get("excluded", False)),
                     parameters=parameters,
                     recipe_url=declared.get("recipe_url"),
+                    tool=declared.get("tool"),
+                    role=declared.get("role"),
                 )
             )
         return stages

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/publish/github.py

@@ -2,9 +2,11 @@
 
 from __future__ import annotations
 
+import html
 import re
 import shutil
 import warnings
+from collections.abc import Sequence
 from importlib import resources
 from pathlib import Path
 from typing import Any
@@ -16,7 +18,7 @@ from tomlkit.exceptions import ParseError
 
 from starbash import console
 from starbash.paths import get_publish_site_dir
-from starbash.processed_target import ProcessedTarget
+from starbash.processed_target import ProcessedTarget, StageOption, stage_declarations
 
 
 def slugify(value: str) -> str:
@@ -63,6 +65,123 @@ def equipment_rows(equipment: Any) -> list[dict[str, str | None]]:
     return rows
 
 
+#: Stylesheet for :func:`stage_tree_html`, scoped to its wrapper so it cannot
+#: fight the site theme.  Colours are tuned for the dark ``jekyll-theme-midnight``
+#: look: defaults are a muted grey-blue, overrides a bold amber accent.
+_STAGE_TREE_CSS = """\
+.sb-stages{margin:1.25em 0;font-size:.92rem;line-height:1.5}
+.sb-stages ul{list-style:none;margin:.25rem 0;padding:0}
+.sb-stages .sb-stage{margin:.35rem 0;padding-left:1.1rem;border-left:2px solid rgba(128,150,180,.45)}
+.sb-stages .sb-stage-name{font-weight:600}
+.sb-stages a.sb-stage-name{color:inherit;text-decoration:underline dotted;text-underline-offset:.15em}
+.sb-stages .sb-tool,.sb-stages .sb-role,.sb-stages .sb-skip{display:inline-block;margin-left:.45rem;padding:.05rem .45rem;border:1px solid rgba(128,150,180,.55);border-radius:.7rem;font-size:.7rem;letter-spacing:.05em;text-transform:uppercase;opacity:.85;vertical-align:.1em}
+.sb-stages .sb-skip{border-style:dashed}
+.sb-stages .sb-stage.excluded{opacity:.55}
+.sb-stages .sb-stage.excluded .sb-stage-name{text-decoration:line-through}
+.sb-stages .sb-recipe{margin-left:.45rem;font-size:.78rem;opacity:.9}
+.sb-stages .sb-stage-desc{margin-left:.45rem;opacity:.7;font-size:.85rem}
+.sb-stages .sb-params{padding-left:1.35rem;margin:.1rem 0}
+.sb-stages .sb-param{margin:.05rem 0}
+.sb-stages .sb-pname{opacity:.92}
+.sb-stages .sb-default{color:#9fb0c3;font-weight:400}
+.sb-stages .sb-override{color:#ffb454;font-weight:700}
+.sb-stages .sb-legend{font-size:.8rem;opacity:.85;margin:.2rem 0 .6rem}"""
+
+
+def _display_value(value: Any) -> str:
+    """Render a parameter value the way its TOML line would be written."""
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, str):
+        return f'"{value}"'
+    return str(value)
+
+
+def _esc(value: Any) -> str:
+    """HTML-escape any value bound for the stage tree."""
+    return html.escape(str(value), quote=True)
+
+
+def _param_row(param: Any) -> str:
+    """One parameter line: grey default, or a bold amber override beside it."""
+    bits = ['<li class="sb-param"']
+    if param.description:
+        bits.append(f' title="{_esc(param.description)}"')
+    bits.append(f'><span class="sb-pname">{_esc(param.name)}</span>')
+    if param.is_overridden:
+        bits.append(f' <span class="sb-override">= {_esc(_display_value(param.value))}</span>')
+        if param.default is not None:
+            bits.append(
+                f' <span class="sb-default">(default {_esc(_display_value(param.default))})</span>'
+            )
+    elif param.default is not None:
+        bits.append(f' <span class="sb-default">= {_esc(_display_value(param.default))}</span>')
+    else:
+        bits.append(' <span class="sb-default">(no default)</span>')
+    bits.append("</li>")
+    return "".join(bits)
+
+
+def _stage_row(stage: StageOption) -> list[str]:
+    """The ``<li>`` for one stage: header line plus its parameter lines."""
+    css = "sb-stage excluded" if stage.excluded else "sb-stage"
+    # The stage name links to the recipe its TOML came from, when that recipe
+    # has a browsable (http(s)) URL; local/`pkg://` sources stay plain text.
+    recipe_url = str(stage.recipe_url) if stage.recipe_url else ""
+    if recipe_url.startswith("http"):
+        name_html = f'<a class="sb-stage-name" href="{_esc(recipe_url)}">{_esc(stage.name)}</a>'
+    else:
+        name_html = f'<span class="sb-stage-name">{_esc(stage.name)}</span>'
+    head = [name_html]
+    if stage.tool:
+        head.append(f'<span class="sb-tool">{_esc(stage.tool)}</span>')
+    if stage.role:
+        head.append(f'<span class="sb-role">{_esc(stage.role)}</span>')
+    if stage.excluded:
+        head.append('<span class="sb-skip">skipped</span>')
+    if stage.description:
+        head.append(f'<span class="sb-stage-desc">{_esc(stage.description)}</span>')
+
+    lines = [f'<li class="{css}">', f'<div class="sb-stage-head">{" ".join(head)}</div>']
+    if stage.parameters:
+        lines.append('<ul class="sb-params">')
+        lines.extend(_param_row(param) for param in stage.parameters)
+        lines.append("</ul>")
+    lines.append("</li>")
+    return lines
+
+
+def stage_tree_html(stages: Sequence[StageOption]) -> str:
+    """Render a target's stages as an HTML tree for its report page.
+
+    Every stage the target records is shown, in order, with the parameters its
+    recipe declares: the recipe *defaults* render in muted grey, while values
+    this target *overrides* render in a bolder amber accent right beside the
+    default they replaced.  Excluded stages stay visible but dimmed and marked
+    "skipped", so the tree shows exactly which stages were used.
+
+    Returns ``""`` for a target with no recorded stages.
+    """
+    if not stages:
+        return ""
+
+    lines = [
+        '<div class="sb-stages">',
+        "<style>",
+        _STAGE_TREE_CSS,
+        "</style>",
+        '<div class="sb-legend">Parameters: <span class="sb-default">grey = recipe default</span>'
+        ' &middot; <span class="sb-override">amber = this target&rsquo;s override</span></div>',
+        '<ul class="sb-stage-list">',
+    ]
+    for stage in stages:
+        lines.extend(_stage_row(stage))
+    lines.extend(["</ul>", "</div>"])
+    return "\n".join(lines)
+
+
 class GitHubPublisher:
     """Generate a complete local Jekyll site from one processed repository."""
 
@@ -103,8 +222,26 @@ class GitHubPublisher:
         heroes = [path for path in images if path.name.lower().startswith("hero")]
         return heroes or images
 
-    def _targets(self, root: Path) -> list[tuple[Path, dict[str, Any]]]:
-        targets: list[tuple[Path, dict[str, Any]]] = []
+    def _stage_declarations(self) -> dict[str, dict[str, Any]]:
+        """Map stage name -> declared description/parameters from the recipe repos.
+
+        Best effort: contexts without ``get_recipes`` (bare front ends, tests)
+        get an empty map, and the report then simply omits recipe-declared
+        defaults while still showing the target's recorded stages.
+        """
+        get_recipes = getattr(self.sb, "get_recipes", None)
+        if not callable(get_recipes):
+            return {}
+        try:
+            return stage_declarations(get_recipes())
+        except Exception:  # noqa: BLE001 - a broken recipe repo must not kill the report
+            warnings.warn(
+                "Could not read recipe declarations; the report omits defaults", stacklevel=2
+            )
+            return {}
+
+    def _targets(self, root: Path) -> list[tuple[Path, dict[str, Any], ProcessedTarget]]:
+        targets: list[tuple[Path, dict[str, Any], ProcessedTarget]] = []
         for directory in sorted(
             (path for path in root.iterdir() if path.is_dir()),
             key=lambda path: path.name.lower(),
@@ -126,7 +263,7 @@ class GitHubPublisher:
                 document.update(plain(target.about))
                 document.update(plain(target.sessions))
                 document["_main_config"] = main_config
-                targets.append((directory, document))
+                targets.append((directory, document, target))
             except (OSError, ParseError) as exc:
                 warnings.warn(f"Skipping malformed target {metadata_dir}: {exc}", stacklevel=2)
         return targets
@@ -135,6 +272,7 @@ class GitHubPublisher:
         """Regenerate the complete site and return its root directory."""
         root = self._processed_root()
         targets = self._targets(root)
+        declarations = self._stage_declarations()
 
         # Wipe any previously generated site so stale files don't persist.
         if self.site_dir.exists():
@@ -178,7 +316,7 @@ class GitHubPublisher:
                 shutil.copyfileobj(source, destination)
             progress.update(task, description="Copied static assets", advance=1)
             index_targets: list[dict[str, Any]] = []
-            for directory, document in targets:
+            for directory, document, processed in targets:
                 about = document.get("about", {})
                 if not isinstance(about, dict):
                     about = {}
@@ -231,6 +369,7 @@ class GitHubPublisher:
                     )
                 page_images = [f"../../{url}" for url in image_urls]
                 seo_image = f"/{image_urls[0]}" if image_urls else None
+                stage_tree = stage_tree_html(processed.stage_options(declarations))
                 page_name = f"{slug}.md"
                 post = self.environment.get_template("target.md.jinja").render(
                     target={**target, "name": name},
@@ -240,6 +379,7 @@ class GitHubPublisher:
                     images=page_images,
                     image=seo_image,
                     sessions=sessions,
+                    stage_tree=stage_tree,
                     workflow_url=f"../../assets/targets/{slug}/main.toml",
                 )
                 (posts / page_name).write_text(post)

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/publish/github_service.py

@@ -407,7 +407,7 @@ class GitHubService:
             {
                 "name": name,
                 # note: markdown is not supported in the description field
-                "description": "Semiautomatic (beta) image workflows by Starbash",
+                "description": "(mostly) automatic (beta) image workflows by Starbash",
                 "private": False,
                 # we want to make main ourselves
                 "auto_init": False,

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/templates/report/target.md.jinja

@@ -9,10 +9,30 @@ description: {{ description | default('Processed Starbash target.', true) | tojs
 
 {{ about.summary | default('Processed astrophotography target.') }}
 
+{% if target.ra is defined and target.ra and target.ra != 'N/A' and target.dec is defined and target.dec and target.dec != 'N/A' %}
+
+**Coordinates:** RA {{ target.ra }} / Dec {{ target.dec }}
+
+{% endif %}
+
 {% for image in images %}
 ![{{ target.name }}]({{ image }})
 {% endfor %}
 
+## Workflow
+
+{% if stage_tree %}
+
+The stages used to process this target, with each stage's parameters:
+
+{{ stage_tree }}
+
+{% endif %}
+
+{% if workflow_url %}
+[View processing workflow]({{ workflow_url }})
+{% endif %}
+
 ## Sessions
 
 {% for session in sessions %}
@@ -35,8 +55,3 @@ description: {{ description | default('Processed Starbash target.', true) | tojs
 
 {% endfor %}
 
-## Workflow
-
-{% if workflow_url %}
-[View processing workflow]({{ workflow_url }})
-{% endif %}

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/ui/qt/main_window.py

@@ -61,6 +61,9 @@ class MainWindow(QMainWindow):
         super().__init__(parent)
         self.setWindowTitle("Starbash")
         self.resize(1280, 820)
+        # A stable handle for the gui-integration movie (doc/plans/gui-integration-video.md
+        # §6): a name, not a behaviour - nothing is styled by it.
+        self.setObjectName("MainWindow")
 
         self._bus = EventBusBridge(self)
         self._sb = sb

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/ui/qt/pages/processing.py

@@ -150,6 +150,7 @@ class ProcessingPage(Page):
         layout.addWidget(self._caption)
 
         self._tasks = _RunTree()
+        self._tasks.setObjectName("processingTree")
         self._tasks.setHeaderLabels(["Target / stage / task", "Status / details"])
         self._tasks.setAlternatingRowColors(True)
         layout.addWidget(self._tasks, 1)
@@ -160,6 +161,29 @@ class ProcessingPage(Page):
         if self.bus is not None:
             self.bus.received.connect(self._on_event)  # type: ignore[attr-defined]
 
+    # --- public handles ---------------------------------------------------
+    @property
+    def run_button(self) -> QPushButton:
+        """The *Run auto pipeline* button — the movie script's handle for it.
+
+        It cannot carry an ``objectName`` of its own (it is ``#Primary``, and a widget
+        has one ``objectName``), so it is reached through this accessor instead — see
+        ``doc/plans/gui-integration-video.md`` §6.
+        """
+        return self._run
+
+    @property
+    def cancel_button(self) -> QPushButton:
+        """The *Cancel* button beside the run button — same §6 workaround as the
+        run button (no ``objectName`` of its own)."""
+        return self._cancel
+
+    @property
+    def caption_label(self) -> QLabel:
+        """The one-line run caption (e.g. ``Idle.``) — same §6 workaround as above:
+        it is ``#PageSubtitle``, so its ``objectName`` is spoken for."""
+        return self._caption
+
     # --- actions ----------------------------------------------------------
     def start_run(self) -> None:
         """Clear the last run's view and start processing in the background.

{starbash-0.3.3 → starbash-0.3.4}/src/starbash/ui/qt/pages/wizard.py

@@ -274,12 +274,18 @@ class YouPage(SetupPage):
 
         repo = sb.user_repo
         self._name = QLineEdit(str(repo.get("user.name", "") or ""))
+        # objectName is the gui-integration script's handle (doc/plans/gui-integration-video.md
+        # §6). These four are named, never restyled - the theme styles by type here.
+        self._name.setObjectName("wizardName")
         self._email = QLineEdit(str(repo.get("user.email", "") or ""))
+        self._email.setObjectName("wizardEmail")
         self._analytics = QCheckBox("Send anonymous crash reports and usage data (please!)")
+        self._analytics.setObjectName("wizardAnalytics")
         self._analytics.setChecked(analytics_enabled(repo))
         self._include_email = QCheckBox(
             "Include my email with crash reports (so we can contact you)"
         )
+        self._include_email.setObjectName("wizardIncludeEmail")
         self._include_email.setChecked(analytics_include_user(repo))
 
         # The *include email* option only means something once an email is typed.
@@ -548,6 +554,17 @@ class ImagesPage(SetupPage):
 
         self.refresh()
 
+    @property
+    def choose_button(self) -> QPushButton:
+        """The *Choose folder…* button — the movie script's handle for it.
+
+        It cannot carry an ``objectName`` of its own: it is ``#Primary`` (the theme's
+        accent style) and a widget has only one ``objectName``.  A public accessor is
+        the workaround the plan settled on — see ``doc/plans/gui-integration-video.md``
+        §6.
+        """
+        return self._choose
+
     def _known_paths(self) -> set[str]:
         """The filesystem paths of the raw-image repos we already know about."""
         known: set[str] = set()
@@ -869,6 +886,9 @@ class SetupWizard(QWizard):
         self.action: str | None = None
 
         self.setWindowTitle("Starbash setup")
+        # A stable handle for the gui-integration movie (doc/plans/gui-integration-video.md
+        # §6); names, not behaviour.
+        self.setObjectName("SetupWizard")
         self.setWizardStyle(QWizard.WizardStyle.ModernStyle)
         # Page 1 is the start of the story, so a greyed-out *Back* is just noise.
         self.setOption(QWizard.WizardOption.NoBackButtonOnStartPage)
@@ -901,6 +921,11 @@ class SetupWizard(QWizard):
         self.setOption(QWizard.WizardOption.HaveCustomButton2)
         self.setButtonText(QWizard.WizardButton.CustomButton1, "Process all my targets")
         self.setButtonText(QWizard.WizardButton.CustomButton2, "Pick a target to process")
+        # The script's handles for those two actions (doc/plans/gui-integration-video.md
+        # §6). Qt pre-created the buttons, so naming them here is enough - and the
+        # names are new ids, so the theme (which styles nothing of theirs) is untouched.
+        self._name_action_button(QWizard.WizardButton.CustomButton1, "wizardProcessAllTargets")
+        self._name_action_button(QWizard.WizardButton.CustomButton2, "wizardPickTarget")
         # Qt creates those two *enabled* and shows them on every page, and it never
         # consults isComplete() for custom buttons - so without this the wizard
         # offered a live "Process all my targets" on page 1 and only switched it off
@@ -959,6 +984,16 @@ class SetupWizard(QWizard):
                 buttons.append(button)
         return buttons
 
+    def _name_action_button(self, which: QWizard.WizardButton, name: str) -> None:
+        """Give one of Qt's custom buttons an ``objectName`` (see the constructor).
+
+        Qt types :meth:`button` as ``QAbstractButton``; the closing actions are the
+        ``QPushButton`` it actually created.
+        """
+        button = self.button(which)
+        if isinstance(button, QPushButton):
+            button.setObjectName(name)
+
     def _disable_action_buttons(self) -> None:
         """Switch the closing actions off, and say when they come alive.