kkrunner 0.1.0b1__tar.gz

kkrunner-0.1.0b1/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2018 The Python Packaging Authority
+
+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.

kkrunner-0.1.0b1/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENCE README.md Makefile
+recursive-include docs *.md *.rst *.py
+prune docs/_generated
+recursive-include tests *.py *.sh *.conf Dockerfile
+global-exclude *.py[cod]

kkrunner-0.1.0b1/Makefile

@@ -0,0 +1,10 @@
+PYTHON ?= python
+SPHINXOPTS ?= -W --keep-going
+
+.PHONY: docs docs-test
+
+docs:
+	$(PYTHON) -m sphinx -M html docs build/docs $(SPHINXOPTS)
+
+docs-test:
+	$(PYTHON) -m sphinx -M doctest docs build/docs $(SPHINXOPTS)

kkrunner-0.1.0b1/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: kkrunner
+Version: 0.1.0b1
+Summary: Program-independent local and remote scientific job execution
+License-Expression: MIT
+Project-URL: Documentation, https://ase2sprkkr.github.io/kkrunner/
+Project-URL: Source, https://github.com/ase2sprkkr/kkrunner
+Project-URL: Issues, https://github.com/ase2sprkkr/kkrunner/issues
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: platformdirs
+Requires-Dist: psutil>=5.8.0
+Provides-Extra: psij
+Requires-Dist: psij-python>=0.9.11; extra == "psij"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=3; extra == "docs"
+Requires-Dist: myst-parser>=3; extra == "docs"
+Dynamic: license-file
+
+# KKRunner
+
+Program-independent Python execution, durable run history, file manifests,
+local/MPI processes, SSH transport and optional PSI/J scheduler support.
+The core depends on `platformdirs` and `psutil`; scheduler support is an optional extra.
+
+```sh
+python -m pip install .
+python -m pip install '.[psij]'  # optional scheduler support
+kkrunner remote --help
+```
+
+Run these commands from the KKRunner checkout in a virtual environment.
+Use `python -m pip install --editable .` instead when editing the source.
+
+## Raw execution
+
+```python
+import sys
+from kkrunner import ExecutionSpec
+from kkrunner.backends import LocalExecutor
+
+run = LocalExecutor().create_run(ExecutionSpec([sys.executable, '-c', 'print(42)']))
+outcome = run.run()
+assert outcome.return_code == 0
+```
+
+## Persistent execution
+
+A `RunManager` records runs in a `RunStore` so a later client can reconnect.
+Projects are optional; see the [project guide](docs/projects.rst) for grouping.
+
+```python
+import sys
+from pathlib import Path
+from kkrunner import ExecutionSpec, RunManager, RunStore
+from kkrunner.backends import LocalExecutor
+
+root = Path('example').absolute()
+root.mkdir(exist_ok=True)
+manager = RunManager(RunStore(root / 'runs'))
+run = manager.create_run(
+    LocalExecutor(),
+    ExecutionSpec([sys.executable, '-c', 'print(42)'],
+                  directory=root, output_file='stdout.txt'),
+    metadata={'example': {'label': 'answer'}},
+)
+outcome = run.run()
+assert manager.store.get(run.id).state.value == 'finished'
+```
+
+`manager.attach(run_id)` resumes monitoring and required transfers. A result
+callback is optional; when supplied it receives an `ExecutionOutcome` and may
+return any Python object. To defer processing, create a run with
+`processing_required=True`, then supply `process_result=` on a later attach.
+Without that callback the durable state remains `postprocessing` and `wait()`
+raises `ProcessingPending`. The same exception tells an application observer
+that another client owns/already performed processing; load the historical
+application result instead of treating a raw outcome as a parsed result.
+
+`manager.retry_postprocessing(run_id, callback)` retries failed/interrupted
+processing against the captured files without submitting another process.
+`manager.resume_download(run_id)` reopens a failed download before attach.
+`run.stop_observation()` detaches observation without cancelling the backend;
+`run.cancel()` requests backend cancellation. Untracked raw local runs have no
+restart/reconnect guarantee; managed local runs use the same supervisor as SSH.
+
+See the [documentation guide](docs/index.rst) and [architecture](docs/architecture.md)
+for usage, ownership, recovery and format rules.
+
+## Development and distribution
+
+For development, install an editable checkout with test dependencies:
+
+```sh
+python -m pip install --editable '.[test]'
+python -m pytest -q
+```
+
+To produce archives for sharing, install the build tool with
+`python -m pip install build`, then run `python -m build`. This creates a source
+archive and an installable wheel in `dist/`. CI validates these artifacts on
+Linux with Python 3.9, 3.12 and 3.14, plus macOS tests on Apple Silicon and
+Intel with Python 3.12, including durable local supervision and reconnect.
+See [development](docs/development.rst) for test scope and packaging details.
+
+## Publish to PyPI
+
+The `publish-pypi.yml` workflow runs on a `v<version>` tag from any branch.
+The tag must exactly match `[project].version` in `pyproject.toml`; publication
+is independent of branch names.
+The version is defined in `pyproject.toml`; `kkrunner.__version__` reads the
+installed distribution metadata automatically.
+
+Configure a PyPI Trusted Publisher for project `kkrunner`, GitHub owner
+`ase2sprkkr`, repository `kkrunner`, workflow `publish-pypi.yml` and environment
+`pypi`. Protect the GitHub `pypi` environment with required reviewers and `v*`
+tag rules. If hosted under another owner, use that owner in
+the publisher configuration. No PyPI API token is needed.
+
+The workflow verifies the tag, builds one source archive and wheel,
+then tests that wheel on Python 3.9, 3.12 and 3.14 and builds/tests the documentation.
+Only after all checks pass does the publish job upload those exact artifacts
+using the `pypi` environment and GitHub's OIDC token.
+
+For nonpublic evaluation, use a prerelease version and do not push a version tag.
+Branch CI retains wheel/sdist artifacts for evaluation. Use access-controlled
+storage when sharing with testers: GitHub artifacts in a public repository are
+not private, and an upload to PyPI is public even for a development version.
+
+## Documentation
+
+Documentation is published at <https://ase2sprkkr.github.io/kkrunner/> after
+successful runtime and documentation checks on `master`.
+
+The user guide and API reference use Sphinx with the Read the Docs theme.
+Install the documentation extra and build the HTML and examples:
+
+```sh
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[docs]'
+make docs PYTHON=.venv/bin/python
+make docs-test PYTHON=.venv/bin/python
+```
+
+Use the same Python for dependency installation and Makefile targets; the
+`docs` extra includes MyST and the theme. Open `build/docs/html/index.html`. See [the guide](docs/index.rst) for raw and
+persistent execution, manifests, projects, schedulers, remote execution and the
+CLI; [development](docs/development.rst) covers builds and releases. Generated
+API pages and HTML are not committed. CI validates documentation against the
+installed wheel and uploads the HTML artifact. The separate documentation
+workflow checks the same wheel and documentation, omits the runtime test
+matrices, and deploys to GitHub Pages for `v*` tags or manual runs. Enable
+**Settings → Pages → Build and deployment → GitHub Actions** and allow release
+tags and manually selected source branches in the `github-pages` environment
+deployment rules.
+
+Source provenance is recorded in [development remarks](docs/remarks/source-provenance.md);
+the license is in [LICENCE](LICENCE).

kkrunner-0.1.0b1/README.md

@@ -0,0 +1,139 @@
+# KKRunner
+
+Program-independent Python execution, durable run history, file manifests,
+local/MPI processes, SSH transport and optional PSI/J scheduler support.
+The core depends on `platformdirs` and `psutil`; scheduler support is an optional extra.
+
+```sh
+python -m pip install .
+python -m pip install '.[psij]'  # optional scheduler support
+kkrunner remote --help
+```
+
+Run these commands from the KKRunner checkout in a virtual environment.
+Use `python -m pip install --editable .` instead when editing the source.
+
+## Raw execution
+
+```python
+import sys
+from kkrunner import ExecutionSpec
+from kkrunner.backends import LocalExecutor
+
+run = LocalExecutor().create_run(ExecutionSpec([sys.executable, '-c', 'print(42)']))
+outcome = run.run()
+assert outcome.return_code == 0
+```
+
+## Persistent execution
+
+A `RunManager` records runs in a `RunStore` so a later client can reconnect.
+Projects are optional; see the [project guide](docs/projects.rst) for grouping.
+
+```python
+import sys
+from pathlib import Path
+from kkrunner import ExecutionSpec, RunManager, RunStore
+from kkrunner.backends import LocalExecutor
+
+root = Path('example').absolute()
+root.mkdir(exist_ok=True)
+manager = RunManager(RunStore(root / 'runs'))
+run = manager.create_run(
+    LocalExecutor(),
+    ExecutionSpec([sys.executable, '-c', 'print(42)'],
+                  directory=root, output_file='stdout.txt'),
+    metadata={'example': {'label': 'answer'}},
+)
+outcome = run.run()
+assert manager.store.get(run.id).state.value == 'finished'
+```
+
+`manager.attach(run_id)` resumes monitoring and required transfers. A result
+callback is optional; when supplied it receives an `ExecutionOutcome` and may
+return any Python object. To defer processing, create a run with
+`processing_required=True`, then supply `process_result=` on a later attach.
+Without that callback the durable state remains `postprocessing` and `wait()`
+raises `ProcessingPending`. The same exception tells an application observer
+that another client owns/already performed processing; load the historical
+application result instead of treating a raw outcome as a parsed result.
+
+`manager.retry_postprocessing(run_id, callback)` retries failed/interrupted
+processing against the captured files without submitting another process.
+`manager.resume_download(run_id)` reopens a failed download before attach.
+`run.stop_observation()` detaches observation without cancelling the backend;
+`run.cancel()` requests backend cancellation. Untracked raw local runs have no
+restart/reconnect guarantee; managed local runs use the same supervisor as SSH.
+
+See the [documentation guide](docs/index.rst) and [architecture](docs/architecture.md)
+for usage, ownership, recovery and format rules.
+
+## Development and distribution
+
+For development, install an editable checkout with test dependencies:
+
+```sh
+python -m pip install --editable '.[test]'
+python -m pytest -q
+```
+
+To produce archives for sharing, install the build tool with
+`python -m pip install build`, then run `python -m build`. This creates a source
+archive and an installable wheel in `dist/`. CI validates these artifacts on
+Linux with Python 3.9, 3.12 and 3.14, plus macOS tests on Apple Silicon and
+Intel with Python 3.12, including durable local supervision and reconnect.
+See [development](docs/development.rst) for test scope and packaging details.
+
+## Publish to PyPI
+
+The `publish-pypi.yml` workflow runs on a `v<version>` tag from any branch.
+The tag must exactly match `[project].version` in `pyproject.toml`; publication
+is independent of branch names.
+The version is defined in `pyproject.toml`; `kkrunner.__version__` reads the
+installed distribution metadata automatically.
+
+Configure a PyPI Trusted Publisher for project `kkrunner`, GitHub owner
+`ase2sprkkr`, repository `kkrunner`, workflow `publish-pypi.yml` and environment
+`pypi`. Protect the GitHub `pypi` environment with required reviewers and `v*`
+tag rules. If hosted under another owner, use that owner in
+the publisher configuration. No PyPI API token is needed.
+
+The workflow verifies the tag, builds one source archive and wheel,
+then tests that wheel on Python 3.9, 3.12 and 3.14 and builds/tests the documentation.
+Only after all checks pass does the publish job upload those exact artifacts
+using the `pypi` environment and GitHub's OIDC token.
+
+For nonpublic evaluation, use a prerelease version and do not push a version tag.
+Branch CI retains wheel/sdist artifacts for evaluation. Use access-controlled
+storage when sharing with testers: GitHub artifacts in a public repository are
+not private, and an upload to PyPI is public even for a development version.
+
+## Documentation
+
+Documentation is published at <https://ase2sprkkr.github.io/kkrunner/> after
+successful runtime and documentation checks on `master`.
+
+The user guide and API reference use Sphinx with the Read the Docs theme.
+Install the documentation extra and build the HTML and examples:
+
+```sh
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[docs]'
+make docs PYTHON=.venv/bin/python
+make docs-test PYTHON=.venv/bin/python
+```
+
+Use the same Python for dependency installation and Makefile targets; the
+`docs` extra includes MyST and the theme. Open `build/docs/html/index.html`. See [the guide](docs/index.rst) for raw and
+persistent execution, manifests, projects, schedulers, remote execution and the
+CLI; [development](docs/development.rst) covers builds and releases. Generated
+API pages and HTML are not committed. CI validates documentation against the
+installed wheel and uploads the HTML artifact. The separate documentation
+workflow checks the same wheel and documentation, omits the runtime test
+matrices, and deploys to GitHub Pages for `v*` tags or manual runs. Enable
+**Settings → Pages → Build and deployment → GitHub Actions** and allow release
+tags and manually selected source branches in the `github-pages` environment
+deployment rules.
+
+Source provenance is recorded in [development remarks](docs/remarks/source-provenance.md);
+the license is in [LICENCE](LICENCE).

kkrunner-0.1.0b1/docs/_templates/autosummary/class.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :undoc-members:
+   :show-inheritance:

kkrunner-0.1.0b1/docs/_templates/autosummary/function.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autofunction:: {{ objname }}

kkrunner-0.1.0b1/docs/api.rst

@@ -0,0 +1,141 @@
+API reference
+===============
+
+The root package provides backend-independent entry points for ordinary runs.
+Choose executors from :mod:`kkrunner.backends` or :mod:`kkrunner.remote`; projects,
+file manifests and advanced run contracts have their own public subpackages.
+These import paths are independent of the modules implementing each type.
+
+Common entry points
+----------------------
+
+.. py:module:: kkrunner
+
+.. currentmodule:: kkrunner
+
+.. autosummary::
+   :toctree: _generated
+
+   ExecutionSpec
+   ExecutionOutcome
+   RunManager
+   RunStore
+   RunState
+   TaskFile
+   ProcessingPending
+
+Execution contracts and durable records
+-----------------------------------------
+
+.. py:module:: kkrunner.runs
+
+.. currentmodule:: kkrunner.runs
+
+.. autosummary::
+   :toctree: _generated
+
+   LaunchSpec
+   MpiSpec
+   MpiNotFoundWarning
+   RunStatus
+   FailurePhase
+   Runner
+   BackendRunner
+   ManagedRunner
+   Executor
+   PersistentRunner
+   RunRecord
+   CorruptRunRecord
+   DuplicateSubmissionError
+   HistoricalFileMismatchError
+   Execution
+   WorkingDirectory
+
+Declared files and identity
+-----------------------------
+
+.. py:module:: kkrunner.files
+
+.. currentmodule:: kkrunner.files
+
+.. autosummary::
+   :toctree: _generated
+
+   FileEntry
+   CacheEntry
+   FileMapping
+   FileManifest
+   FileSyncPolicy
+   ArtifactAvailabilityState
+   FileFingerprint
+   FileState
+   FileVersion
+   FileVersionCaptureError
+
+Execution backends
+---------------------
+
+.. py:module:: kkrunner.backends
+
+.. currentmodule:: kkrunner.backends
+
+.. autosummary::
+   :toctree: _generated
+
+   LocalExecutor
+   PsijExecutor
+   ExecutorEndpoint
+   ExecutorPool
+   default_executor_pool
+
+Remote execution and transport
+--------------------------------
+
+.. py:module:: kkrunner.remote
+
+.. currentmodule:: kkrunner.remote
+
+.. autosummary::
+   :toctree: _generated
+
+   RemoteEndpointExecutor
+   Transport
+   RunningCommand
+   LocalTransport
+   SshTransport
+
+Projects
+----------
+
+.. py:module:: kkrunner.projects
+
+.. currentmodule:: kkrunner.projects
+
+.. autosummary::
+   :toctree: _generated
+
+   Project
+   ProjectRepository
+   ProjectRepositoryError
+   ProjectConflictError
+   ProjectDeleteError
+   ProjectExecutionManager
+   default_projects_directory
+
+Backend implementation interfaces
+------------------------------------
+
+These modules expose lower-level runner implementations and resource ownership
+helpers for backend authors. They are not re-exported by the public facades.
+
+.. currentmodule:: kkrunner
+
+.. autosummary::
+   :toctree: _generated
+
+   backends.local.LocalRunner
+   backends.psij.PsijRunner
+   remote.runner.RemoteRunner
+   runs.processing.PostprocessingRunner
+   runs.base.ExecutionResources
+   runs.base.ResourceOwnedRunner