basebandflow 0.0.1__tar.gz

basebandflow-0.0.1/.github/workflows/publish.yaml

@@ -0,0 +1,48 @@
+name: Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*' # Triggers when you run: git push origin v1.0
+
+jobs:
+  release-and-publish:
+    name: Build, Release, and Publish
+    runs-on: ubuntu-latest
+    
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publishing
+      contents: write  # Required to create a GitHub Release
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # IMPORTANT: Fetches all git tags and full history for setuptools-scm
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          draft: false
+          prerelease: false
+          files: dist/*
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

basebandflow-0.0.1/.github/workflows/update-docs.yaml

@@ -0,0 +1,50 @@
+name: Auto-Update CLI Documentation
+
+on:
+  push:
+    branches:
+      - main
+    # Only run if python CLI files or the readme itself change
+    paths:
+      - 'basebandflow/cli/**'
+      - 'README.md'
+      - 'pyproject.toml'
+
+jobs:
+  update-readme:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12' 
+
+      - name: Install Dependencies & Typer CLI
+        run: |
+          python -m pip install --upgrade pip
+          pip install "typer[cli]"
+          pip install -e . # Installs basebandflow to resolve local imports
+
+      - name: Generate CLI Reference File
+        run: |
+          typer basebandflow/cli/main.py utils docs --name bbflow --output CLI_REFERENCE.md
+
+      - name: Commit and Push Changes
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@://github.com"
+          
+          # Only stage and commit if CLI_REFERENCE.md actually changed
+          git add CLI_REFERENCE.md
+          if ! git diff --cached --quiet; then
+            git commit -m "docs: auto-update CLI reference documentation [skip ci]"
+            git push
+          else
+            echo "No documentation changes detected."
+          fi

basebandflow-0.0.1/.gitignore

@@ -0,0 +1,3 @@
+*egg-info
+.vscode/
+__pycache__

basebandflow-0.0.1/CLI_REFERENCE.md

@@ -0,0 +1,421 @@
+# `bbflow`
+
+Run the baseband pipeline on CANFAR
+
+**Usage**:
+
+```console
+$ bbflow [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--install-completion`: Install completion for the current shell.
+* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `version`: Show the bbflow version
+* `config`: Configuration of basebandflow (bbflow)
+* `containers`: Commands to manage CANFAR headless...
+* `history`: List recent launches, newest first
+* `launch`: Launch the baseband pipeline (containers +...
+* `login`: Log in to your CANFAR account
+* `tokens`: Manage CHIME/FRB API tokens
+* `workflow`: Workflow related commands
+
+## `bbflow version`
+
+Show the bbflow version
+
+**Usage**:
+
+```console
+$ bbflow version [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `bbflow config`
+
+Configuration of basebandflow (bbflow)
+
+**Usage**:
+
+```console
+$ bbflow config [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `init`: Initialize the configuration
+* `set`: Change a configuration parameter
+* `show`: Show the current configuration
+* `path`: Show where the configuration is saved
+
+### `bbflow config init`
+
+Initialize the configuration
+
+**Usage**:
+
+```console
+$ bbflow config init [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow config set`
+
+Change a configuration parameter
+
+**Usage**:
+
+```console
+$ bbflow config set [OPTIONS] {parameter}
+```
+
+**Arguments**:
+
+* `parameter`: Choose between username, baseband_path, refresh_timer to update the configuration  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow config show`
+
+Show the current configuration
+
+**Usage**:
+
+```console
+$ bbflow config show [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow config path`
+
+Show where the configuration is saved
+
+**Usage**:
+
+```console
+$ bbflow config path [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `bbflow containers`
+
+Commands to manage CANFAR headless containers/sessions
+
+**Usage**:
+
+```console
+$ bbflow containers [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `create`: Create a CANFAR container
+* `list`: List CANFAR headless containers
+* `delete`: Delete one CANFAR container
+* `prune`: Prune multiple CANFAR containers
+
+### `bbflow containers create`
+
+Create a CANFAR container
+
+**Usage**:
+
+```console
+$ bbflow containers create [OPTIONS] [session_type]
+```
+
+**Arguments**:
+
+* `session_type`: Type of session: datatrail, analysis, refinement, all
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow containers list`
+
+List CANFAR headless containers
+
+**Usage**:
+
+```console
+$ bbflow containers list [OPTIONS]
+```
+
+**Options**:
+
+* `-f, --filter <str>`: Type of session: datatrail, analysis, refinement, all
+* `--help`: Show this message and exit.
+
+### `bbflow containers delete`
+
+Delete one CANFAR container
+
+**Usage**:
+
+```console
+$ bbflow containers delete [OPTIONS] {session_id}
+```
+
+**Arguments**:
+
+* `session_id`: CANFAR session ID  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow containers prune`
+
+Prune multiple CANFAR containers
+
+**Usage**:
+
+```console
+$ bbflow containers prune [OPTIONS] [session_type]
+```
+
+**Arguments**:
+
+* `session_type`: Type of session: datatrail, analysis, refinement, all
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `bbflow history`
+
+List recent launches, newest first
+
+**Usage**:
+
+```console
+$ bbflow history [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `-e, --event <str>`: Only this event ID
+* `-n, --limit <int range>`: How many runs to show  [default: 10; x&gt;=1]
+* `-a, --all`: Include dry runs
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `show`: Show most recent launch for an event
+
+### `bbflow history show`
+
+Show most recent launch for an event
+
+**Usage**:
+
+```console
+$ bbflow history show [OPTIONS] {event_id}
+```
+
+**Arguments**:
+
+* `event_id`: Event ID used for the baseband pipeline  [required]
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `bbflow launch`
+
+Launch the baseband pipeline (containers + deployment)
+
+**Usage**:
+
+```console
+$ bbflow launch [OPTIONS] {event_id}
+```
+
+**Arguments**:
+
+* `event_id`: [required]
+
+**Options**:
+
+* `--dry-run`
+* `--help`: Show this message and exit.
+
+## `bbflow login`
+
+Log in to your CANFAR account
+
+**Usage**:
+
+```console
+$ bbflow login [OPTIONS]
+```
+
+**Options**:
+
+* `--check`: Report status only
+* `--help`: Show this message and exit.
+
+## `bbflow tokens`
+
+Manage CHIME/FRB API tokens
+
+**Usage**:
+
+```console
+$ bbflow tokens [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `path`: Show where CHIME/FRB tokens are saved
+* `status`: Report the status and lifetime of JWT tokens
+* `refresh`: Refresh CHIME/FRB tokens (requires...
+
+### `bbflow tokens path`
+
+Show where CHIME/FRB tokens are saved
+
+**Usage**:
+
+```console
+$ bbflow tokens path [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow tokens status`
+
+Report the status and lifetime of JWT tokens
+
+**Usage**:
+
+```console
+$ bbflow tokens status [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow tokens refresh`
+
+Refresh CHIME/FRB tokens (requires password input)
+
+**Usage**:
+
+```console
+$ bbflow tokens refresh [OPTIONS]
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+## `bbflow workflow`
+
+Workflow related commands
+
+**Usage**:
+
+```console
+$ bbflow workflow [OPTIONS] COMMAND [ARGS]...
+```
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+**Commands**:
+
+* `abort`: Abort the Workflow deployment
+* `status`: Loads the status of the Workflow deployment
+* `open`: Opens the Workflow page for the configuration
+
+### `bbflow workflow abort`
+
+Abort the Workflow deployment
+
+**Usage**:
+
+```console
+$ bbflow workflow abort [OPTIONS] [config_id]
+```
+
+**Arguments**:
+
+* `config_id`: Configuration ID from Workflow
+
+**Options**:
+
+* `--help`: Show this message and exit.
+
+### `bbflow workflow status`
+
+Loads the status of the Workflow deployment
+
+**Usage**:
+
+```console
+$ bbflow workflow status [OPTIONS] [event_id]
+```
+
+**Arguments**:
+
+* `event_id`: Event ID used for the baseband pipeline
+
+**Options**:
+
+* `--oneline / --no-oneline`: Oneline status  [default: no-oneline]
+* `--help`: Show this message and exit.
+
+### `bbflow workflow open`
+
+Opens the Workflow page for the configuration
+
+**Usage**:
+
+```console
+$ bbflow workflow open [OPTIONS] [event_id]
+```
+
+**Arguments**:
+
+* `event_id`: Event ID used for the baseband pipeline
+
+**Options**:
+
+* `--help`: Show this message and exit.

basebandflow-0.0.1/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: basebandflow
+Version: 0.0.1
+Requires-Python: >=3.12
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: jinja2
+Requires-Dist: pyyaml
+Requires-Dist: pydantic
+Requires-Dist: platformdirs
+Requires-Dist: canfar
+Requires-Dist: pyjwt
+Requires-Dist: pandas
+Requires-Dist: chime-frb-api
+Requires-Dist: nest_asyncio

basebandflow-0.0.1/README.md

@@ -0,0 +1,76 @@
+# 🌌 basebandflow
+
+A command-line interface to run the CHIME/FRB baseband pipeline on **CANFAR**.
+
+## 📦 Installation
+
+This project uses `pyproject.toml` to manage dependencies and expose the command-line executable.
+
+```bash
+# Clone the repository
+git clone https://github.com
+cd basebandflow
+
+# Install the package locally in editable mode (remove -e for normal install)
+pip install -e .
+```
+
+## 🛠️ Usage
+
+Once installed, you can launch the CLI using the executable defined in your `pyproject.toml` (typically `bbflow` or `basebandflow`—replace `bbflow` below with your actual entry point name):
+
+```bash
+bbflow [OPTIONS] COMMAND [ARGS]...
+```
+
+If you run the base command without any subcommands, it will automatically check your CANFAR login status and display an interactive banner menu:
+```bash
+bbflow
+```
+
+### Debug Mode
+If you encounter errors and need a full Python stack trace instead of a clean error message, set the debug environment variable:
+```bash
+export BBFLOW_DEBUG=1
+bbflow <command>
+```
+
+---
+
+## 📖 CLI Reference
+For a full list of all available commands, options, and flags, see the auto-generated [CLI Reference Guide](CLI_REFERENCE.md).
+
+
+<!-- ## 📖 CLI Reference
+
+The interface is broken down into several modular subcommands:
+
+### Global Options
+* `-h`, `--help`: Show the help message and exit.
+
+### Command Groups
+
+| Command Group | Description |
+| :--- | :--- |
+| **`config`** | Manage local CLI configurations and settings. |
+| **`containers`** | List, pull, or manage CANFAR pipeline containers. |
+| **`history`** | View historical logs and past pipeline runs. |
+| **`launch`** | Spin up and initiate a new baseband pipeline job. |
+| **`login`** | Authenticate with CANFAR services. |
+| **`tokens`** | Manage CHIME/FRB and CANFAR authentication tokens. |
+| **`workflow`** | Define, inspect, and track active workflow states. |
+
+> 💡 *To view detailed arguments and options for any group, run `bbflow <group> --help`.*
+
+> ⚠️ **More information about the commands in [CLI Reference](CLI_REFERENCE.md)** -->
+
+<!-- --- -->
+
+<!-- ## 🧪 Development
+
+To run the test suite or contribute to `basebandflow`:
+
+```bash
+pip install -e ".[test]"
+pytest
+``` -->

basebandflow-0.0.1/basebandflow/api/auth/__init__.py

@@ -0,0 +1,58 @@
+from datetime import timedelta
+
+from basebandflow.api.auth.canfar import is_logged_in
+from basebandflow.api.auth.tokens import (
+    load_tokens,
+    refresh_tokens,
+    token_time_remaining,
+    tokens_need_refresh,
+)
+from basebandflow.api.errors import InvalidTokens, NotLoggedIn, TokenRefreshFailed
+from basebandflow.api.settings import require_settings
+from basebandflow.models import TokenStatus
+from basebandflow.tools import require_tool
+
+
+def tokens_valid() -> bool:
+    settings = require_settings()
+    margin = timedelta(minutes=settings.token_refresh_timer)
+    access, _ = load_tokens()
+    return not tokens_need_refresh(access, margin)
+
+
+def refresh_and_verify() -> None:
+    """Refresh (prompts for a password), then confirm the result. Call from the CLI, not from launch()."""
+    refresh_tokens()
+    if not tokens_valid():
+        raise TokenRefreshFailed("Tokens are still expired after refresh.")
+
+
+def ensure_ready_for_launch() -> None:
+    require_tool("workflow")
+    logged_in = is_logged_in()
+    if logged_in is None:
+        raise NotLoggedIn(
+            "Couldn't reach CANFAR to verify your login. Check your connection and retry."
+        )
+    if not logged_in:
+        raise NotLoggedIn("Not logged in to CANFAR. Run `bbflow login`.")
+    if not tokens_valid():
+        raise InvalidTokens(
+            "CHIME/FRB tokens are expired or about to expire."
+        )  # no refresh here
+
+
+def _token_status(token: str | None, margin: timedelta) -> TokenStatus:
+    return TokenStatus(
+        present=bool(token),
+        remaining=token_time_remaining(token),
+        needs_refresh=tokens_need_refresh(token, margin),
+    )
+
+
+def check_tokens() -> tuple[TokenStatus, TokenStatus]:
+    settings = require_settings()
+    access, refresh = load_tokens()
+    return _token_status(
+        access, timedelta(minutes=settings.token_refresh_timer)
+    ), _token_status(refresh, timedelta(minutes=settings.token_refresh_timer))

basebandflow-0.0.1/basebandflow/api/auth/canfar.py

@@ -0,0 +1,24 @@
+from basebandflow import tools
+from basebandflow.api.errors import ToolNotFound
+
+
+def is_logged_in() -> bool | None:
+    """True/False, or None if it couldn't be verified (timeout)."""
+    try:
+        r = tools.canfar(
+            "ps",
+            stdin=tools.subprocess.DEVNULL,
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except ToolNotFound:
+        return False
+    except tools.subprocess.TimeoutExpired:
+        return None
+    return r.returncode == 0
+
+
+def login_interactive() -> int:  # inherits terminal, returns exit code
+    r = tools.canfar("login", "--force")
+    return r.returncode