starbash 0.1.8__tar.gz → 0.1.10__tar.gz

{starbash-0.1.8 → starbash-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: starbash
-Version: 0.1.8
+Version: 0.1.10
 Summary: A tool for automating/standardizing/sharing astrophotography workflows.
 License-File: LICENSE
 Author: Kevin Hester
@@ -20,7 +20,7 @@ Requires-Dist: tomlkit (>=0.13.3,<0.14.0)
 Requires-Dist: typer (>=0.20.0,<0.21.0)
 Description-Content-Type: text/markdown
 
-# Starbash
+# [Starbash](https://github.com/geeksville/starbash)
 
 <img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/img/icon.png" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
 
@@ -33,6 +33,7 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 * Automatic - with sensible defaults, that you can change as needed.
 * Easy - provides a 'seestar like' starting-point for autoprocessing all your sessions (by default).
 * Fast - even with large image repositories.  Automatic master bias and flat generation and reasonable defaults
+* Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...)
 * Sharable - you can share/use recipes for image preprocessing flows.
 
 (This project is currently 'alpha' and missing recipes for some workflows, but adding new recipes is easy and we're happy to help.  Please file a github issue if your images are not auto-processed and we'll work out a fix.)
@@ -67,7 +68,7 @@ See the current [TODO](TODO.md) file for work items.  I'll be looking for pre-al
 
 Currently the easiest way to install this command-line based tool is to install is via [pipx](https://pipx.pypa.io/stable/).  If you don't already have pipx and you have python installed, you can auto install it by running "pip install --user pipx."  If you don't have python installed see the pipx link for pipx installers for any OS.
 
-Once pipx is installed just run the following **two** commands (the sb --install-completion will make TAB auto-complete automatically complete sb options (for most platforms)):
+Once pipx is installed just run the following **two** commands (the sb --install-completion will make TAB auto-complete automatically complete sb options (for most platforms)).  Installing auto-complete is **highly** recommended because it makes entering starbash commands fast - by pressing the TAB key:
 
 ```
 ➜ pipx install starbash
@@ -88,10 +89,10 @@ FIXME - add getting started instructions (possibly with a screenshare video)
 ## Supported commands
 
 ### Repository Management
-- `sb repo [--verbose]` - List installed repos (use `-v` for details)
-- `sb repo add <filepath|URL>` - Add a repository
-- `sb repo remove <REPONUM>` - Remove the indicated repo from the repo list
-- `sb repo reindex [--force] [REPONUM]` - Reindex the specified repo (or all repos if none specified)
+- `sb repo list [--verbose]` - List installed repos (use `-v` for details)
+- `sb repo add [--master] [filepath|URL]` - Add a repository, optionally specifying the type
+- `sb repo remove <REPOURL>` - Remove the indicated repo from the repo list
+- `sb repo reindex [--force] <REPOURL>` - Reindex the specified repo (or all repos if none specified)
 
 ### User Preferences
 - `sb user name "Your Name"` - Set name for attribution in generated images
@@ -108,18 +109,19 @@ FIXME - add getting started instructions (possibly with a screenshare video)
 - `sb select date <after|before|between> <DATE> [DATE]` - Limit to sessions in the specified date range
 - `sb select export SESSIONNUM DESTDIR` - Export the images for indicated session number into the specified directory (or current directory if not specified).  If possible symbolic links are used, if not the files are copied.
 
-## Not yet supported commands
-
-### Setup & Configuration
+### Selection information
 - `sb info` - Show user preferences location and other app info
 - `sb info target` - List targets (filtered based on the current selection)
 - `sb info telescope` - List instruments (filtered based on the current selection)
 - `sb info filter` - List all filters found in current selection
+- `sb info master [KIND]` - List all precalculated master images (darks, biases, flats). Optional KIND argument to filter by image type (e.g., BIAS, DARK, FLAT)
+
+## Not yet supported commands
 
 ### Export & Processing
-- `sb process siril` - Generate Siril directory tree and run Siril GUI
-- `sb process auto` - Automatic processing
-- `sb process masters` - Generate master flats, darks, and biases from available raw frames
+- `sb process siril [--run] SESSIONNUM DESTDIR` - Generate Siril directory tree and optionally run Siril GUI
+- `sb process auto [SESSIONNUM]` - Automatic processing.  If session # is specified process only that session, otherwise all selected sessions will be processed
+- `sb process masters` - Generate master flats, darks, and biases from available raw frames in the current selection
 
 ## Supported tools (now)
 
@@ -138,3 +140,8 @@ We try to make this project useful and friendly.  If you find problems please fi
 We accept pull-requests and enjoy discussing possible new development directions via github issues.  If you might want to work on this, just describe what your interests are and we can talk about how to get it merged.
 
 Project members can access crash reports [here](https://geeksville.sentry.io/insights/projects/starbash/?project=4510264204132352).
+
+## License
+
+Copyright 2025 Kevin Hester, kevinh@geeksville.com.
+Licensed under the [GPL v3](LICENSE)

{starbash-0.1.8 → starbash-0.1.10}/README.md

@@ -1,4 +1,4 @@
-# Starbash
+# [Starbash](https://github.com/geeksville/starbash)
 
 <img src="https://raw.githubusercontent.com/geeksville/starbash/refs/heads/main/img/icon.png" alt="Starbash: Astrophotography workflows simplified" width="30%" align="right" style="margin-bottom: 20px;">
 
@@ -11,6 +11,7 @@ A tool for automating/standardizing/sharing astrophotography workflows.
 * Automatic - with sensible defaults, that you can change as needed.
 * Easy - provides a 'seestar like' starting-point for autoprocessing all your sessions (by default).
 * Fast - even with large image repositories.  Automatic master bias and flat generation and reasonable defaults
+* Multi-session - by default.  So your workflows can stack from multiple nights (and still use the correct flats etc...)
 * Sharable - you can share/use recipes for image preprocessing flows.
 
 (This project is currently 'alpha' and missing recipes for some workflows, but adding new recipes is easy and we're happy to help.  Please file a github issue if your images are not auto-processed and we'll work out a fix.)
@@ -45,7 +46,7 @@ See the current [TODO](TODO.md) file for work items.  I'll be looking for pre-al
 
 Currently the easiest way to install this command-line based tool is to install is via [pipx](https://pipx.pypa.io/stable/).  If you don't already have pipx and you have python installed, you can auto install it by running "pip install --user pipx."  If you don't have python installed see the pipx link for pipx installers for any OS.
 
-Once pipx is installed just run the following **two** commands (the sb --install-completion will make TAB auto-complete automatically complete sb options (for most platforms)):
+Once pipx is installed just run the following **two** commands (the sb --install-completion will make TAB auto-complete automatically complete sb options (for most platforms)).  Installing auto-complete is **highly** recommended because it makes entering starbash commands fast - by pressing the TAB key:
 
 ```
 ➜ pipx install starbash
@@ -66,10 +67,10 @@ FIXME - add getting started instructions (possibly with a screenshare video)
 ## Supported commands
 
 ### Repository Management
-- `sb repo [--verbose]` - List installed repos (use `-v` for details)
-- `sb repo add <filepath|URL>` - Add a repository
-- `sb repo remove <REPONUM>` - Remove the indicated repo from the repo list
-- `sb repo reindex [--force] [REPONUM]` - Reindex the specified repo (or all repos if none specified)
+- `sb repo list [--verbose]` - List installed repos (use `-v` for details)
+- `sb repo add [--master] [filepath|URL]` - Add a repository, optionally specifying the type
+- `sb repo remove <REPOURL>` - Remove the indicated repo from the repo list
+- `sb repo reindex [--force] <REPOURL>` - Reindex the specified repo (or all repos if none specified)
 
 ### User Preferences
 - `sb user name "Your Name"` - Set name for attribution in generated images
@@ -86,18 +87,19 @@ FIXME - add getting started instructions (possibly with a screenshare video)
 - `sb select date <after|before|between> <DATE> [DATE]` - Limit to sessions in the specified date range
 - `sb select export SESSIONNUM DESTDIR` - Export the images for indicated session number into the specified directory (or current directory if not specified).  If possible symbolic links are used, if not the files are copied.
 
-## Not yet supported commands
-
-### Setup & Configuration
+### Selection information
 - `sb info` - Show user preferences location and other app info
 - `sb info target` - List targets (filtered based on the current selection)
 - `sb info telescope` - List instruments (filtered based on the current selection)
 - `sb info filter` - List all filters found in current selection
+- `sb info master [KIND]` - List all precalculated master images (darks, biases, flats). Optional KIND argument to filter by image type (e.g., BIAS, DARK, FLAT)
+
+## Not yet supported commands
 
 ### Export & Processing
-- `sb process siril` - Generate Siril directory tree and run Siril GUI
-- `sb process auto` - Automatic processing
-- `sb process masters` - Generate master flats, darks, and biases from available raw frames
+- `sb process siril [--run] SESSIONNUM DESTDIR` - Generate Siril directory tree and optionally run Siril GUI
+- `sb process auto [SESSIONNUM]` - Automatic processing.  If session # is specified process only that session, otherwise all selected sessions will be processed
+- `sb process masters` - Generate master flats, darks, and biases from available raw frames in the current selection
 
 ## Supported tools (now)
 
@@ -115,4 +117,9 @@ FIXME - add getting started instructions (possibly with a screenshare video)
 We try to make this project useful and friendly.  If you find problems please file a github issue.
 We accept pull-requests and enjoy discussing possible new development directions via github issues.  If you might want to work on this, just describe what your interests are and we can talk about how to get it merged.
 
-Project members can access crash reports [here](https://geeksville.sentry.io/insights/projects/starbash/?project=4510264204132352).
+Project members can access crash reports [here](https://geeksville.sentry.io/insights/projects/starbash/?project=4510264204132352).
+
+## License
+
+Copyright 2025 Kevin Hester, kevinh@geeksville.com.
+Licensed under the [GPL v3](LICENSE)

{starbash-0.1.8 → starbash-0.1.10}/pyproject.toml

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

{starbash-0.1.8 → starbash-0.1.10}/src/repo/__init__.py

@@ -3,5 +3,6 @@ The repo package handles finding, loading and searching starbash repositories.
 """
 
 from .manager import RepoManager
+from .repo import Repo, repo_suffix, REPO_REF
 
-__all__ = ["RepoManager"]
+__all__ = ["RepoManager", "Repo", "repo_suffix", "REPO_REF"]

starbash-0.1.10/src/repo/manager.py

@@ -0,0 +1,144 @@
+"""
+Manages the repository of processing recipes and configurations.
+"""
+
+from __future__ import annotations
+import logging
+from pathlib import Path
+from importlib import resources
+from typing import Any
+
+import tomlkit
+from tomlkit.toml_file import TOMLFile
+from tomlkit.items import AoT
+from multidict import MultiDict
+from repo.repo import Repo
+
+
+class RepoManager:
+    """
+    Manages the collection of starbash repositories.
+
+    This class is responsible for finding, loading, and providing an API
+    for searching through known repositories defined in TOML configuration
+    files (like appdefaults.sb.toml).
+    """
+
+    def __init__(self):
+        """
+        Initializes the RepoManager by loading the application default repos.
+        """
+        self.repos = []
+
+        # We expose the app default preferences as a special root repo with a private URL
+        # root_repo = Repo(self, "pkg://starbash-defaults", config=app_defaults)
+        # self.repos.append(root_repo)
+
+        # Most users will just want to read from merged
+        self.merged = MultiDict()
+
+    @property
+    def regular_repos(self) -> list[Repo]:
+        "We exclude certain repo types (preferences, recipe) from the list of repos users care about."
+        return [
+            r
+            for r in self.repos
+            if r.kind() not in ("preferences") and not r.is_scheme("pkg")
+        ]
+
+    def add_repo(self, url: str) -> Repo:
+        logging.debug(f"Adding repo: {url}")
+        r = Repo(self, url)
+        self.repos.append(r)
+
+        # FIXME, generate the merged dict lazily
+        self._add_merged(r)
+
+        # if this new repo has sub-repos, add them too
+        r.add_by_repo_refs()
+
+        return r
+
+    def get_repo_by_url(self, url: str) -> Repo | None:
+        """
+        Retrieves a repository by its URL.
+
+        Args:
+            url: The URL of the repository to retrieve.
+
+        Returns:
+            The Repo instance with the matching URL, or None if not found.
+        """
+        for repo in self.repos:
+            if repo.url == url:
+                return repo
+        return None
+
+    def get_repo_by_kind(self, kind: str) -> Repo | None:
+        """
+        Retrieves the first repository matching the specified kind.
+
+        Args:
+            kind: The kind of repository to search for (e.g., "recipe", "preferences").
+
+        Returns:
+            The first Repo instance matching the kind, or None if not found.
+        """
+        for repo in self.repos:
+            if repo.kind() == kind:
+                return repo
+        return None
+
+    def get(self, key: str, default=None):
+        """
+        Searches for a key across all repositories and returns the first value found.
+        The search is performed in reverse order of repository loading, so the
+        most recently added repositories have precedence.
+
+        Args:
+            key: The dot-separated key to search for (e.g., "repo.kind").
+            default: The value to return if the key is not found in any repo.
+
+        Returns:
+            The found value or the default.
+        """
+        # Iterate in reverse to give precedence to later-loaded repos
+        for repo in reversed(self.repos):
+            value = repo.get(key)
+            if value is not None:
+                return value
+
+        return default
+
+    def dump(self):
+        """
+        Prints a detailed, multi-line description of the combined top-level keys
+        and values from all repositories, using a MultiDict for aggregation.
+        This is useful for debugging and inspecting the consolidated configuration.
+        """
+
+        combined_config = self.merged
+        logging.info("RepoManager Dump")
+        for key, value in combined_config.items():
+            # tomlkit.items() can return complex types (e.g., ArrayOfTables, Table)
+            # For a debug dump, a simple string representation is usually sufficient.
+            logging.info(f"  %s: %s", key, value)
+
+    def _add_merged(self, repo: Repo) -> None:
+        for key, value in repo.config.items():
+            # if the toml object is an AoT type, monkey patch each element in the array instead
+            if isinstance(value, AoT):
+                for v in value:
+                    setattr(v, "source", repo)
+                else:
+                    # We monkey patch source into any object that came from a repo, so that users can
+                    # find the source repo (for attribution, URL relative resolution, whatever...)
+                    setattr(value, "source", repo)
+
+            self.merged.add(key, value)
+
+    def __str__(self):
+        lines = [f"RepoManager with {len(self.repos)} repositories:"]
+        for i, repo in enumerate(self.repos):
+            lines.append(f"  [{i}] {repo.url}")
+        return "\n".join(lines)

starbash-0.1.8/src/repo/manager.py → starbash-0.1.10/src/repo/repo.py

@@ -1,18 +1,16 @@
-"""
-Manages the repository of processing recipes and configurations.
-"""
-
 from __future__ import annotations
 import logging
 from pathlib import Path
 from importlib import resources
-from typing import Any
+from typing import Any, TYPE_CHECKING
 
 import tomlkit
 from tomlkit.toml_file import TOMLFile
 from tomlkit.items import AoT
 from multidict import MultiDict
 
+if TYPE_CHECKING:
+    from repo.manager import RepoManager
 
 repo_suffix = "starbash.toml"
 
@@ -39,7 +37,7 @@ class Repo:
 
         Example: "Repo(kind=recipe, local=True, url=file:///path/to/repo)"
         """
-        return f"Repo(kind={self.kind}, url={self.url})"
+        return f"Repo(kind={self.kind()}, url={self.url})"
 
     __repr__ = __str__
 
@@ -53,14 +51,14 @@ class Repo:
         c = self.get("repo.kind", unknown_kind)
         return str(c)
 
-    def add_repo_ref(self, dir: str) -> Repo | None:
+    def add_repo_ref(self, dir: Path) -> Repo | None:
         """
         Adds a new repo-ref to this repository's configuration.
         if new returns the newly added Repo object, if already exists returns None"""
 
         # if dir is not absolute, we need to resolve it relative to the cwd
-        if not Path(dir).is_absolute():
-            dir = str((Path.cwd() / dir).resolve())
+        if not dir.is_absolute():
+            dir = (Path.cwd() / dir).resolve()
 
         # Add the ref to this repo
         aot = self.config.get(REPO_REF, None)
@@ -72,11 +70,11 @@ class Repo:
             raise ValueError(f"repo-ref in {self.url} is not an array")
 
         for t in aot:
-            if "dir" in t and t["dir"] == dir:
+            if "dir" in t and t["dir"] == str(dir):
                 logging.warning(f"Repo ref {dir} already exists - ignoring.")
                 return None  # already exists
 
-        ref = {"dir": dir}
+        ref = {"dir": str(dir)}
         aot.append(ref)
 
         # Also add the repo to the manager
@@ -156,22 +154,22 @@ class Repo:
         for ref in repo_refs:
             self.add_from_ref(ref)
 
-    def _read_file(self, filepath: str) -> str:
+    def resolve_path(self, filepath: str) -> Path:
         """
-        Read a filepath relative to the base of this repo. Return the contents in a string.
+        Resolve a filepath relative to the base of this repo.
 
         Args:
             filepath: The path to the file, relative to the repository root.
 
         Returns:
-            The content of the file as a string.
+            The resolved Path object.
         """
         base_path = self.get_path()
         if base_path is None:
-            raise ValueError("Cannot read files from non-local repositories")
+            raise ValueError("Cannot resolve filepaths for non-local repositories")
         target_path = (base_path / filepath).resolve()
 
-        # Security check to prevent reading files outside the repo directory.
+        # Security check to prevent accessing files outside the repo directory.
         # FIXME SECURITY - temporarily disabled because I want to let file urls say things like ~/foo.
         # it would false trigger if user homedir path has a symlink in it (such as /home -> /var/home)
         #   base_path = PosixPath('/home/kevinh/.config/starbash')                   │                                                                                          │
@@ -180,7 +178,21 @@ class Repo:
         #   target_path = PosixPath('/var/home/kevinh/.config/starbash/starbash.toml')
         #
         # if base_path not in target_path.parents and target_path != base_path:
-        #    raise PermissionError("Attempted to read file outside of repository")
+        #    raise PermissionError("Attempted to access file outside of repository")
+
+        return target_path
+
+    def _read_file(self, filepath: str) -> str:
+        """
+        Read a filepath relative to the base of this repo. Return the contents in a string.
+
+        Args:
+            filepath: The path to the file, relative to the repository root.
+
+        Returns:
+            The content of the file as a string.
+        """
+        target_path = self.resolve_path(filepath)
 
         return target_path.read_text()
 
@@ -280,102 +292,3 @@ class Repo:
 
         # Set the final value
         current[keys[-1]] = value
-
-
-class RepoManager:
-    """
-    Manages the collection of starbash repositories.
-
-    This class is responsible for finding, loading, and providing an API
-    for searching through known repositories defined in TOML configuration
-    files (like appdefaults.sb.toml).
-    """
-
-    def __init__(self):
-        """
-        Initializes the RepoManager by loading the application default repos.
-        """
-        self.repos = []
-
-        # We expose the app default preferences as a special root repo with a private URL
-        # root_repo = Repo(self, "pkg://starbash-defaults", config=app_defaults)
-        # self.repos.append(root_repo)
-
-        # Most users will just want to read from merged
-        self.merged = MultiDict()
-
-    @property
-    def regular_repos(self) -> list[Repo]:
-        "We exclude certain repo types (preferences, recipe) from the list of repos users care about."
-        return [
-            r
-            for r in self.repos
-            if r.kind() not in ("preferences") and not r.is_scheme("pkg")
-        ]
-
-    def add_repo(self, url: str) -> Repo:
-        logging.debug(f"Adding repo: {url}")
-        r = Repo(self, url)
-        self.repos.append(r)
-
-        # FIXME, generate the merged dict lazily
-        self._add_merged(r)
-
-        # if this new repo has sub-repos, add them too
-        r.add_by_repo_refs()
-
-        return r
-
-    def get(self, key: str, default=None):
-        """
-        Searches for a key across all repositories and returns the first value found.
-        The search is performed in reverse order of repository loading, so the
-        most recently added repositories have precedence.
-
-        Args:
-            key: The dot-separated key to search for (e.g., "repo.kind").
-            default: The value to return if the key is not found in any repo.
-
-        Returns:
-            The found value or the default.
-        """
-        # Iterate in reverse to give precedence to later-loaded repos
-        for repo in reversed(self.repos):
-            value = repo.get(key)
-            if value is not None:
-                return value
-
-        return default
-
-    def dump(self):
-        """
-        Prints a detailed, multi-line description of the combined top-level keys
-        and values from all repositories, using a MultiDict for aggregation.
-        This is useful for debugging and inspecting the consolidated configuration.
-        """
-
-        combined_config = self.merged
-        logging.info("RepoManager Dump")
-        for key, value in combined_config.items():
-            # tomlkit.items() can return complex types (e.g., ArrayOfTables, Table)
-            # For a debug dump, a simple string representation is usually sufficient.
-            logging.info(f"  %s: %s", key, value)
-
-    def _add_merged(self, repo: Repo) -> None:
-        for key, value in repo.config.items():
-            # if the toml object is an AoT type, monkey patch each element in the array instead
-            if isinstance(value, AoT):
-                for v in value:
-                    setattr(v, "source", repo)
-                else:
-                    # We monkey patch source into any object that came from a repo, so that users can
-                    # find the source repo (for attribution, URL relative resolution, whatever...)
-                    setattr(value, "source", repo)
-
-            self.merged.add(key, value)
-
-    def __str__(self):
-        lines = [f"RepoManager with {len(self.repos)} repositories:"]
-        for i, repo in enumerate(self.repos):
-            lines.append(f"  [{i}] {repo.url}")
-        return "\n".join(lines)

{starbash-0.1.8 → starbash-0.1.10}/src/starbash/__init__.py

@@ -1,5 +1,7 @@
+import datetime
 import logging
 import os
+from datetime import datetime
 
 from .database import Database  # re-export for convenience
 from rich.console import Console
@@ -15,4 +17,22 @@ console = Console(
 # Global variable for log filter level (can be changed via --debug flag)
 log_filter_level = logging.INFO
 
+
+def to_shortdate(date_iso: str) -> str:
+    """Convert ISO UTC datetime string to local short date string (YYYY-MM-DD).
+
+    Args:
+        date_iso: ISO format datetime string (e.g., "2023-10-15T14:30:00Z")
+
+    Returns:
+        Short date string in YYYY-MM-DD format
+    """
+    try:
+        dt_utc = datetime.fromisoformat(date_iso)
+        dt_local = dt_utc.astimezone()
+        return dt_local.strftime("%Y-%m-%d")
+    except (ValueError, TypeError):
+        return date_iso
+
+
 __all__ = ["Database"]

starbash-0.1.10/src/starbash/aliases.py

@@ -0,0 +1,100 @@
+import string
+
+
+_translator = str.maketrans("", "", string.punctuation + string.whitespace)
+
+
+def normalize_target_name(name: str | None) -> str | None:
+    """Converts a target name to an any filesystem-safe format by removing spaces"""
+    if name is None:
+        return None
+    return name.replace(" ", "").lower()
+
+
+def pre_normalize(name: str) -> str:
+    """Pre-normalize a name by removing all whitespace and punctuation, and converting to lowercase.
+
+    Args:
+        name: The name to pre-normalize.
+
+    Returns:
+        Normalized string with only alphanumeric characters in lowercase.
+    """
+    # Create translation table that removes all punctuation and whitespace
+    return name.lower().translate(_translator)
+
+
+class UnrecognizedAliasError(ValueError):
+    """Exception raised when an unrecognized alias is encountered during normalization."""
+
+    pass
+
+
+class Aliases:
+    def __init__(self, alias_dict: dict[str, list[str]]):
+        """Initialize the Aliases object with a dictionary mapping keys to their alias lists.
+
+        The alias_dict structure follows the TOML format:
+        - Keys are reference names used in code (e.g., "dark", "flat", "bias", "fits", "SiiOiii", "HaOiii")
+        - Values are lists of aliases where the FIRST item is the canonical/preferred name
+        - The dictionary key may or may not match the canonical name
+
+        Example from TOML:
+            [aliases]
+            dark = ["dark", "darks"]           # key "dark" -> canonical "dark"
+            flat = ["flat", "flats"]           # key "flat" -> canonical "flat"
+            SiiOiii = ["SiiOiii", "SII-OIII", "S2-O3"]  # key "SiiOiii" -> canonical "SiiOiii"
+        """
+        self.alias_dict = alias_dict
+        self.reverse_dict = {}
+
+        # Build reverse lookup: any alias variant maps to canonical name
+        for _key, aliases in alias_dict.items():
+            if not aliases:
+                continue
+            # The first item in the list is ALWAYS the canonical/preferred form
+            canonical = aliases[0]
+            for alias in aliases:
+                # Map each alias (case-insensitive) to the canonical form (first in list)
+                # Also remove spaces, hypens and underscores when matching for normalization
+                self.reverse_dict[pre_normalize(alias)] = canonical
+
+    def get(self, name: str) -> list[str] | None:
+        """Get the list of aliases for a given key name.
+
+        Args:
+            name: The key name to look up (as used in code/TOML)
+
+        Returns:
+            List of all aliases for this key, or None if not found.
+            The first item in the returned list is the canonical form.
+        """
+        return self.alias_dict.get(name)
+
+    def normalize(self, name: str) -> str:
+        """Normalize a name to its canonical form using aliases.
+
+        This performs case-insensitive matching to find the canonical form.
+        The canonical form is the first item in the alias list from the TOML.
+
+        Args:
+            name: The name to normalize (e.g., "darks", "FLAT", "HA-OIII")
+
+        Returns:
+            The canonical/preferred form (e.g., "dark", "flat", "HaOiii"), or None if not found
+
+        Examples:
+            normalize("darks") -> "dark"
+            normalize("FLAT") -> "flat"
+            normalize("HA-OIII") -> "HaOiii"
+        """
+        result = self.reverse_dict.get(pre_normalize(name))
+        if not result:
+            raise UnrecognizedAliasError(f"'{name}' not found in aliases.")
+        return result
+
+    def equals(self, name1: str, name2: str) -> bool:
+        """Check if two names are equivalent based on aliases."""
+        norm1 = self.normalize(name1.strip())
+        norm2 = self.normalize(name2.strip())
+        return norm1 == norm2