horus-singularity 0.0.1__tar.gz

horus_singularity-0.0.1/.github/workflows/python-ci.yaml

@@ -0,0 +1,62 @@
+name: Python CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Sync project dependencies
+        run: uv sync --group dev
+
+      - name: Lint with Ruff and mypy
+        run: uv run make lint
+
+      - name: Check translations
+        run: uv run make babel-check
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Sync project dependencies
+        run: uv sync --group dev
+
+      - name: Run tests with coverage
+        run: uv run make test
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v6
+        if: matrix.python-version == '3.13'
+        with:
+          name: coverage-html-report
+          path: htmlcov/
+          retention-days: 5

horus_singularity-0.0.1/.github/workflows/release.yaml

@@ -0,0 +1,35 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+
+      - name: Sync project dependencies
+        run: uv sync --group dev
+
+      - name: Verify and compile translations
+        run: uv run make babel-check
+
+      - name: Build package
+        run: uv run uv build
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

horus_singularity-0.0.1/.gitignore

@@ -0,0 +1,54 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+*.ipynb
+
+# Virtual environments
+venv/
+.venv/
+ENV/
+env/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# OS
+.DS_Store
+Thumbs.db
+
+*.xml
+
+# i18n
+*.mo
+
+# logs
+logs/
+
+no-commit/

horus_singularity-0.0.1/.mit.tmpl

@@ -0,0 +1,4 @@
+${projectname}
+Copyright (c) ${years} ${owner}
+
+MIT License

horus_singularity-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+  - id: check-yaml
+  - id: check-added-large-files
+
+- repo: local
+  hooks:
+  - id: ruff-lint
+    name: ruff lint
+    entry: ruff check --fix
+    language: system
+    types: [ python ]
+    require_serial: true
+
+  - id: ruff-format
+    name: ruff format
+    entry: ruff format
+    language: system
+    types: [ python ]
+
+  - id: mypy
+    name: mypy
+    entry: mypy
+    language: system
+    types: [ python ]
+    require_serial: true
+
+  # If the commit includes changes in translation files,
+  # check that all translations are complete.
+  - id: babel-check
+    name: babel-check
+    entry: make babel-check
+    language: system
+
+  - id: add-license-headers
+    name: add-license-headers
+    entry: make add-license-headers
+    language: system
+    pass_filenames: false

horus_singularity-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Temple Compute
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

horus_singularity-0.0.1/Makefile

@@ -0,0 +1,101 @@
+# Makefile for Horus Runtime plugin development
+
+# Command definitions (used in CI and locally)
+PYTEST_CMD = pytest --cov=src/horus_singularity --cov-report=xml --cov-report=html --cov-report=term --junitxml=test-results.xml
+RUFF_LINT_CMD = ruff check src/ tests/
+RUFF_FORMAT_CHECK_CMD = ruff format --check --diff .
+RUFF_FIX_CMD = ruff check --fix src/ tests/
+RUFF_FORMAT_CMD = ruff format .
+MYPY_CMD = mypy src/ tests/
+
+# i18n settings (babel)
+BABEL_CFG = babel.cfg
+LOCALE_DIR = src/horus_singularity/locale
+MESSAGES_POT = $(LOCALE_DIR)/messages.pot
+DOMAIN = horus_singularity
+SOURCE_DIR = src/horus_singularity
+
+# Variables used for babel metadata
+PROJECT_NAME = horus_singularity
+ORGANIZATION = Temple Compute
+LICENSE_TMPL = .mit.tmpl
+
+.PHONY: test lint format type-check clean help ruff-check ruff-format-check mypy-check babel-update babel-check babel-add babel-extract add-license-headers
+
+help:
+	@echo "Available commands:"
+	@echo "  test                Run all tests with coverage (same as CI)"
+	@echo "  lint                Run all linting tools (same as CI)"
+	@echo "  ruff-check          Check code with ruff linter (used by CI)"
+	@echo "  ruff-format-check   Check code formatting with ruff (used by CI)"
+	@echo "  mypy-check          Check types with mypy (used by CI)"
+	@echo "  format              Format code with ruff"
+	@echo "  type-check          Run type checking"
+	@echo "  babel-update        Update Babel translations"
+	@echo "  babel-check         Check Babel translations (used by CI)"
+	@echo "  babel-add           Add a new language (usage: make babel-add LANG=es)"
+	@echo "  babel-extract       Extract translatable strings to messages.pot"
+	@echo "  clean               Remove cache files"
+
+test:
+	# Set PYTHONPATH to current directory to ensure tests can find other test modules
+	PYTHONPATH=. $(PYTEST_CMD)
+
+# Individual check commands
+ruff-check:
+	$(RUFF_LINT_CMD)
+
+ruff-format-check:
+	$(RUFF_FORMAT_CHECK_CMD)
+
+mypy-check:
+	$(MYPY_CMD)
+
+lint:
+	$(RUFF_LINT_CMD)
+	$(RUFF_FORMAT_CHECK_CMD)
+	$(MYPY_CMD)
+
+format:
+	$(RUFF_FIX_CMD)
+	$(RUFF_FORMAT_CMD)
+
+type-check:
+	$(MYPY_CMD)
+
+add-license-headers:
+	licenseheaders -t $(LICENSE_TMPL) -cy -o '$(ORGANIZATION)' -n $(PROJECT_NAME) -d src
+	licenseheaders -t $(LICENSE_TMPL) -cy -o '$(ORGANIZATION)' -n $(PROJECT_NAME) -d tests
+
+clean:
+	find . -type d -name "__pycache__" -delete
+	find . -type f -name "*.pyc" -delete
+	rm -rf .coverage htmlcov/ .pytest_cache/
+	rm -rf *.egg-info/ build/ dist/
+
+babel-extract:
+	pybabel extract -F $(BABEL_CFG) \
+		--project=$(PROJECT_NAME) \
+		--copyright-holder="$(ORGANIZATION)" \
+		-o $(MESSAGES_POT) $(SOURCE_DIR)
+
+babel-update:
+	pybabel update -i $(MESSAGES_POT) -d $(LOCALE_DIR) -D $(DOMAIN) --no-fuzzy-matching
+
+babel-refresh: babel-extract babel-update
+
+babel-check:
+	@echo "Checking for missing or fuzzy translations..."
+	@for file in $(shell find $(LOCALE_DIR) -name "*.po"); do \
+		RESULT=$$(msgfmt --statistics -c -o /dev/null $$file 2>&1); \
+		echo "$$RESULT"; \
+		if echo "$$RESULT" | grep -E "untranslated|fuzzy" > /dev/null; then \
+			echo "ERROR: $$file has missing or fuzzy strings!"; \
+			exit 1; \
+		fi; \
+	done
+	@echo "Success: All strings are translated."
+	pybabel compile -d $(LOCALE_DIR) -D $(DOMAIN) --statistics
+
+babel-add:
+	pybabel init -i $(MESSAGES_POT) -d $(LOCALE_DIR) -l $(LANG) -D $(DOMAIN)

horus_singularity-0.0.1/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: horus_singularity
+Version: 0.0.1
+Summary: A Horus runtime plugin that runs task commands inside Singularity/Apptainer containers.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Requires-Dist: horus-runtime>=0.2.0

horus_singularity-0.0.1/README.md

@@ -0,0 +1,123 @@
+# horus-singularity
+
+[![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+A [horus-runtime](https://github.com/temple-compute/horus-runtime) plugin that runs tasks inside Singularity/Apptainer containers.
+
+---
+
+## Overview
+
+**horus-singularity** contributes a `SingularityExecutor` to the `horus.executor` entry point group. Once installed, any `HorusContext` that calls `HorusContext.boot()` will automatically discover and register the executor — no manual wiring required.
+
+The executor accepts a `CommandRuntime`-produced shell command and runs it via `/bin/sh -c` inside a Singularity (or Apptainer) container, giving you the same shell semantics (pipes, globbing, `&&`, …) as the local shell executor.
+
+It is the HPC counterpart of [horus-docker](https://github.com/temple-compute/horus-docker): most clusters forbid the Docker daemon but ship Singularity/Apptainer, so this plugin is a drop-in swap for the same workflows.
+
+---
+
+## Repository structure
+
+```
+src/
+└── horus_singularity/
+    ├── __init__.py
+    ├── i18n.py                  # plugin-scoped gettext wrapper
+    ├── locale/
+    │   └── messages.pot         # translatable strings template
+    └── executor/
+        ├── __init__.py
+        └── singularity.py       # SingularityExecutor implementation
+tests/
+├── __init__.py
+├── conftest.py                  # shared fixtures (registry, HorusContext)
+└── unit/
+    ├── __init__.py
+    └── test_singularity_executor.py
+babel.cfg
+Makefile
+pyproject.toml
+```
+
+---
+
+## SingularityExecutor
+
+Registered under `kind = "singularity"`. Only accepted when the task's runtime is a `CommandRuntime`.
+
+### Fields
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `image` | `str` | required | Path to the `.sif` image on the target (e.g. `/opt/images/boltz.sif`) |
+| `exe` | `str` | `"singularity"` | Container CLI to invoke — `singularity` or `apptainer` |
+| `binds` | `dict[str, str]` | `{}` | Bind mounts as `host_path → container_path` |
+| `nv` | `bool` | `False` | Add `--nv` to expose the NVIDIA driver stack inside the container |
+| `env` | `dict[str, str]` | `{}` | Environment variables set with `--env NAME=value` |
+| `working_dir` | `str \| None` | `None` | Working directory inside the container (`--pwd`) |
+| `extra_args` | `list[str]` | `[]` | Extra flags passed verbatim before the image path |
+
+### Behaviour
+
+1. The task's `CommandRuntime` prepares the shell command via `setup_runtime()`.
+2. The executor builds:
+   ```
+   <exe> exec [--nv] [--env K=V]… [--bind host:container]… [--pwd dir] [extra_args…] <image> /bin/sh -c <command>
+   ```
+   Every interpolated value is passed through `shlex.quote`.
+3. The parent directory of every task input/output artifact is auto-bound at the same path inside the container (`host_dir → host_dir`). Explicit `binds` entries win on conflict.
+4. The command runs on the task target via `target.run_command(...)`; stdout is logged at `INFO`, stderr at `WARNING`.
+5. A non-zero exit code raises `TaskExecutionError`.
+6. `cancel_execution()` kills the still-running process (Singularity has no daemon-side container name to `stop`), and is a safe no-op otherwise.
+
+---
+
+## Development
+
+### Requirements
+
+- Python ≥ 3.13
+- `singularity` or `apptainer` available on the target
+- `horus-runtime` ≥ 0.2.0
+
+### Setup
+
+```bash
+# Install dependencies (creates .venv automatically)
+uv sync
+
+# Install pre-commit hooks
+uv run pre-commit install
+```
+
+### Common commands
+
+| Command | Description |
+|---|---|
+| `make test` | Run the full test suite with coverage |
+| `make lint` | ruff + mypy |
+| `make format` | Auto-fix with ruff |
+| `make type-check` | mypy only |
+| `make babel-extract` | Update `messages.pot` |
+| `make babel-add LANG=es` | Add a new language |
+| `make babel-check` | Verify all strings are translated |
+| `make clean` | Remove build artefacts and caches |
+
+---
+
+## Internationalization (i18n)
+
+Each plugin maintains its **own** gettext domain and locale directory, independent of the runtime's translations.
+
+`src/horus_singularity/i18n.py` wraps Python's `gettext` module, looking for compiled `.mo` files in `src/horus_singularity/locale/<lang>/LC_MESSAGES/horus_singularity.mo`. If no catalog exists for the detected locale, it falls back to the original string.
+
+Import the wrapper as `_` (required by Babel's extractor) in any module with user-visible strings. Use `make babel-extract` → edit `.po` → `make babel-check` to update translations. The pre-commit hook prevents committing incomplete catalogs.
+
+> Full i18n workflow and plural-form reference: [docs.templecompute.com](https://docs.templecompute.com/docs/sdk/i18n).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

horus_singularity-0.0.1/babel.cfg

@@ -0,0 +1,2 @@
+[python: **.py]
+encoding = utf-8

horus_singularity-0.0.1/pyproject.toml

@@ -0,0 +1,114 @@
+[project]
+name = "horus_singularity"
+version = "0.0.1"
+description = "A Horus runtime plugin that runs task commands inside Singularity/Apptainer containers."
+requires-python = ">=3.13"
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+]
+dependencies = ["horus-runtime>=0.2.0"]
+
+# ================
+# Plugin entry-points
+# ================
+[project.entry-points."horus.executor"]
+singularity = "horus_singularity.executor.singularity"
+
+# ================
+
+[dependency-groups]
+dev = [
+  "babel~=2.0",
+  "licenseheaders~=0.8",
+  "mypy~=1.19",
+  "pre_commit~=4.0",
+  "pytest~=9.0",
+  "pytest-asyncio~=1.3.0",
+  "pytest-cov~=7.0",
+  "ruff~=0.15",
+  "types-PyYAML~=6.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.coverage.run]
+source = ["horus_singularity"]
+
+[tool.coverage.report]
+omit = ["tests/*"]
+
+[tool.hatch.build]
+artifacts = ["src/horus_singularity/locale/**/LC_MESSAGES/*.mo"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/horus_singularity"]
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+exclude = ["build", "dist"]
+plugins = ["pydantic.mypy"]
+
+[tool.pydantic-mypy]
+init_typed = true
+init_forbid_extra = true
+warn_required_dynamic_aliases = true
+
+[tool.pytest.ini_options]
+addopts = """
+    --verbose
+    --cov=src/horus_singularity
+    --cov-report=html
+    --cov-report=term-missing
+    --cov-fail-under=90
+"""
+minversion = "7.0"
+python_classes = ["Test*"]
+python_files = ["test_*.py", "*_test.py"]
+python_functions = ["test_*"]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 79
+target-version = "py313"
+exclude = [".git", ".venv", "build", "dist", "__pycache__"]
+
+[tool.ruff.lint]
+select = [
+  "D",  # pydocstyle
+  "E",  # pycodestyle errors
+  "W",  # pycodestyle warnings
+  "F",  # pyflakes
+  "I",  # isort
+  "N",  # pep8-naming
+  "UP",  # pyupgrade
+  "B",  # flake8-bugbear
+  "PL",  # pylint
+  "RUF",  # ruff-specific
+  "ARG",  # ruff-arglint
+  "SLF",  # ruff-slf
+]
+extend-select = ["T201"]  # Prevent use of print()
+
+ignore = [
+  "E203",  # Whitespace before ':', conflicts with formatter
+  "D104",  # Missing docstring in __init__ (often redundant)
+  "D205",  # 1 blank line required between summary line and description
+  "D212",  # Multi-line docstring summary should start at the first line
+  "D200",  # One-line docstring should fit on one line
+  "PLR2004"  # Magic numbers are ok
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["SLF001"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"

horus_singularity-0.0.1/src/horus_singularity/__init__.py

@@ -0,0 +1,6 @@
+#
+# horus_singularity
+# Copyright (c) 2026 Temple Compute
+#
+# MIT License
+#

horus_singularity-0.0.1/src/horus_singularity/executor/__init__.py

@@ -0,0 +1,6 @@
+#
+# horus_singularity
+# Copyright (c) 2026 Temple Compute
+#
+# MIT License
+#