brkraw 0.3.11__py3-none-any.whl → 0.5.0__py3-none-any.whl

brkraw/cli/commands/session.py

@@ -0,0 +1,371 @@
+from __future__ import annotations
+
+"""Session command to manage BrkRaw environment defaults."""
+
+import argparse
+import os
+from pathlib import Path
+from typing import Iterable, List, Tuple
+
+from brkraw.apps.loader import BrukerLoader
+
+
+def _format_export(name: str, value: str) -> str:
+    escaped = value.replace("\"", "\\\"")
+    return f'export {name}="{escaped}"'
+
+
+def _format_scan_ids(scan_ids: Iterable[int]) -> str:
+    return ",".join(str(sid) for sid in scan_ids)
+
+
+def _format_param_files(files: Iterable[str]) -> str:
+    return ",".join(str(item) for item in files)
+
+
+def cmd_session(args: argparse.Namespace) -> int:
+    handler = getattr(args, "session_func", None)
+    if handler is None:
+        args.parser.print_help()
+        return 2
+    return handler(args)
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    if (
+        not args.path
+        and not args.scan_id
+        and args.reco_id is None
+        and not args.param_key
+        and not args.param_file
+        and not args.convert_option
+    ):
+        parser = getattr(args, "parser", None)
+        if parser is not None:
+            print(_format_short_help(parser))
+        print("\nTip: run `brkraw init --shell-rc ~/.zshrc` (or ~/.bashrc)")
+        print("Then use `brkraw-set ...` and `brkraw-unset` in your shell.")
+        print("You can still use `eval \"$(brkraw session set ...)\"` directly.")
+        return 2
+    lines: List[str] = []
+    if args.path:
+        path = Path(args.path).expanduser()
+        if not path.exists():
+            print(f"error: path not found: {path}")
+            return 2
+        try:
+            BrukerLoader(path)
+        except Exception as exc:
+            print(f"error: failed to load dataset at {path}: {exc}")
+            return 2
+        lines.append(_format_export("BRKRAW_PATH", str(path.resolve())))
+    if args.scan_id:
+        lines.append(_format_export("BRKRAW_SCAN_ID", _format_scan_ids(args.scan_id)))
+    if args.reco_id is not None:
+        lines.append(_format_export("BRKRAW_RECO_ID", str(args.reco_id)))
+    if args.param_key:
+        lines.append(_format_export("BRKRAW_PARAM_KEY", args.param_key))
+    if args.param_file:
+        lines.append(_format_export("BRKRAW_PARAM_FILE", _format_param_files(args.param_file)))
+    if args.convert_option:
+        convert_items: List[str] = []
+        for item in args.convert_option:
+            if isinstance(item, list):
+                convert_items.extend(item)
+            else:
+                convert_items.append(item)
+        for key, value in _parse_convert_options(convert_items):
+            lines.append(_format_export(f"BRKRAW_CONVERT_{key}", value))
+    if lines:
+        print("\n".join(lines))
+    return 0
+
+
+def cmd_unset(args: argparse.Namespace) -> int:
+    base_vars = [
+        "BRKRAW_PATH",
+        "BRKRAW_SCAN_ID",
+        "BRKRAW_RECO_ID",
+        "BRKRAW_PARAM_KEY",
+        "BRKRAW_PARAM_FILE",
+    ]
+    convert_vars = [
+        "BRKRAW_CONVERT_OUTPUT",
+        "BRKRAW_CONVERT_PREFIX",
+        "BRKRAW_CONVERT_SCAN_ID",
+        "BRKRAW_CONVERT_RECO_ID",
+        "BRKRAW_CONVERT_SIDECAR",
+        "BRKRAW_CONVERT_CONTEXT_MAP",
+        "BRKRAW_CONVERT_SPACE",
+        "BRKRAW_CONVERT_COMPRESS",
+        "BRKRAW_CONVERT_FLIP_X",
+        "BRKRAW_CONVERT_FLATTEN_FG",
+        "BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE",
+        "BRKRAW_CONVERT_OVERRIDE_SUBJECT_POSE",
+        "BRKRAW_CONVERT_XYZ_UNITS",
+        "BRKRAW_CONVERT_T_UNITS",
+        "BRKRAW_CONVERT_HEADER",
+        "BRKRAW_CONVERT_FORMAT",
+    ]
+    targets: List[str] = []
+    if args.path:
+        targets.append("BRKRAW_PATH")
+    if args.scan_id:
+        targets.append("BRKRAW_SCAN_ID")
+    if args.reco_id:
+        targets.append("BRKRAW_RECO_ID")
+    if args.param_key:
+        targets.append("BRKRAW_PARAM_KEY")
+    if args.param_file:
+        targets.append("BRKRAW_PARAM_FILE")
+
+    if args.convert_option:
+        keys: List[str] = []
+        for item in args.convert_option:
+            if item is None or item == "*":
+                keys = ["*"]
+                break
+            keys.append(item)
+        if "*" in keys:
+            targets.extend(convert_vars)
+        else:
+            targets.extend(
+                [f"BRKRAW_CONVERT_{key.strip().upper().replace('-', '_')}" for key in keys]
+            )
+
+    if not targets:
+        targets = base_vars + convert_vars
+    print("unset " + " ".join(targets))
+    return 0
+
+
+def cmd_env(_: argparse.Namespace) -> int:
+    path = os.environ.get("BRKRAW_PATH")
+    scan_id = os.environ.get("BRKRAW_SCAN_ID")
+    reco_id = os.environ.get("BRKRAW_RECO_ID")
+    param_key = os.environ.get("BRKRAW_PARAM_KEY")
+    param_file = os.environ.get("BRKRAW_PARAM_FILE")
+    convert_output = os.environ.get("BRKRAW_CONVERT_OUTPUT")
+    convert_prefix = os.environ.get("BRKRAW_CONVERT_PREFIX")
+    convert_scan_id = os.environ.get("BRKRAW_CONVERT_SCAN_ID")
+    convert_reco_id = os.environ.get("BRKRAW_CONVERT_RECO_ID")
+    convert_sidecar = os.environ.get("BRKRAW_CONVERT_SIDECAR")
+    convert_context_map = os.environ.get("BRKRAW_CONVERT_CONTEXT_MAP")
+    convert_compress = os.environ.get("BRKRAW_CONVERT_COMPRESS")
+    convert_space = os.environ.get("BRKRAW_CONVERT_SPACE")
+    convert_flip_x = os.environ.get("BRKRAW_CONVERT_FLIP_X")
+    convert_flatten_fg = os.environ.get("BRKRAW_CONVERT_FLATTEN_FG")
+    convert_subject_type = os.environ.get("BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE")
+    convert_subject_pose = os.environ.get("BRKRAW_CONVERT_OVERRIDE_SUBJECT_POSE")
+    convert_xyz_units = os.environ.get("BRKRAW_CONVERT_XYZ_UNITS")
+    convert_t_units = os.environ.get("BRKRAW_CONVERT_T_UNITS")
+    convert_header = os.environ.get("BRKRAW_CONVERT_HEADER")
+    convert_format = os.environ.get("BRKRAW_CONVERT_FORMAT")
+    if (
+        path is None
+        and scan_id is None
+        and reco_id is None
+        and param_key is None
+        and param_file is None
+        and convert_output is None
+        and convert_prefix is None
+        and convert_scan_id is None
+        and convert_reco_id is None
+        and convert_sidecar is None
+        and convert_context_map is None
+        and convert_compress is None
+        and convert_space is None
+        and convert_flip_x is None
+        and convert_flatten_fg is None
+        and convert_subject_type is None
+        and convert_subject_pose is None
+        and convert_xyz_units is None
+        and convert_t_units is None
+        and convert_header is None
+        and convert_format is None
+    ):
+        print("(none)")
+        return 0
+    if path is not None:
+        print(f"BRKRAW_PATH={path}")
+    if scan_id is not None:
+        print(f"BRKRAW_SCAN_ID={scan_id}")
+    if reco_id is not None:
+        print(f"BRKRAW_RECO_ID={reco_id}")
+    if param_key is not None:
+        print(f"BRKRAW_PARAM_KEY={param_key}")
+    if param_file is not None:
+        print(f"BRKRAW_PARAM_FILE={param_file}")
+    if convert_output is not None:
+        print(f"BRKRAW_CONVERT_OUTPUT={convert_output}")
+    if convert_prefix is not None:
+        print(f"BRKRAW_CONVERT_PREFIX={convert_prefix}")
+    if convert_scan_id is not None:
+        print(f"BRKRAW_CONVERT_SCAN_ID={convert_scan_id}")
+    if convert_reco_id is not None:
+        print(f"BRKRAW_CONVERT_RECO_ID={convert_reco_id}")
+    if convert_sidecar is not None:
+        print(f"BRKRAW_CONVERT_SIDECAR={convert_sidecar}")
+    if convert_context_map is not None:
+        print(f"BRKRAW_CONVERT_CONTEXT_MAP={convert_context_map}")
+    if convert_space is not None:
+        print(f"BRKRAW_CONVERT_SPACE={convert_space}")
+    if convert_compress is not None:
+        print(f"BRKRAW_CONVERT_COMPRESS={convert_compress}")
+    if convert_flip_x is not None:
+        print(f"BRKRAW_CONVERT_FLIP_X={convert_flip_x}")
+    if convert_flatten_fg is not None:
+        print(f"BRKRAW_CONVERT_FLATTEN_FG={convert_flatten_fg}")
+    if convert_subject_type is not None:
+        print(f"BRKRAW_CONVERT_OVERRIDE_SUBJECT_TYPE={convert_subject_type}")
+    if convert_subject_pose is not None:
+        print(f"BRKRAW_CONVERT_OVERRIDE_SUBJECT_POSE={convert_subject_pose}")
+    if convert_xyz_units is not None:
+        print(f"BRKRAW_CONVERT_XYZ_UNITS={convert_xyz_units}")
+    if convert_t_units is not None:
+        print(f"BRKRAW_CONVERT_T_UNITS={convert_t_units}")
+    if convert_header is not None:
+        print(f"BRKRAW_CONVERT_HEADER={convert_header}")
+    if convert_format is not None:
+        print(f"BRKRAW_CONVERT_FORMAT={convert_format}")
+    return 0
+
+
+def _format_short_help(parser: argparse.ArgumentParser) -> str:
+    formatter = parser._get_formatter()
+    formatter.add_usage(parser.usage, parser._actions, parser._mutually_exclusive_groups)
+    for action_group in parser._action_groups:
+        formatter.start_section(action_group.title)
+        actions = [
+            action
+            for action in action_group._group_actions
+            if "-h" not in action.option_strings and "--help" not in action.option_strings
+        ]
+        formatter.add_arguments(actions)
+        formatter.end_section()
+    return formatter.format_help()
+
+
+def _parse_convert_options(items: List[str]) -> List[Tuple[str, str]]:
+    pairs: List[Tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"Invalid convert option (expected KEY=VALUE): {item}")
+        key, value = item.split("=", 1)
+        key = key.strip().upper().replace("-", "_")
+        if not key:
+            raise ValueError(f"Invalid convert option key in: {item}")
+        pairs.append((key, value.strip()))
+    return pairs
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:  # type: ignore[name-defined]
+    session_parser = subparsers.add_parser(
+        "session",
+        help="Manage BrkRaw environment defaults.",
+    )
+    session_parser.add_argument(
+        "--root",
+        help="Override config root directory (default: BRKRAW_CONFIG_HOME or ~/.brkraw).",
+    )
+    session_parser.set_defaults(func=cmd_session, parser=session_parser)
+    session_sub = session_parser.add_subparsers(dest="session_command")
+
+    set_parser = session_sub.add_parser(
+        "set",
+        help="Emit shell exports for BrkRaw environment defaults.",
+    )
+    set_parser.add_argument(
+        "-p",
+        "--path",
+        help="Default Bruker study path.",
+    )
+    set_parser.add_argument(
+        "-s",
+        "--scan-id",
+        nargs="*",
+        type=int,
+        help="Default scan id(s).",
+    )
+    set_parser.add_argument(
+        "-r",
+        "--reco-id",
+        type=int,
+        help="Default reco id.",
+    )
+    set_parser.add_argument(
+        "-k",
+        "--param-key",
+        help="Default parameter key for brkraw params.",
+    )
+    set_parser.add_argument(
+        "-f",
+        "--param-file",
+        nargs="*",
+        help="Default parameter file(s) for brkraw params.",
+    )
+    set_parser.add_argument(
+        "--convert-option",
+        action="append",
+        metavar="KEY=VALUE",
+        help=(
+            "Set BRKRAW_CONVERT_<OPTION> as KEY=VALUE (repeatable). "
+            "Keys: OUTPUT, PREFIX, SCAN_ID, RECO_ID, SIDECAR, CONTEXT_MAP, "
+            "COMPRESS, SPACE, FLIP_X, FLATTEN_FG, OVERRIDE_SUBJECT_TYPE, "
+            "OVERRIDE_SUBJECT_POSE, XYZ_UNITS, T_UNITS, HEADER, FORMAT."
+        ),
+    )
+    set_parser.set_defaults(session_func=cmd_set, parser=set_parser)
+
+    unset_parser = session_sub.add_parser(
+        "unset",
+        help="Emit shell unset commands for BrkRaw environment defaults.",
+    )
+    unset_parser.add_argument(
+        "-p",
+        "--path",
+        action="store_true",
+        help="Unset BRKRAW_PATH.",
+    )
+    unset_parser.add_argument(
+        "-s",
+        "--scan-id",
+        action="store_true",
+        help="Unset BRKRAW_SCAN_ID.",
+    )
+    unset_parser.add_argument(
+        "-r",
+        "--reco-id",
+        action="store_true",
+        help="Unset BRKRAW_RECO_ID.",
+    )
+    unset_parser.add_argument(
+        "-k",
+        "--param-key",
+        action="store_true",
+        help="Unset BRKRAW_PARAM_KEY.",
+    )
+    unset_parser.add_argument(
+        "-f",
+        "--param-file",
+        action="store_true",
+        help="Unset BRKRAW_PARAM_FILE.",
+    )
+    unset_parser.add_argument(
+        "--convert-option",
+        nargs="?",
+        action="append",
+        const="*",
+        metavar="KEY",
+        help=(
+            "Unset BRKRAW_CONVERT_<OPTION> by KEY (repeatable). "
+            "Use without KEY to unset all convert variables."
+        ),
+    )
+    unset_parser.set_defaults(session_func=cmd_unset)
+
+    env_parser = session_sub.add_parser(
+        "env",
+        help="Show current BrkRaw environment defaults.",
+    )
+    env_parser.set_defaults(session_func=cmd_env)

brkraw/cli/hook_args.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Mapping
+
+import yaml
+
+
+def merge_hook_args(
+    base: Mapping[str, Mapping[str, Any]],
+    override: Mapping[str, Mapping[str, Any]],
+) -> Dict[str, Dict[str, Any]]:
+    merged: Dict[str, Dict[str, Any]] = {}
+    for hook_name, values in base.items():
+        if not isinstance(hook_name, str) or not hook_name:
+            continue
+        if not isinstance(values, Mapping):
+            continue
+        merged[hook_name] = dict(values)
+    for hook_name, values in override.items():
+        if not isinstance(hook_name, str) or not hook_name:
+            continue
+        if not isinstance(values, Mapping):
+            continue
+        merged.setdefault(hook_name, {}).update(dict(values))
+    return merged
+
+
+def load_hook_args_yaml(paths: List[str]) -> Dict[str, Dict[str, Any]]:
+    """Load hook args mapping from YAML files.
+
+    Supported YAML formats:
+      - `{hooks: {hook_name: {key: value}}}`
+      - `{hook_name: {key: value}}`
+    """
+
+    merged: Dict[str, Dict[str, Any]] = {}
+
+    def normalize_doc(doc: Any, *, source: str) -> Dict[str, Dict[str, Any]]:
+        if doc is None:
+            return {}
+        hooks_obj = doc.get("hooks") if isinstance(doc, Mapping) else None
+        if hooks_obj is None and isinstance(doc, Mapping):
+            hooks_obj = doc
+        if not isinstance(hooks_obj, Mapping):
+            raise ValueError(f"Invalid hook args YAML in {source!r}: expected mapping.")
+
+        out: Dict[str, Dict[str, Any]] = {}
+        for hook_name, values in hooks_obj.items():
+            if not isinstance(hook_name, str) or not hook_name.strip():
+                continue
+            if values is None:
+                continue
+            if not isinstance(values, Mapping):
+                raise ValueError(
+                    f"Invalid hook args YAML in {source!r}: hook {hook_name!r} must map to a dict."
+                )
+            out[hook_name.strip()] = dict(values)
+        return out
+
+    for raw in paths:
+        source = raw.strip()
+        if not source:
+            continue
+        if source == "-":
+            doc = yaml.safe_load(sys.stdin.read())
+        else:
+            path = Path(source).expanduser()
+            if not path.exists():
+                raise ValueError(f"Hook args YAML not found: {source}")
+            doc = yaml.safe_load(path.read_text(encoding="utf-8"))
+        parsed = normalize_doc(doc, source=source)
+        merged = merge_hook_args(merged, parsed)
+
+    return merged
+
+
+__all__ = ["load_hook_args_yaml", "merge_hook_args"]
+

brkraw/cli/main.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import argparse
+from typing import Callable, List, Optional
+from ..core.entrypoints import list_entry_points as _iter_entry_points
+
+from brkraw import __version__
+from brkraw.core import config as config_core
+
+PLUGIN_GROUP = "brkraw.cli"
+
+
+def _register_entry_point_commands(
+    subparsers: argparse._SubParsersAction,  # type: ignore[name-defined]
+) -> None:
+    for ep in _iter_entry_points(PLUGIN_GROUP):
+        try:
+            register = ep.load()
+        except Exception as exc:  # noqa: BLE001 - best-effort plugin load
+            print(f"warning: failed to load entry point {ep.name!r}: {exc}")
+            continue
+        if not callable(register):
+            raise TypeError("entry point must be callable (register(subparsers)).")
+        register(subparsers)
+
+    preferred = [
+        "init",
+        "config",
+        "session",
+        "info",
+        "params",
+        "convert",
+        "convert-batch",
+        "prune",
+        "addon",
+        "hook",
+    ]
+    preferred_set = set(preferred)
+    ordered = [name for name in preferred if name in subparsers.choices]
+    ordered += [name for name in subparsers.choices if name not in preferred_set]
+    subparsers.choices = {name: subparsers.choices[name] for name in ordered}
+    choices_actions = getattr(subparsers, "_choices_actions", None)
+    if choices_actions:
+        action_map = {action.dest: action for action in choices_actions}
+        ordered_actions = [action_map[name] for name in ordered if name in action_map]
+        ordered_actions += [
+            action for action in choices_actions if action.dest not in ordered
+        ]
+        subparsers._choices_actions = ordered_actions  # type: ignore[attr-defined]
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    config_core.configure_logging()
+    parser = argparse.ArgumentParser(
+        prog="brkraw",
+        description="BrkRaw command-line interface.",
+    )
+    parser.add_argument(
+        "-v", "--version", action="version", version="%(prog)s v{}".format(__version__)
+    )
+
+    subparsers = parser.add_subparsers(
+        title="Sub-commands",
+        description=(
+            "Choose one of the sub-commands below. For details on a specific "
+            "command, run: brkraw <command> -h."
+        ),
+        dest="command",
+        metavar="command",
+    )
+
+    _register_entry_point_commands(subparsers)
+
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 2
+    func: Callable[[argparse.Namespace], int] = args.func
+    return func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

brkraw/cli/utils.py

@@ -0,0 +1,60 @@
+"""Formatting helpers for CLI-style output.
+
+Last updated: 2025-12-30
+"""
+
+from __future__ import annotations
+
+import itertools
+import logging
+import threading
+import time
+from contextlib import contextmanager
+from typing import Iterator, List
+
+from brkraw.apps.loader import BrukerLoader
+
+logger = logging.getLogger("brkraw")
+
+@contextmanager
+def spinner(prefix: str = "Loading") -> Iterator[None]:
+    """Display a simple CLI spinner while a block runs.
+
+    Args:
+        prefix: Text shown before the spinner glyph.
+
+    Yields:
+        None.
+    """
+    if logger.isEnabledFor(logging.DEBUG):
+        yield
+        return
+
+    stop_event = threading.Event()
+    seq = itertools.cycle("|/-\\")
+
+    def run() -> None:
+        while not stop_event.is_set():
+            print(f"\r{prefix} {next(seq)}", end="", flush=True)
+            time.sleep(0.08)
+
+    thread = threading.Thread(target=run, daemon=True)
+    thread.start()
+    try:
+        yield
+    finally:
+        stop_event.set()
+        thread.join()
+        print("\r" + " " * (len(prefix) + 2) + "\r", end="", flush=True)
+
+
+def load(path, *, prefix: str = "Loading") -> BrukerLoader:
+    """Load a Bruker dataset with a CLI spinner."""
+    with spinner(prefix):
+        return BrukerLoader(path)
+
+
+__all__ = ["spinner", "load"]
+
+def __dir__() -> List[str]:
+    return sorted(__all__)

brkraw/core/__init__.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from . import fs, jcamp, parameters, zip
+from .entrypoints import list_entry_points
+
+
+__all__ = [
+    'fs',
+    'jcamp', 
+    'parameters',
+    'zip',
+    'list_entry_points',
+    ]