starbash 0.1.9__py3-none-any.whl → 0.1.10__py3-none-any.whl

starbash/database.py

@@ -2,17 +2,32 @@ from __future__ import annotations
 
 import sqlite3
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, Optional, NamedTuple
 from datetime import datetime, timedelta
 import json
 from typing import TypeAlias
 
 from .paths import get_user_data_dir
+from .aliases import normalize_target_name
 
 SessionRow: TypeAlias = dict[str, Any]
 ImageRow: TypeAlias = dict[str, Any]
 
 
+class SearchCondition(NamedTuple):
+    """A search condition for database queries.
+
+    Args:
+        column_name: The column name to filter on (e.g., 'i.date_obs', 'r.url')
+        comparison_op: The comparison operator (e.g., '=', '>=', '<=', 'LIKE')
+        value: The value to compare against
+    """
+
+    column_name: str
+    comparison_op: str
+    value: Any
+
+
 def get_column_name(k: str) -> str:
     """Convert keynames to SQL legal column names"""
     k = k.lower()
@@ -34,8 +49,8 @@ class Database:
     #2: images
     Provides an `images` table for FITS metadata and basic helpers.
 
-    The images table stores DATE-OBS and DATE as indexed SQL columns for
-    efficient date-based queries, while other FITS metadata is stored in JSON.
+    The images table stores DATE-OBS, DATE, and IMAGETYP as indexed SQL columns for
+    efficient date-based and type-based queries, while other FITS metadata is stored in JSON.
 
     The 'path' column contains a path **relative** to the repository root.
     Each image belongs to exactly one repo, linked via the repo_id foreign key.
@@ -68,7 +83,9 @@ class Database:
     IMAGETYP_KEY = "IMAGETYP"
     OBJECT_KEY = "OBJECT"
     TELESCOP_KEY = "TELESCOP"
+    EXPTIME_KEY = "EXPTIME"
     ID_KEY = "id"  # for finding any row by its ID
+    REPO_URL_KEY = "repo_url"
 
     SESSIONS_TABLE = "sessions"
     IMAGES_TABLE = "images"
@@ -115,7 +132,7 @@ class Database:
         """
         )
 
-        # Create images table with DATE-OBS and DATE as indexed columns
+        # Create images table with DATE-OBS, DATE, and IMAGETYP as indexed columns
         cursor.execute(
             f"""
             CREATE TABLE IF NOT EXISTS {self.IMAGES_TABLE} (
@@ -124,6 +141,7 @@ class Database:
                 path TEXT NOT NULL,
                 date_obs TEXT,
                 date TEXT,
+                imagetyp TEXT COLLATE NOCASE,
                 metadata TEXT NOT NULL,
                 FOREIGN KEY (repo_id) REFERENCES {self.REPOS_TABLE}(id),
                 UNIQUE(repo_id, path)
@@ -152,6 +170,13 @@ class Database:
         """
         )
 
+        # Create index on imagetyp for efficient image type filtering
+        cursor.execute(
+            f"""
+            CREATE INDEX IF NOT EXISTS idx_images_imagetyp ON {self.IMAGES_TABLE}(imagetyp)
+        """
+        )
+
         # Create sessions table
         cursor.execute(
             f"""
@@ -159,12 +184,13 @@ class Database:
                 id INTEGER PRIMARY KEY AUTOINCREMENT,
                 start TEXT NOT NULL,
                 end TEXT NOT NULL,
-                filter TEXT NOT NULL,
-                imagetyp TEXT NOT NULL,
-                object TEXT NOT NULL,
+                filter TEXT COLLATE NOCASE,
+                imagetyp TEXT COLLATE NOCASE NOT NULL,
+                object TEXT,
                 telescop TEXT NOT NULL,
                 num_images INTEGER NOT NULL,
                 exptime_total REAL NOT NULL,
+                exptime REAL NOT NULL,
                 image_doc_id INTEGER,
                 FOREIGN KEY (image_doc_id) REFERENCES {self.IMAGES_TABLE}(id)
             )
@@ -175,7 +201,7 @@ class Database:
         cursor.execute(
             f"""
             CREATE INDEX IF NOT EXISTS idx_sessions_lookup
-            ON {self.SESSIONS_TABLE}(filter, imagetyp, object, telescop, start, end)
+            ON {self.SESSIONS_TABLE}(filter, imagetyp, object, telescop, exptime, start, end)
         """
         )
 
@@ -186,38 +212,44 @@ class Database:
         """Remove a repo record by URL.
 
         This will cascade delete all images belonging to this repo, and all sessions
-        that reference those images.
+        that reference those images via image_doc_id.
+
+        The relationship is: repos -> images (via repo_id) -> sessions (via image_doc_id).
+        Sessions have an image_doc_id field that points to a representative image.
+        We delete sessions whose representative image belongs to the repo being deleted.
 
         Args:
             url: The repository URL (e.g., 'file:///path/to/repo')
         """
         cursor = self._db.cursor()
 
-        # First get the repo_id
-        repo_id = self.get_repo_id(url)
-        if repo_id is None:
-            return  # Repo doesn't exist, nothing to delete
-
-        # Delete sessions that reference images from this repo
-        # This deletes sessions where image_doc_id points to any image in this repo
+        # Use a 3-way join to find and delete sessions that reference images from this repo
+        # repo_url -> repo_id -> images.id -> sessions.image_doc_id
         cursor.execute(
             f"""
             DELETE FROM {self.SESSIONS_TABLE}
-            WHERE image_doc_id IN (
-                SELECT id FROM {self.IMAGES_TABLE} WHERE repo_id = ?
+            WHERE id IN (
+                SELECT s.id
+                FROM {self.SESSIONS_TABLE} s
+                INNER JOIN {self.IMAGES_TABLE} i ON s.image_doc_id = i.id
+                INNER JOIN {self.REPOS_TABLE} r ON i.repo_id = r.id
+                WHERE r.url = ?
             )
             """,
-            (repo_id,),
+            (url,),
         )
 
-        # Delete all images from this repo
+        # Delete all images from this repo (using repo_id from URL)
         cursor.execute(
-            f"DELETE FROM {self.IMAGES_TABLE} WHERE repo_id = ?",
-            (repo_id,),
+            f"""
+            DELETE FROM {self.IMAGES_TABLE}
+            WHERE repo_id = (SELECT id FROM {self.REPOS_TABLE} WHERE url = ?)
+            """,
+            (url,),
         )
 
         # Finally delete the repo itself
-        cursor.execute(f"DELETE FROM {self.REPOS_TABLE} WHERE id = ?", (repo_id,))
+        cursor.execute(f"DELETE FROM {self.REPOS_TABLE} WHERE url = ?", (url,))
 
         self._db.commit()
 
@@ -282,7 +314,7 @@ class Database:
 
         The record must include a 'path' key (relative to repo); other keys are arbitrary FITS metadata.
         The path is stored as-is - caller is responsible for making it relative to the repo.
-        DATE-OBS and DATE are extracted and stored as indexed columns for efficient queries.
+        DATE-OBS, DATE, and IMAGETYP are extracted and stored as indexed columns for efficient queries.
 
         Args:
             record: Dictionary containing image metadata including 'path' (relative to repo)
@@ -300,24 +332,26 @@ class Database:
         if repo_id is None:
             repo_id = self.upsert_repo(repo_url)
 
-        # Extract date fields for column storage
+        # Extract special fields for column storage
         date_obs = record.get(self.DATE_OBS_KEY)
         date = record.get(self.DATE_KEY)
+        imagetyp = record.get(self.IMAGETYP_KEY)
 
-        # Separate path and date fields from metadata
+        # Separate path and special fields from metadata
         metadata = {k: v for k, v in record.items() if k != "path"}
         metadata_json = json.dumps(metadata)
 
         cursor = self._db.cursor()
         cursor.execute(
             f"""
-            INSERT INTO {self.IMAGES_TABLE} (repo_id, path, date_obs, date, metadata) VALUES (?, ?, ?, ?, ?)
+            INSERT INTO {self.IMAGES_TABLE} (repo_id, path, date_obs, date, imagetyp, metadata) VALUES (?, ?, ?, ?, ?, ?)
             ON CONFLICT(repo_id, path) DO UPDATE SET
                 date_obs = excluded.date_obs,
                 date = excluded.date,
+                imagetyp = excluded.imagetyp,
                 metadata = excluded.metadata
         """,
-            (repo_id, str(path), date_obs, date, metadata_json),
+            (repo_id, str(path), date_obs, date, imagetyp, metadata_json),
         )
 
         self._db.commit()
@@ -332,38 +366,36 @@ class Database:
             return result[0]
         return cursor.lastrowid if cursor.lastrowid is not None else 0
 
-    def search_image(self, conditions: dict[str, Any]) -> list[SessionRow]:
+    def search_image(self, conditions: list[SearchCondition]) -> list[ImageRow]:
         """Search for images matching the given conditions.
 
         Args:
-            conditions: Dictionary of metadata key-value pairs to match.
-                       Special keys:
-                       - 'date_start': Filter images with DATE-OBS >= this date
-                       - 'date_end': Filter images with DATE-OBS <= this date
+            conditions: List of SearchCondition tuples, each containing:
+                       - column_name: The column to filter on (e.g., 'i.date_obs', 'r.url', 'i.imagetyp')
+                       - comparison_op: The comparison operator (e.g., '=', '>=', '<=')
+                       - value: The value to compare against
 
         Returns:
             List of matching image records with relative path, repo_id, and repo_url
-        """
-        # Extract special date filter keys (make a copy to avoid modifying caller's dict)
-        conditions_copy = dict(conditions)
-        date_start = conditions_copy.pop("date_start", None)
-        date_end = conditions_copy.pop("date_end", None)
 
-        # Build SQL query with WHERE clauses for date filtering
+        Example:
+            conditions = [
+                SearchCondition('r.url', '=', 'file:///path/to/repo'),
+                SearchCondition('i.imagetyp', '=', 'BIAS'),
+                SearchCondition('i.date_obs', '>=', '2025-01-01'),
+            ]
+        """
+        # Build SQL query with WHERE clauses from conditions
         where_clauses = []
         params = []
 
-        if date_start:
-            where_clauses.append("i.date_obs >= ?")
-            params.append(date_start)
-
-        if date_end:
-            where_clauses.append("i.date_obs <= ?")
-            params.append(date_end)
+        for condition in conditions:
+            where_clauses.append(f"{condition.column_name} {condition.comparison_op} ?")
+            params.append(condition.value)
 
         # Build the query with JOIN to repos table
         query = f"""
-            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.metadata, r.url as repo_url
+            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.imagetyp, i.metadata, r.url as repo_url
             FROM {self.IMAGES_TABLE} i
             JOIN {self.REPOS_TABLE} r ON i.repo_id = r.id
         """
@@ -379,20 +411,18 @@ class Database:
             # Store the relative path, repo_id, and repo_url for caller
             metadata["path"] = row["path"]
             metadata["repo_id"] = row["repo_id"]
-            metadata["repo_url"] = row["repo_url"]
+            metadata[Database.REPO_URL_KEY] = row[Database.REPO_URL_KEY]
             metadata["id"] = row["id"]
 
-            # Add date fields back to metadata for compatibility
+            # Add special fields back to metadata for compatibility
             if row["date_obs"]:
                 metadata[self.DATE_OBS_KEY] = row["date_obs"]
             if row["date"]:
                 metadata[self.DATE_KEY] = row["date"]
+            if row["imagetyp"]:
+                metadata[self.IMAGETYP_KEY] = row["imagetyp"]
 
-            # Check if remaining conditions match (those stored in JSON metadata)
-            match = all(metadata.get(k) == v for k, v in conditions_copy.items())
-
-            if match:
-                results.append(metadata)
+            results.append(metadata)
 
         return results
 
@@ -402,10 +432,7 @@ class Database:
         """Search for sessions matching the given conditions.
 
         Args:
-            conditions: Dictionary of session key-value pairs to match, or None for all.
-                       Special keys:
-                       - 'date_start': Filter sessions starting on or after this date
-                       - 'date_end': Filter sessions starting on or before this date
+            where_tuple
 
         Returns:
             List of matching session records with metadata from the reference image
@@ -416,7 +443,7 @@ class Database:
         # Build the query with JOIN to images table to get reference image metadata
         query = f"""
             SELECT s.id, s.start, s.end, s.filter, s.imagetyp, s.object, s.telescop,
-                   s.num_images, s.exptime_total, s.image_doc_id, i.metadata
+                   s.num_images, s.exptime_total, s.exptime, s.image_doc_id, i.metadata
             FROM {self.SESSIONS_TABLE} s
             LEFT JOIN {self.IMAGES_TABLE} i ON s.image_doc_id = i.id
             {where_clause}
@@ -473,7 +500,7 @@ class Database:
         cursor = self._db.cursor()
         cursor.execute(
             f"""
-            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.metadata, r.url as repo_url
+            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.imagetyp, i.metadata, r.url as repo_url
             FROM {self.IMAGES_TABLE} i
             JOIN {self.REPOS_TABLE} r ON i.repo_id = r.id
             WHERE r.url = ? AND i.path = ?
@@ -488,14 +515,16 @@ class Database:
         metadata = json.loads(row["metadata"])
         metadata["path"] = row["path"]
         metadata["repo_id"] = row["repo_id"]
-        metadata["repo_url"] = row["repo_url"]
+        metadata[Database.REPO_URL_KEY] = row[Database.REPO_URL_KEY]
         metadata["id"] = row["id"]
 
-        # Add date fields back to metadata for compatibility
+        # Add special fields back to metadata for compatibility
         if row["date_obs"]:
             metadata[self.DATE_OBS_KEY] = row["date_obs"]
         if row["date"]:
             metadata[self.DATE_KEY] = row["date"]
+        if row["imagetyp"]:
+            metadata[self.IMAGETYP_KEY] = row["imagetyp"]
 
         return metadata
 
@@ -504,7 +533,7 @@ class Database:
         cursor = self._db.cursor()
         cursor.execute(
             f"""
-            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.metadata, r.url as repo_url
+            SELECT i.id, i.repo_id, i.path, i.date_obs, i.date, i.imagetyp, i.metadata, r.url as repo_url
             FROM {self.IMAGES_TABLE} i
             JOIN {self.REPOS_TABLE} r ON i.repo_id = r.id
             """
@@ -516,14 +545,16 @@ class Database:
             # Return relative path, repo_id, and repo_url for caller
             metadata["path"] = row["path"]
             metadata["repo_id"] = row["repo_id"]
-            metadata["repo_url"] = row["repo_url"]
+            metadata[Database.REPO_URL_KEY] = row[Database.REPO_URL_KEY]
             metadata["id"] = row["id"]
 
-            # Add date fields back to metadata for compatibility
+            # Add special fields back to metadata for compatibility
             if row["date_obs"]:
                 metadata[self.DATE_OBS_KEY] = row["date_obs"]
             if row["date"]:
                 metadata[self.DATE_KEY] = row["date"]
+            if row["imagetyp"]:
+                metadata[self.IMAGETYP_KEY] = row["imagetyp"]
 
             results.append(metadata)
 
@@ -542,7 +573,7 @@ class Database:
         cursor.execute(
             f"""
             SELECT id, start, end, filter, imagetyp, object, telescop,
-                   num_images, exptime_total, image_doc_id
+                   num_images, exptime_total, exptime, image_doc_id
             FROM {self.SESSIONS_TABLE}
             WHERE id = ?
         """,
@@ -561,15 +592,10 @@ class Database:
         Searches for sessions with the same filter, image type, target, and telescope
         whose start time is within +/- 8 hours of the provided date.
         """
-        date = to_find.get(Database.START_KEY)
+        date = to_find.get(get_column_name(Database.START_KEY))
         assert date
-        image_type = to_find.get(Database.IMAGETYP_KEY)
+        image_type = to_find.get(get_column_name(Database.IMAGETYP_KEY))
         assert image_type
-        filter = to_find.get(Database.FILTER_KEY)
-        assert filter
-        target = to_find.get(Database.OBJECT_KEY)
-        assert target
-        telescop = to_find.get(Database.TELESCOP_KEY, "unspecified")
 
         # Convert the provided ISO8601 date string to a datetime, then
         # search for sessions with the same filter whose start time is
@@ -581,17 +607,75 @@ class Database:
 
         # Since session 'start' is stored as ISO8601 strings, lexicographic
         # comparison aligns with chronological ordering for a uniform format.
+
+        # Build WHERE clause handling NULL values properly
+        # In SQL, you cannot use = with NULL, must use IS NULL
+        # If a field is not in to_find, we don't filter on it at all
+        where_clauses = []
+        params = []
+
+        # Handle imagetyp (required)
+        where_clauses.append("imagetyp = ?")
+        params.append(image_type)
+
+        # Handle filter (optional - only filter if present in to_find)
+        filter_key = get_column_name(Database.FILTER_KEY)
+        filter = to_find.get(filter_key)  # filter can be the string "None"
+        if filter:
+            if filter is None:
+                where_clauses.append("filter IS NULL")
+            else:
+                where_clauses.append("filter = ?")
+                params.append(filter)
+
+        # Handle object/target (optional - only filter if present in to_find)
+        object_key = get_column_name(Database.OBJECT_KEY)
+        target = to_find.get(object_key)
+        if target:
+            target = normalize_target_name(target)
+            if target is None:
+                where_clauses.append("object IS NULL")
+            else:
+                where_clauses.append("object = ?")
+                params.append(target)
+
+        # Handle telescop (optional - only filter if present in to_find)
+        telescop_key = get_column_name(Database.TELESCOP_KEY)
+        telescop = to_find.get(telescop_key)
+        if telescop:
+            if telescop is None:
+                where_clauses.append("telescop IS NULL")
+            else:
+                where_clauses.append("telescop = ?")
+                params.append(telescop)
+
+        # Handle exptime (optional - only filter if present in to_find)
+        exptime_key = get_column_name(Database.EXPTIME_KEY)
+        if exptime_key in to_find:
+            exptime = to_find.get(exptime_key)
+            if exptime is None:
+                where_clauses.append("exptime IS NULL")
+            else:
+                where_clauses.append("exptime = ?")
+                params.append(exptime)
+
+        # Time window
+        where_clauses.append("start >= ?")
+        where_clauses.append("start <= ?")
+        params.extend([start_min, start_max])
+
+        where_clause = " AND ".join(where_clauses)
+
         cursor = self._db.cursor()
         cursor.execute(
             f"""
             SELECT id, start, end, filter, imagetyp, object, telescop,
-                   num_images, exptime_total, image_doc_id
+                   num_images, exptime_total, exptime, image_doc_id
             FROM {self.SESSIONS_TABLE}
-            WHERE filter = ? AND imagetyp = ? AND object = ? AND telescop = ?
-              AND start >= ? AND start <= ?
+            WHERE {where_clause}
             LIMIT 1
         """,
-            (filter, image_type, target, telescop, start_min, start_max),
+            params,
         )
 
         row = cursor.fetchone()
@@ -608,14 +692,20 @@ class Database:
 
         if existing:
             # Update existing session with new data
-            updated_start = min(new[Database.START_KEY], existing[Database.START_KEY])
-            updated_end = max(new[Database.END_KEY], existing[Database.END_KEY])
-            updated_num_images = existing.get(Database.NUM_IMAGES_KEY, 0) + new.get(
-                Database.NUM_IMAGES_KEY, 0
+            updated_start = min(
+                new[get_column_name(Database.START_KEY)],
+                existing[get_column_name(Database.START_KEY)],
+            )
+            updated_end = max(
+                new[get_column_name(Database.END_KEY)],
+                existing[get_column_name(Database.END_KEY)],
             )
+            updated_num_images = existing.get(
+                get_column_name(Database.NUM_IMAGES_KEY), 0
+            ) + new.get(get_column_name(Database.NUM_IMAGES_KEY), 0)
             updated_exptime_total = existing.get(
-                Database.EXPTIME_TOTAL_KEY, 0
-            ) + new.get(Database.EXPTIME_TOTAL_KEY, 0)
+                get_column_name(Database.EXPTIME_TOTAL_KEY), 0
+            ) + new.get(get_column_name(Database.EXPTIME_TOTAL_KEY), 0)
 
             cursor.execute(
                 f"""
@@ -636,19 +726,22 @@ class Database:
             cursor.execute(
                 f"""
                 INSERT INTO {self.SESSIONS_TABLE}
-                (start, end, filter, imagetyp, object, telescop, num_images, exptime_total, image_doc_id)
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                (start, end, filter, imagetyp, object, telescop, num_images, exptime_total, exptime, image_doc_id)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
                 (
-                    new[Database.START_KEY],
-                    new[Database.END_KEY],
-                    new[Database.FILTER_KEY],
-                    new[Database.IMAGETYP_KEY],
-                    new[Database.OBJECT_KEY],
-                    new.get(Database.TELESCOP_KEY, "unspecified"),
-                    new[Database.NUM_IMAGES_KEY],
-                    new[Database.EXPTIME_TOTAL_KEY],
-                    new.get(Database.IMAGE_DOC_KEY),
+                    new[get_column_name(Database.START_KEY)],
+                    new[get_column_name(Database.END_KEY)],
+                    new.get(get_column_name(Database.FILTER_KEY)),
+                    new[get_column_name(Database.IMAGETYP_KEY)],
+                    normalize_target_name(
+                        new.get(get_column_name(Database.OBJECT_KEY))
+                    ),
+                    new.get(get_column_name(Database.TELESCOP_KEY)),
+                    new[get_column_name(Database.NUM_IMAGES_KEY)],
+                    new[get_column_name(Database.EXPTIME_TOTAL_KEY)],
+                    new[get_column_name(Database.EXPTIME_KEY)],
+                    new[get_column_name(Database.IMAGE_DOC_KEY)],
                 ),
             )
 

starbash/defaults/starbash.toml

@@ -12,13 +12,31 @@ kind = "preferences"
 dark = ["dark", "darks"]
 flat = ["flat", "flats"]
 bias = ["bias", "biases"]
+light = ["light", "lights"]
 
 # file suffixes
-fit = ["fits", "fit"]
+fits = ["fits", "fit"]
 
 # filter names
-SiiOiii = ["SiiOiii", "SII-OIII", "S2-O3"]
-HaOiii = ["HaOiii", "HA-OIII", "Halpha-O3"]
+SiiOiii = ["SiiOiii", "S2O3"]
+HaOiii = ["HaOiii", "HaO3"]
+
+None = ["None"]
+
+# Passes SII 672.4nm and H-Beta 486.1nm lines
+# Capturing of the two main emission wavebands in the deep red and blue at the same time
+#
+# The ALP-T dual band 3.5nm SII&Hb filter is a dual narrowband filter, which lets the deep
+# red Sulfur-II 672.4nm and the blue Hydrogen-Beta 486.1nm lines through and is primarily
+# engineered for color cameras to assist astrophotographers taking deep sky images with
+# superior SNR(Signal to Noise Ratio). With an FWHM halfbandwidth designed at 3.5nm and
+# achieving an optical density (OD) of 4.5 on unwanted wavelengths, it works strongly in
+# blocking light pollution, moonlight, and airglow, leding to enhanced contrast in nebulae
+# images by effectively passing the SII and H-beta emission lines signal only.
+#
+# http://www.antliafilter.com/pd.jsp?fromColId=2&id=160#_pp=2_671
+SiiHb = ["SiiHb", "S2Hb"]
+
 
 # FIXME, somewhere here list default patterns which can be used to identify NINA, ASIAIR, SEESTAR
 # raw repo layouts

starbash/paths.py

@@ -7,19 +7,24 @@ app_author = "geeksville"
 dirs = PlatformDirs(app_name, app_author)
 config_dir = Path(dirs.user_config_dir)
 data_dir = Path(dirs.user_data_dir)
+documents_dir = Path(dirs.user_documents_dir) / "starbash"
 
 # These can be overridden for testing
 _override_config_dir: Path | None = None
 _override_data_dir: Path | None = None
+_override_documents_dir: Path | None = None
 
 
 def set_test_directories(
-    config_dir_override: Path | None = None, data_dir_override: Path | None = None
+    config_dir_override: Path | None = None,
+    data_dir_override: Path | None = None,
+    documents_dir_override: Path | None = None,
 ) -> None:
     """Set override directories for testing. Used by test fixtures to isolate test data."""
-    global _override_config_dir, _override_data_dir
+    global _override_config_dir, _override_data_dir, _override_documents_dir
     _override_config_dir = config_dir_override
     _override_data_dir = data_dir_override
+    _override_documents_dir = documents_dir_override
 
 
 def get_user_config_dir() -> Path:
@@ -36,3 +41,14 @@ def get_user_data_dir() -> Path:
     dir_to_use = _override_data_dir if _override_data_dir is not None else data_dir
     os.makedirs(dir_to_use, exist_ok=True)
     return dir_to_use
+
+
+def get_user_documents_dir() -> Path:
+    """Get the user documents directory. Returns test override if set, otherwise the real user directory."""
+    dir_to_use = (
+        _override_documents_dir
+        if _override_documents_dir is not None
+        else documents_dir
+    )
+    os.makedirs(dir_to_use, exist_ok=True)
+    return dir_to_use

starbash/recipes/master_bias/starbash.toml

@@ -10,13 +10,14 @@ author.email = "FIXMESiril?"
 [[stage]]
 
 description = "Generate master bias"
-disabled = false # FIXME, debugging later stuff
+# disabled = false # turn on to skip
 
 # Restrict processing of this stage to only if detected hardware was found for this session
 # For any camera
-auto.for-camera = []
+# auto.for-camera = []
 
-tool = "siril"
+tool.name = "siril"
+# tool.timeout = 15.0 # allow up to 15 seconds before we timeout and kill tool
 
 # or auto?
 # find the most recent raw fits for the current instrument (as of the time of session start)
@@ -25,16 +26,11 @@ input.type = "bias" # look in all raw repos, but look only for bias files
 
 # Look for files in input repos, finding them by using the "relative" tag they contain
 input.source = "repo"
+input.required = 2 # siril needs at least 2 frames to stack
+# old school paths also work (but are not recommended)
 # input.path = ".../from_astroboy/masters-raw/2025-09-09/BIAS/*.fit*"
-input.required = true # Is at least one input file required?  If true, we will skip running this stage entirely (with a warning)
 
-# make the following also work
-#
-#os.makedirs(os.path.dirname(output), exist_ok=True)
-#os.makedirs(os.path.dirname(process_dir), exist_ok=True)
-#frames = glob(f"{masters_raw}/{date}/BIAS/{date}_*.fit*")
-#siril_run_in_temp_dir(frames, ...
-when = "setup.masters" # run when master biases are regenerated
+when = "setup.master.bias" # run when master biases are regenerated
 
 # Based on the following definitions in the stage toml file...
 output.dest = "repo" # write to a particular repo
@@ -64,9 +60,9 @@ output.type = "master" # write output to the special masters repo
 
 script = '''
     # Convert Bias Frames to .fit files
-    link bias -out={process_dir}
+    link frames -out={process_dir}
     cd {process_dir}
 
-    # Stack Bias Frames to bias_stacked.fit
-    stack bias rej 3 3 -nonorm -out={output["base_path"]}
+    # Stack frames
+    stack frames rej 3 3 -nonorm -out={output["base_path"]}
     '''