brkraw 0.5.2__tar.gz → 0.5.5__tar.gz

{brkraw-0.5.2 → brkraw-0.5.5}/.github/workflows/ci.yml

@@ -2,7 +2,17 @@ name: CI
 
 on:
   push:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/ci.yml"
   pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/ci.yml"
 
 jobs:
   pytest:

{brkraw-0.5.2 → brkraw-0.5.5}/.github/workflows/publish.yml

@@ -12,6 +12,16 @@ on:
         description: "Tag to publish (optional, e.g. v1.2.3)"
         required: false
         type: string
+  workflow_call:
+    inputs:
+      target:
+        description: "Publish target"
+        type: string
+        default: testpypi
+      tag:
+        description: "Tag to publish (optional, e.g. v1.2.3)"
+        required: false
+        type: string
 
 permissions:
   contents: read

{brkraw-0.5.2 → brkraw-0.5.5}/.github/workflows/release.yml

@@ -19,6 +19,10 @@ jobs:
   release:
     if: ${{ github.repository == 'BrkRaw/brkraw' }}
     runs-on: ubuntu-latest
+    outputs:
+      prerelease: ${{ steps.prerelease.outputs.value }}
+      tag: ${{ steps.tag.outputs.value }}
+      zenodo_success: ${{ steps.zenodo.outcome == 'success' }}
     steps:
       - name: Resolve tag
         id: tag
@@ -127,3 +131,38 @@ jobs:
           if url:
               print(f"Created discussion: {url}")
           PY
+      - name: Checkout main for Zenodo badge update
+        uses: actions/checkout@v4
+        with:
+          ref: main
+      - name: Set up git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Update Zenodo badge
+        id: zenodo
+        if: ${{ steps.prerelease.outputs.value != 'true' }}
+        continue-on-error: true
+        run: |
+          for i in $(seq 1 10); do
+            echo "Zenodo badge update attempt $i/10"
+            python3 scripts/update_zenodo_badge.py --up-to-date-exit-code 2
+            exit_code=$?
+            if [ "$exit_code" -eq 0 ]; then
+              echo "Zenodo badge updated."
+              exit 0
+            fi
+            if [ "$exit_code" -ne 2 ]; then
+              exit "$exit_code"
+            fi
+            sleep 60
+          done
+          echo "Zenodo badge still up to date after 10 attempts; giving up."
+
+  publish:
+    if: ${{ github.repository == 'BrkRaw/brkraw' && (needs.release.outputs.prerelease == 'true' || needs.release.outputs.zenodo_success == 'true') }}
+    needs: [release]
+    uses: ./.github/workflows/publish.yml
+    with:
+      target: ${{ needs.release.outputs.prerelease == 'true' && 'testpypi' || 'pypi' }}
+      tag: ${{ needs.release.outputs.tag }}

brkraw-0.5.5/.github/workflows/release_on_merge.yml

@@ -0,0 +1,118 @@
+name: Release On Merge
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  tag_release:
+    if: ${{ github.repository == 'BrkRaw/brkraw' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Detect version change
+        id: version
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.sha }}
+          BEFORE: ${{ github.event.before }}
+        run: |
+          set -euo pipefail
+
+          # Default outputs
+          echo "changed=false" >> "$GITHUB_OUTPUT"
+
+          # Only proceed for merge commits ("Merge pull request ...")
+          if [[ "${{ github.event.head_commit.message }}" != Merge\ pull\ request* ]]; then
+            echo "Not a merge commit. Skipping." 
+            exit 0
+          fi
+
+          # Find the PR associated with this merge commit and ensure it has the 'release' label.
+          api="https://api.github.com/repos/${REPO}/commits/${SHA}/pulls"
+          pr_json=$(curl -fsSL \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            -H "Accept: application/vnd.github.groot-preview+json" \
+            "$api" || true)
+          export PR_JSON="$pr_json"
+
+          pr_number=$(python3 - <<'PY'
+          import json, os
+          s = os.environ.get('PR_JSON','')
+          if not s.strip():
+            print('')
+            raise SystemExit(0)
+          data = json.loads(s)
+          if isinstance(data, list) and data:
+            print(data[0].get('number',''))
+          else:
+            print('')
+          PY
+          )
+
+          if [[ -z "${pr_number}" ]]; then
+            echo "No PR associated with ${SHA}. Skipping." 
+            exit 0
+          fi
+
+          labels_api="https://api.github.com/repos/${REPO}/issues/${pr_number}/labels"
+          labels_json=$(curl -fsSL \
+            -H "Authorization: Bearer ${GH_TOKEN}" \
+            -H "Accept: application/vnd.github+json" \
+            "$labels_api")
+          export LABELS_JSON="$labels_json"
+
+          has_release=$(python3 - <<'PY'
+          import json, os
+          labels = json.loads(os.environ['LABELS_JSON'])
+          names = {l.get('name','') for l in labels if isinstance(l, dict)}
+          print('true' if 'release' in names else 'false')
+          PY
+          )
+
+          if [[ "${has_release}" != "true" ]]; then
+            echo "PR #${pr_number} does not have 'release' label. Skipping." 
+            exit 0
+          fi
+
+          # Check whether version file changed in this push
+          if ! git diff --name-only "${BEFORE}" "${SHA}" | grep -q '^src/brkraw/__init__.py$'; then
+            echo "src/brkraw/__init__.py not changed. Skipping." 
+            exit 0
+          fi
+
+          version=$(python3 - <<'PY'
+          import re
+          from pathlib import Path
+
+          text = Path("src/brkraw/__init__.py").read_text(encoding="utf-8").lstrip("\ufeff")
+          match = re.search(
+              r"__version__(?:\s*:\s*[^=]+)?\s*=\s*[\"']([^\"']+)[\"']",
+              text,
+          )
+          if not match:
+              raise SystemExit("No __version__ found in src/brkraw/__init__.py")
+          print(match.group(1))
+          PY
+          )
+
+          echo "changed=true" >> "$GITHUB_OUTPUT"
+          echo "value=$version" >> "$GITHUB_OUTPUT"
+        shell: bash
+      - name: Create and push tag
+        if: ${{ steps.version.outputs.changed == 'true' }}
+        run: |
+          tag="${{ steps.version.outputs.value }}"
+          if git rev-parse "$tag" >/dev/null 2>&1; then
+            echo "Tag $tag already exists. Skipping."
+            exit 0
+          fi
+          git tag "$tag" "${{ github.sha }}"
+          git push origin "$tag"

{brkraw-0.5.2 → brkraw-0.5.5}/.gitignore

@@ -21,6 +21,5 @@ site/
 .direnv/
 .envrc
 .idea/
-.vscode/
 *.lock
 .tmp

brkraw-0.5.5/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.terminal.activateEnvironment": true
+}

brkraw-0.5.5/.vscode/tasks.json

@@ -0,0 +1,86 @@
+{
+  "version": "2.0.0",
+  "inputs": [
+    {
+      "id": "releaseVersion",
+      "type": "promptString",
+      "description": "Release version (e.g., 1.0.0)"
+    }
+  ],
+  "tasks": [
+    {
+      "label": "Standard: Setup venv + deps",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" -m venv .venv && .venv/bin/python -m pip install -U pip && .venv/bin/python -m pip install -e \".[dev]\"",
+      "windows": {
+        "command": "\"${command:python.interpreterPath}\" -m venv .venv; .venv\\Scripts\\python -m pip install -U pip; .venv\\Scripts\\python -m pip install -e \".[dev]\"",
+        "options": {
+          "shell": {
+            "executable": "pwsh"
+          }
+        }
+      },
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Standard: Release Prep PR (2-step)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/release_pr.py --version ${input:releaseVersion} --base upstream/main --remote-upstream upstream --remote-origin origin",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "DryRun: Release Prep PR (2-step)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/release_pr.py --dry-run --version ${input:releaseVersion} --base upstream/main --remote-upstream upstream --remote-origin origin",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Standard: MkDocs Serve",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" -m mkdocs serve",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Optional: Release Prep (bump + notes)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/update_contributors.py --source github --repo brkraw/brkraw --output docs/dev/contributors.md && \"${command:python.interpreterPath}\" scripts/release_prep.py --version ${input:releaseVersion} --fetch-tags --remote upstream",
+      "windows": {
+        "command": "pwsh -NoProfile -Command \"& \\\"${command:python.interpreterPath}\\\" scripts/update_contributors.py --source github --repo brkraw/brkraw --output docs/dev/contributors.md; if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }; & \\\"${command:python.interpreterPath}\\\" scripts/release_prep.py --version ${input:releaseVersion} --fetch-tags --remote upstream\""
+      },
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Optional: Release Notes Only",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/release_notes.py --fetch-tags --remote upstream",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Optional: Release Tag + Push (upstream)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/tag_and_push.py",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Optional: Docs Update Contributors (git)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/update_contributors.py --source git --output docs/dev/contributors.md",
+      "group": "build",
+      "problemMatcher": []
+    },
+    {
+      "label": "Optional: Docs Update Contributors (GitHub API)",
+      "type": "shell",
+      "command": "\"${command:python.interpreterPath}\" scripts/update_contributors.py --source github --repo brkraw/brkraw --output docs/dev/contributors.md",
+      "group": "build",
+      "problemMatcher": []
+    }
+  ]
+}

{brkraw-0.5.2 → brkraw-0.5.5}/CITATION.cff

@@ -34,4 +34,4 @@ keywords:
   - BIDS
   - neuroimaging
 
-version: "0.5.2"
+version: "0.5.5"

{brkraw-0.5.2 → brkraw-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brkraw
-Version: 0.5.2
+Version: 0.5.5
 Summary: Toolkit for loading Bruker Paravision datasets, mapping metadata, and exporting NIfTI
 Project-URL: Homepage, https://brkraw.github.io
 Maintainer-email: SungHo Lee <shlee@unc.edu>
@@ -31,6 +31,7 @@ Requires-Dist: mkdocs; extra == 'dev'
 Requires-Dist: mkdocs-material; extra == 'dev'
 Requires-Dist: pymdown-extensions; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: tomli; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: rich; extra == 'docs'
 Provides-Extra: minimal
@@ -44,11 +45,11 @@ Description-Content-Type: text/markdown
 </picture>
 <!-- markdownlint-enable MD041 MD033 MD013 -->
 
-[![DOI](https://zenodo.org/badge/245546149.svg)](https://doi.org/10.5281/zenodo.3818614)
+[![DOI](docs/assets/zenodo_badge.svg)](https://doi.org/10.5281/zenodo.3818614)
 
 A modular toolkit for Bruker MRI raw-data handling.
 
-BrkRaw (v0.5.2) converts raw data into standardized, neuroimaging-ready
+BrkRaw (v0.5.5) converts raw data into standardized, neuroimaging-ready
 datasets, with extensible rules/specs and plugin hooks.
 
 - Documentation: [brkraw.github.io](https://brkraw.github.io/)
@@ -66,16 +67,14 @@ If you use BrkRaw in your research, please cite it.
 
 <!-- BEGIN: brkraw-bibtex -->
 ```biblatex
-@software{brkraw_2026,
-  author = {Lee, Sung-Ho and Devenyi, Gabriel A and Ban, Woomi and Shih, Yen-Yu Ian},
+@software{brkraw,
+  author = {Lee, Sung-Ho and Devenyi, Gabriel A. and Ban, Woomi and Shih, Yen-Yu Ian},
   title = {BrkRaw: A modular toolkit for Bruker MRI raw-data handling},
-  year = {2026},
-  version = {0.5.0},
+  version = {0.5.5},
   doi = {10.5281/zenodo.3818614},
   url = {https://github.com/BrkRaw/brkraw},
   note = {Documentation: https://brkraw.github.io},
-  license = {GPL-3.0-only},
-  date = {2026-01-13}
+  license = {GPL-3.0-only}
 }
 ```
 <!-- END: brkraw-bibtex -->

{brkraw-0.5.2 → brkraw-0.5.5}/README.md

@@ -6,11 +6,11 @@
 </picture>
 <!-- markdownlint-enable MD041 MD033 MD013 -->
 
-[![DOI](https://zenodo.org/badge/245546149.svg)](https://doi.org/10.5281/zenodo.3818614)
+[![DOI](docs/assets/zenodo_badge.svg)](https://doi.org/10.5281/zenodo.3818614)
 
 A modular toolkit for Bruker MRI raw-data handling.
 
-BrkRaw (v0.5.2) converts raw data into standardized, neuroimaging-ready
+BrkRaw (v0.5.5) converts raw data into standardized, neuroimaging-ready
 datasets, with extensible rules/specs and plugin hooks.
 
 - Documentation: [brkraw.github.io](https://brkraw.github.io/)
@@ -28,16 +28,14 @@ If you use BrkRaw in your research, please cite it.
 
 <!-- BEGIN: brkraw-bibtex -->
 ```biblatex
-@software{brkraw_2026,
-  author = {Lee, Sung-Ho and Devenyi, Gabriel A and Ban, Woomi and Shih, Yen-Yu Ian},
+@software{brkraw,
+  author = {Lee, Sung-Ho and Devenyi, Gabriel A. and Ban, Woomi and Shih, Yen-Yu Ian},
   title = {BrkRaw: A modular toolkit for Bruker MRI raw-data handling},
-  year = {2026},
-  version = {0.5.0},
+  version = {0.5.5},
   doi = {10.5281/zenodo.3818614},
   url = {https://github.com/BrkRaw/brkraw},
   note = {Documentation: https://brkraw.github.io},
-  license = {GPL-3.0-only},
-  date = {2026-01-13}
+  license = {GPL-3.0-only}
 }
 ```
 <!-- END: brkraw-bibtex -->

brkraw-0.5.5/RELEASE_NOTES.md

@@ -0,0 +1,17 @@
+# Release v0.5.5
+
+Date: 2026-01-27
+Changes since 0.5.4
+
+- chore: prepare release v0.5.5 (c3260df)
+- docs: update contributors (a7bf3ef)
+- update: vscode, auto activate environment setting. (95e6868)
+- Chore: wire release → publish workflow (3419d97)
+- Use VS Code interpreter for venv setup task (5aed156)
+- Update release workflow and scripts for Zenodo badge + bibtex generation (e63e007)
+- Patch for brkraw-viewer lazy loading (avoid eager data resolution) (c916625)
+- chore(api): config module (2fa90fc)
+- chore(api): hook resolver (9c36e95)
+- chore(api): minor remapping (f2ef87e)
+- chore(api): ensure naming consistency (9010542)
+- refactor(loader): improve hook handling logic (5c5a0e7)

{brkraw-0.5.2 → brkraw-0.5.5}/brkraw/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = '0.5.2'
+__version__ = '0.5.5'
 from .apps.loader import BrukerLoader
 
 

brkraw-0.5.5/brkraw/api/__init__.py

@@ -0,0 +1,122 @@
+"""Public API surface for BrkRaw.
+
+This module intentionally re-exports a curated set of symbols for external use.
+To keep import-time fast and reduce side effects, most symbols are lazily
+imported on first access (PEP 562: module `__getattr__`).
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, Dict, Tuple
+
+# Public API -----------------------------------------------------------------
+
+__all__ = [
+    "formatter",
+    "BrukerLoader",
+    "loader",
+    "hook",
+    "hook_manager",
+    "hook_resolver",
+    "pruner",
+    "rules",
+    "addon",
+    "addon_manager",
+    "validate_meta",
+    "transform",
+    "info_resolver",
+    "affine_resolver",
+    "shape_resolver",
+    "image_resolver",
+    "fid_resolver",
+    "nifti_resolver",
+    "types",
+    "config",
+]
+
+# Lazy import map: name -> (module_path, attribute_name or None)
+# If attribute_name is None, the module itself is returned.
+_LAZY: Dict[str, Tuple[str, str | None]] = {
+    # core
+    "formatter": ("brkraw.core", "formatter"),
+
+    # apps
+    "BrukerLoader": ("brkraw.apps.loader", "BrukerLoader"),
+    "loader": ("brkraw.apps", "loader"),
+    "hook_manager": ("brkraw.apps", "hook"),
+    "addon_manager": ("brkraw.apps", "addon"),
+    "hook_resolver": ("brkraw.apps.loader.helper", "resolve_converter_hook"),
+    "config": ("brkraw.core", "config"),
+
+    # apps.loader.info resolvers
+    "info_resolver": ("brkraw.apps.loader", "info"),
+    "transform": ("brkraw.apps.loader.info", "transform"),
+
+    # resolvers
+    "affine_resolver": ("brkraw.resolver", "affine"),
+    "shape_resolver": ("brkraw.resolver", "shape"),
+    "image_resolver": ("brkraw.resolver", "image"),
+    "fid_resolver": ("brkraw.resolver", "fid"),
+    "nifti_resolver": ("brkraw.resolver", "nifti"),
+
+    # specs
+    "hook": ("brkraw.specs", "hook"),
+    "pruner": ("brkraw.specs", "pruner"),
+    "rules": ("brkraw.specs", "rules"),
+    "addon": ("brkraw.specs", "remapper"),
+
+    # meta
+    "validate_meta": ("brkraw.specs.meta", "validate_meta"),
+
+    # local
+    "types": ("brkraw.api", "types"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import and return public symbols.
+
+    This keeps import-time minimal while preserving the convenient
+    `brkraw.api.<symbol>` access pattern.
+    """
+
+    try:
+        mod_path, attr = _LAZY[name]
+    except KeyError as e:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from e
+
+    mod = import_module(mod_path)
+    obj = mod if attr is None else getattr(mod, attr)
+
+    # Cache the resolved object on the module for fast subsequent access.
+    globals()[name] = obj
+    return obj
+
+
+def __dir__() -> list[str]:
+    # Expose the curated public surface in interactive environments.
+    return sorted(set(__all__))
+
+
+# Type-checking / IDE support -------------------------------------------------
+# Importing these only for type-checking keeps runtime imports lazy.
+if TYPE_CHECKING:
+    from brkraw.core import formatter as formatter
+    from brkraw.core import config as config
+    from brkraw.apps.loader import BrukerLoader as BrukerLoader
+    from brkraw.apps.loader import info as info_resolver
+    from brkraw.apps.loader.info import transform as transform
+    from brkraw.apps.loader.helper import resolve_converter_hook as hook_resolver
+    from brkraw.apps import addon as addon_manager, hook as hook_manager, loader as loader
+    from brkraw.resolver import (
+        affine as affine_resolver,
+        fid as fid_resolver,
+        image as image_resolver,
+        nifti as nifti_resolver,
+        shape as shape_resolver,
+    )
+    from brkraw.specs import hook as hook, pruner as pruner, rules as rules
+    from brkraw.specs import remapper as addon
+    from brkraw.specs.meta import validate_meta as validate_meta
+    from brkraw.api import types as types

brkraw-0.5.5/brkraw/api/types.py

@@ -0,0 +1,39 @@
+from ..apps.loader.types import (
+    StudyLoader, 
+    ScanLoader, 
+    RecoLoader
+)
+from ..apps.loader.types import (
+    GetAffineType,
+    GetDataobjType,
+    ConvertType,
+    ConverterHook,
+    SubjectType, 
+    SubjectPose, 
+    AffineSpace,
+    Affines,
+    Dataobjs,
+    Metadata,
+    ConvertedObj,
+    HookArgs
+)
+from ..core.parameters import Parameters
+
+__all__ = [
+    "GetAffineType",
+    "GetDataobjType",
+    "ConvertType",
+    "ConverterHook",
+    "StudyLoader",
+    "ScanLoader",
+    "RecoLoader",
+    "SubjectType",
+    "SubjectPose",
+    "AffineSpace",
+    "Affines",
+    "Dataobjs",
+    "Metadata",
+    "ConvertedObj",
+    "HookArgs",
+    "Parameters"
+]

brkraw-0.5.5/brkraw/apps/loader/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from .core import BrukerLoader
+
+__all__ = [
+    "BrukerLoader"
+]