starbash 0.1.35__tar.gz → 0.2.0__tar.gz

{starbash-0.1.35 → starbash-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starbash
-Version: 0.1.35
+Version: 0.2.0
 Summary: A tool for automating/standardizing/sharing astrophotography workflows.
 License-File: LICENSE
 Author: Kevin Hester
@@ -29,15 +29,17 @@ Description-Content-Type: text/markdown
 
 # [Starbash](https://github.com/geeksville/starbash)
 
-<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
-
 [![PyPI - Version](https://img.shields.io/pypi/v/starbash)](https://pypi.org/project/starbash/)
 [![Continuous Integration](https://github.com/geeksville/starbash/actions/workflows/ci.yml/badge.svg)](https://github.com/geeksville/starbash/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/geeksville/starbash/graph/badge.svg?token=47RE10I7O1)](https://codecov.io/github/geeksville/starbash)
 
 A tool for automating/standardizing/sharing astrophotography workflows.
 
-* Automatic - with sensible defaults that you can change as needed.
+## What is starbash?
+
+<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
+
+* Automatic - with sensible defaults that you can change as needed.  Just a few keystrokes to preprocess an entire repo of raw images.
 * Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing.
 * Fast<sup>1</sup> - even with large image repositories.  Automatic master bias and flat generation.  Automatic preprocessing/ stacking/background-elimination with reasonable defaults.
 * Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...).
@@ -49,7 +51,22 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 <sub>**Caveats:**
 1. 'Fast' in terms of you 'just need to click run and magically (ahem) everything just happens.'  But if you ask it to process many images it can take hours - just come back when it is done.</sub>
 
-<br clear="right">
+## What is starbash NOT
+
+### Not a new image processing tool (like Siril)
+It is important to understand that Starbash is primarily a tool for **repeatable**, **sharable**, **semi-automated** workflows.  It is tool agnostic and really just focuses on the relationship between tools, images and sessions.  It builds upon the great work of existing tools (currently mainly Siril and Graxpert) so we can grow an ecosystem of recipes.
+
+### Not a set of scripts
+
+It is more a tool for moving away from (sometimes long and complex) opaque scripts.  "Recipes" are kinda like scripts except they are small and atomic and use dependencies to be automatically installed at the appropriate stage of workflows.  But the actual operations performed by a recipe can be for any of the supported tools.
+
+For instance: if you don't like a particular "stack" stage recipe you can swap out just that portion of the workflow for an alternate implementation.  Or make your own and share it with others.  (With full automatic versioning so that workflows hopefully always keep working/evolving)
+
+Starbash understands FITS metadata and how to run tools based on that metadata, but the actual image transformations are entirely up to you and anyone who writes a recipe.
+
+We provide a few example recipes to enable auto-selection of common workflows (see below for example links).  But hopefully others will either add to these recipes or host their own recipe repos.
+
+If you are familar with the software enginering tools "npm, make and git", the goal of this project is to provide an analogous sharable workflows for astrophotography.
 
 # Current status
 
@@ -69,20 +86,27 @@ If you are interested in alpha-testing we ❤️ you.  This README should have e
 * Uses Siril recipes for its pre-processing operations (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ### From the alpha 2 (0.2.0) release (2025/12/12 ish)
-* Include a stretched 'thumbnail'(FIXME - link example thumbnail) jpg proof-of-concept render in the output directories
-* Generates a per-target [report/config file](FIXME - link example processed toml) which can be customized if the detected defaults or preprocessing are not what you want.
+* Include a stretched 'thumbnail'(FIXME/link/example/thumbnail) jpg proof-of-concept render in the output directories
+* Generates a per-target [report/config file](doc/toml/example/processed-repo/example-m20.toml) which can be customized if the detected defaults or preprocessing are not what you want.
 * '[Recipes](https://github.com/geeksville/starbash-recipes)' are now user-editable - provides repeatable/human-[readable](doc/toml/example/processed-repo/example-m20.toml)/shareable descriptions of all processing steps. [example Siril OSC stacking](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/osc/osc_simple.toml), [example Graxpert BGE](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/graxpert/background.toml), [example thumbnail generation](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/common/thumbnail.toml)...
 * Repos can be on the local disk or shared via HTTPS/GitHub/etc.  This is particularly useful for recipe repos.
 * [Graxpert](https://graxpert.com/) based [recipe stages](https://github.com/geeksville/starbash-recipes/tree/main/graxpert) added (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ## Features coming soon
 
-* Better recipe 'writers guide' documentation.
-* Support for mono-camera workflows (the alpha only has osc recipes).
+* Recipe 'writers guide' documentation.  Currently iterating based on usage reports 😄
+* Support for mono-camera workflows (the alpha only includes osc recipes).
 * The target report can be used to auto-generate a human-friendly 'postable/shareable' report about that image.
 * Target reports are shareable so that you can request comments from others and others can rerender with different settings.
 * Namespaces for recipes are disambiguated to be globally unique
 
+## Features (possibly) coming eventually
+
+* [IPFS](https://ipfs.tech/) based sharing of images and the workflows used to build those images (if you wish)
+* Nice graph view of raw images, recipes and operations that contributed to a final image.  Also possibly exposed via IPFS.
+* Pixinsight?
+* Autostakkert?
+
 See the [TODO](TODO.md) file for work items and approximate schedule.
 
 ## Support
@@ -206,8 +230,6 @@ If you don't want the automated processing you can still ask Starbash to prepare
 
 ## Supported telescope software
 
-FIXME explain FITS and directory paths
-
 * N.I.N.A. - tested, seems fairly okay.
 * Asiair - tested, seems fairly okay.
 * Seestar - tested, seems fairly okay.
@@ -221,27 +243,11 @@ Starbash is a tool agnostic workflow manager.  But it wouldn't be possible witho
 * [Graxpert](https://graxpert.com/) - for background and noise elimination
 * [Python](https://www.python.org/) (you can add Python code to recipes if necessary)
 
-## Supported tools (future?)
-
-* Pixinsight?
-* Autostakkert?
-
 ## Credits
 * Various reddit users who submitted anonymous crash reports from alpha 1
 * [@codegistics](https://github.com/codegistics) for kindly donating Dwarf3 test data and invaluable debugging assistance.
 * The developers of Siril and Graxpert - which are wonderful tools.
-* The [doit](https://pydoit.org/) automation building tool, which substantially simiplified this tool's development.
-
-## Design
-
-FIXME - write this
-
-FIXME - what this tool is
-a way to avoid opaque script blobs that are tied to a particular tool.
-instead a way to make sharable/extendable workflows from atomic mini-tools
-A way to capture preprocessing steps used to create an image
-FIXME - what this tool isn't
-Influences from make, npm, github.
+* The [doit](https://pydoit.org/) an **amazing** automation building tool, which substantially simiplified this tool's development.
 
 ## Development
 

{starbash-0.1.35 → starbash-0.2.0}/README.md

@@ -1,14 +1,16 @@
 # [Starbash](https://github.com/geeksville/starbash)
 
-<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
-
 [![PyPI - Version](https://img.shields.io/pypi/v/starbash)](https://pypi.org/project/starbash/)
 [![Continuous Integration](https://github.com/geeksville/starbash/actions/workflows/ci.yml/badge.svg)](https://github.com/geeksville/starbash/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/geeksville/starbash/graph/badge.svg?token=47RE10I7O1)](https://codecov.io/github/geeksville/starbash)
 
 A tool for automating/standardizing/sharing astrophotography workflows.
 
-* Automatic - with sensible defaults that you can change as needed.
+## What is starbash?
+
+<img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/doc/img/icon.jpg" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
+
+* Automatic - with sensible defaults that you can change as needed.  Just a few keystrokes to preprocess an entire repo of raw images.
 * Easy - provides a 'seestar-like' autoprocessing all your sessions (by default).  You can optionally do manual postprocessing with all this 'grunt work' preprocessing.
 * Fast<sup>1</sup> - even with large image repositories.  Automatic master bias and flat generation.  Automatic preprocessing/ stacking/background-elimination with reasonable defaults.
 * Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...).
@@ -20,7 +22,22 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 <sub>**Caveats:**
 1. 'Fast' in terms of you 'just need to click run and magically (ahem) everything just happens.'  But if you ask it to process many images it can take hours - just come back when it is done.</sub>
 
-<br clear="right">
+## What is starbash NOT
+
+### Not a new image processing tool (like Siril)
+It is important to understand that Starbash is primarily a tool for **repeatable**, **sharable**, **semi-automated** workflows.  It is tool agnostic and really just focuses on the relationship between tools, images and sessions.  It builds upon the great work of existing tools (currently mainly Siril and Graxpert) so we can grow an ecosystem of recipes.
+
+### Not a set of scripts
+
+It is more a tool for moving away from (sometimes long and complex) opaque scripts.  "Recipes" are kinda like scripts except they are small and atomic and use dependencies to be automatically installed at the appropriate stage of workflows.  But the actual operations performed by a recipe can be for any of the supported tools.
+
+For instance: if you don't like a particular "stack" stage recipe you can swap out just that portion of the workflow for an alternate implementation.  Or make your own and share it with others.  (With full automatic versioning so that workflows hopefully always keep working/evolving)
+
+Starbash understands FITS metadata and how to run tools based on that metadata, but the actual image transformations are entirely up to you and anyone who writes a recipe.
+
+We provide a few example recipes to enable auto-selection of common workflows (see below for example links).  But hopefully others will either add to these recipes or host their own recipe repos.
+
+If you are familar with the software enginering tools "npm, make and git", the goal of this project is to provide an analogous sharable workflows for astrophotography.
 
 # Current status
 
@@ -40,20 +57,27 @@ If you are interested in alpha-testing we ❤️ you.  This README should have e
 * Uses Siril recipes for its pre-processing operations (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ### From the alpha 2 (0.2.0) release (2025/12/12 ish)
-* Include a stretched 'thumbnail'(FIXME - link example thumbnail) jpg proof-of-concept render in the output directories
-* Generates a per-target [report/config file](FIXME - link example processed toml) which can be customized if the detected defaults or preprocessing are not what you want.
+* Include a stretched 'thumbnail'(FIXME/link/example/thumbnail) jpg proof-of-concept render in the output directories
+* Generates a per-target [report/config file](doc/toml/example/processed-repo/example-m20.toml) which can be customized if the detected defaults or preprocessing are not what you want.
 * '[Recipes](https://github.com/geeksville/starbash-recipes)' are now user-editable - provides repeatable/human-[readable](doc/toml/example/processed-repo/example-m20.toml)/shareable descriptions of all processing steps. [example Siril OSC stacking](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/osc/osc_simple.toml), [example Graxpert BGE](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/graxpert/background.toml), [example thumbnail generation](https://github.com/geeksville/starbash-recipes/blob/6d255f48591c4991ddc1168ffa5c38050a500771/common/thumbnail.toml)...
 * Repos can be on the local disk or shared via HTTPS/GitHub/etc.  This is particularly useful for recipe repos.
 * [Graxpert](https://graxpert.com/) based [recipe stages](https://github.com/geeksville/starbash-recipes/tree/main/graxpert) added (support for Pixinsight-based recipes will probably be coming at some point...).
 
 ## Features coming soon
 
-* Better recipe 'writers guide' documentation.
-* Support for mono-camera workflows (the alpha only has osc recipes).
+* Recipe 'writers guide' documentation.  Currently iterating based on usage reports 😄
+* Support for mono-camera workflows (the alpha only includes osc recipes).
 * The target report can be used to auto-generate a human-friendly 'postable/shareable' report about that image.
 * Target reports are shareable so that you can request comments from others and others can rerender with different settings.
 * Namespaces for recipes are disambiguated to be globally unique
 
+## Features (possibly) coming eventually
+
+* [IPFS](https://ipfs.tech/) based sharing of images and the workflows used to build those images (if you wish)
+* Nice graph view of raw images, recipes and operations that contributed to a final image.  Also possibly exposed via IPFS.
+* Pixinsight?
+* Autostakkert?
+
 See the [TODO](TODO.md) file for work items and approximate schedule.
 
 ## Support
@@ -177,8 +201,6 @@ If you don't want the automated processing you can still ask Starbash to prepare
 
 ## Supported telescope software
 
-FIXME explain FITS and directory paths
-
 * N.I.N.A. - tested, seems fairly okay.
 * Asiair - tested, seems fairly okay.
 * Seestar - tested, seems fairly okay.
@@ -192,27 +214,11 @@ Starbash is a tool agnostic workflow manager.  But it wouldn't be possible witho
 * [Graxpert](https://graxpert.com/) - for background and noise elimination
 * [Python](https://www.python.org/) (you can add Python code to recipes if necessary)
 
-## Supported tools (future?)
-
-* Pixinsight?
-* Autostakkert?
-
 ## Credits
 * Various reddit users who submitted anonymous crash reports from alpha 1
 * [@codegistics](https://github.com/codegistics) for kindly donating Dwarf3 test data and invaluable debugging assistance.
 * The developers of Siril and Graxpert - which are wonderful tools.
-* The [doit](https://pydoit.org/) automation building tool, which substantially simiplified this tool's development.
-
-## Design
-
-FIXME - write this
-
-FIXME - what this tool is
-a way to avoid opaque script blobs that are tied to a particular tool.
-instead a way to make sharable/extendable workflows from atomic mini-tools
-A way to capture preprocessing steps used to create an image
-FIXME - what this tool isn't
-Influences from make, npm, github.
+* The [doit](https://pydoit.org/) an **amazing** automation building tool, which substantially simiplified this tool's development.
 
 ## Development
 

{starbash-0.1.35 → starbash-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "starbash"
-version = "0.1.35"
+version = "0.2.0"
 description = "A tool for automating/standardizing/sharing astrophotography workflows."
 authors = ["Kevin Hester <kevinh@geeksville.com>"]
 readme = "README.md"

{starbash-0.1.35 → starbash-0.2.0}/src/starbash/app.py

@@ -271,6 +271,7 @@ class Starbash:
         return self
 
     def __exit__(self, exc_type, exc, tb) -> bool:
+        from starbash import _is_test_env
         from starbash.exception import UserHandledError
 
         handled = False
@@ -284,7 +285,18 @@ class Starbash:
                 raise typer.Exit(code=1)
             else:
                 handled = analytics_exception(exc)
-        self.close()
+                self.close()
+                if not handled:
+                    # Show the full exception for developers
+                    starbash.console.print_exception(show_locals=True)
+
+                # In test environments, let exceptions propagate naturally for better test diagnostics
+                if not _is_test_env:
+                    # But in any case, make our app exit with an error code
+                    raise typer.Exit(code=1)
+        else:
+            self.close()
+
         return handled
 
     def _add_session(self, header: dict) -> None:
@@ -439,7 +451,7 @@ class Starbash:
                 absolute_path = repo.resolve_path(relative_path)
                 image["abspath"] = str(absolute_path)
             else:
-                logging.error(f"Repo not found for URL: {repo_url}, skipping image...")
+                raise UserHandledError(f"Repo not found for URL: {repo_url}, session skipped.")
 
         return image
 

{starbash-0.1.35 → starbash-0.2.0}/src/starbash/commands/process.py

@@ -14,6 +14,7 @@ from starbash.commands.__init__ import (
 from starbash.commands.select import selection_by_number
 from starbash.database import SessionRow
 from starbash.doit import FileInfo
+from starbash.paths import get_user_config_path
 from starbash.processed_target import ProcessedTarget
 from starbash.processing import Processing, ProcessingResult
 from starbash.rich import to_rich_link
@@ -110,7 +111,9 @@ def print_results(
     from rich.table import Table
 
     if not results:
-        console.print(f"[yellow]{title}: No results, do you have a target selected?[/yellow]")
+        console.print(
+            f"[yellow]{title}: No results, do you have a target selected?  If this is your first time here run 'sb user setup'[/yellow]"
+        )
         return
 
     table = Table(title=title, show_header=True, header_style=TABLE_HEADER_STYLE)
@@ -212,6 +215,14 @@ def auto(
         import starbash
 
         starbash.process_masters = False
+
+    # Users might run "process auto" as their first command without reading any docs...
+    if not get_user_config_path().exists():
+        from starbash import console
+
+        console.print("[red]No app setup found.[/red]  Please run 'sb user setup'.")
+        raise typer.Exit(1)
+
     with Starbash("process.auto") as sb:
         with Processing(sb) as proc:
             from starbash import console
@@ -223,7 +234,6 @@ def auto(
             else:
                 console.print("[yellow]Auto-processing all selected sessions...[/yellow]")
 
-            try:
                 results = proc.run_all_stages()
 
                 title = "Autoprocessed"
@@ -237,10 +247,6 @@ def auto(
 
                 print_results(title, results, console)
 
-            except Exception:
-                console.print_exception(show_locals=True)
-                raise typer.Exit(code=1)
-
 
 @app.command(
     context_settings={"allow_extra_args": True, "ignore_unknown_options": True},

{starbash-0.1.35 → starbash-0.2.0}/src/starbash/commands/user.py

@@ -152,6 +152,7 @@ def _ask_user_config(sb: Starbash) -> None:
 
 
 def do_reinit(sb: Starbash) -> None:
+    """Do guided 1st time setup for starbash."""
     from starbash import console
 
     console.print()

{starbash-0.1.35 → starbash-0.2.0}/src/starbash/processing.py

@@ -497,7 +497,7 @@ class Processing(ProcessingLike):
         # for parallism etc...?
         # self.doit.run(["list", "--all", "--status"])
 
-        logging.info("Running doit tasks...")
+        logging.debug("Running doit tasks...")
         doit_args: list[str] = []
         if starbash.force_regen:
             doit_args.append("-a")  # force rebuild