scinexus 2026.4.17a0__tar.gz

scinexus-2026.4.17a0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+# NOTE:
+# if changing python versions, also update versions in
+# - release.yml
+# - noxfile.py
+
+jobs:
+  tests:
+    name: "Python ${{ matrix.python-version }} (${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.14"]
+
+    steps:
+      - uses: "actions/checkout@v6"
+        with:
+          fetch-depth: 0
+
+      # Setup env
+      - uses: "actions/setup-python@v6"
+        with:
+            python-version: "${{ matrix.python-version }}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install MPI (Ubuntu)
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y openmpi-bin libopenmpi-dev
+
+      - name: "Run nox for ${{ matrix.python-version }}"
+        shell: bash
+        run: |
+          lname="snx-${{matrix.os}}-${{matrix.python-version}}.lcov"
+          xname="snx-${{matrix.os}}-${{matrix.python-version}}.xml"
+          cov="lcov -o$lname xml -o$xname"
+          uv run --group test nox --force-python python -s testcov -- $cov
+
+      - name: Coveralls Parallel
+        uses: coverallsapp/github-action@v2
+        with:
+          parallel: true
+          github-token: ${{ secrets.github_token }}
+          flag-name: run-${{matrix.python-version}}-${{matrix.os}}
+          file: "snx-${{matrix.os}}-${{matrix.python-version}}.lcov"
+
+  type_check:
+    name: Type Check
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      matrix:
+        python-version: ["3.14"]
+        os: [ubuntu-latest]
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: "actions/setup-python@v6"
+        with:
+            python-version: "${{ matrix.python-version }}"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: "Run Type Checking for ${{ matrix.python-version }}"
+        run: |
+          uv run --group test nox --force-python python -s type_check
+
+  finish:
+    name: "Finish Coveralls"
+    needs: tests
+    runs-on: ubuntu-latest
+    steps:
+    - name: Coveralls Finished
+      uses: coverallsapp/github-action@v2
+      with:
+        github-token: ${{ secrets.github_token }}
+        parallel-finished: true

scinexus-2026.4.17a0/.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches-ignore:
+      - master
+  pull_request:
+    branches-ignore:
+      - master
+  schedule:
+    - cron: '39 20 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v6
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v4
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v4
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v4
+      with:
+        category: "/language:${{matrix.language}}"

scinexus-2026.4.17a0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: Build Docs
+
+concurrency:
+  group: docs-build-${{ github.ref }}
+  cancel-in-progress: true
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.readthedocs.yaml'
+      - 'mkdocs.yml'
+      - 'rtd_get_docs.py'
+
+permissions:
+  contents: read
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - uses: "actions/setup-python@v5"
+        with:
+            python-version: "3.14"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install Docs Dependencies
+        run: |
+          uv venv venv -p python
+          source venv/bin/activate
+          uv pip install ".[test]"
+
+      - name: Build Documentation
+        run: |
+          source venv/bin/activate
+          # update executable components
+          uv run nox -s cogdocs
+          # build actual docs
+          zensical build --clean
+        working-directory: ${{ github.workspace }}
+
+      - name: Upload Documentation Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: scinexus-docs-html
+          path: site

scinexus-2026.4.17a0/.github/workflows/linters.yml

@@ -0,0 +1,33 @@
+name: Lint code using ruff
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  linters:
+    runs-on: ubuntu-latest
+    if: github.repository != 'cogent3/SciNexus'
+    steps:
+      - uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Format code using ruff
+        run: uv run --group test nox -s fmt
+
+      - name: Commit changes
+        uses: EndBug/add-and-commit@v10
+        with:
+          author_name: ${{ github.actor }}
+          author_email: ${{ github.actor }}@users.noreply.github.com
+          message: "STY: pre-commit linting with ruff"
+          add: "."

scinexus-2026.4.17a0/.github/workflows/release.yml

@@ -0,0 +1,137 @@
+name: Release
+
+on: [workflow_dispatch]
+
+jobs:
+  test:
+    name: "Test on Python ${{ matrix.python-version }} (${{ matrix.os }})"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: "actions/checkout@v6"
+        with:
+          fetch-depth: 0
+
+      # Setup env
+      - uses: "actions/setup-python@v6"
+        with:
+            python-version: "${{ matrix.python-version }}"
+
+      - name: Install MPI (Ubuntu)
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y openmpi-bin libopenmpi-dev
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: "Run nox for ${{ matrix.python-version }}"
+        shell: bash
+        run: |
+          uv run --group test nox -db uv --force-python python -s test
+          uv run --group test nox -db uv --force-python python -s test_types
+          uv run --group test nox -db uv --force-python python -s test_docs
+
+      - name: "Run MPI tests"
+        if: startsWith(matrix.os, 'ubuntu')
+        shell: bash
+        run: |
+          uv run --group test nox -db uv --force-python python -s testmpi
+
+  # docbuild:
+  #   name: "Test the docs"
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - uses: "actions/checkout@v6"
+  #       with:
+  #         fetch-depth: 0
+
+  #     - uses: "actions/setup-python@v6"
+  #       with:
+  #           python-version: "3.14"
+
+  #     - name: Install uv
+  #       uses: astral-sh/setup-uv@v7
+  #       with:
+  #         enable-cache: true
+  #         cache-dependency-glob: "pyproject.toml"
+
+  #     - name: "test the docs code"
+  #       run: "uv run --group test zensical build"
+
+  build:
+    name: Build wheel and sdist
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload sdist and wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: snx-wheel-sdist
+          path: |
+            ./dist/*.whl
+            ./dist/*.tar.gz
+
+  release_test:
+    name: Release to Test PyPI
+    needs: build
+    # needs: [build, docbuild]
+    environment: release_test
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download sdist and wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: snx-wheel-sdist
+          path: ./dist
+
+      - name: Publish package distributions to Test PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  release:
+    name: Release to PyPI
+    needs: release_test
+    environment: release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download sdist and wheel
+        uses: actions/download-artifact@v8
+        with:
+          name: snx-wheel-sdist
+          path: ./dist
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scinexus-2026.4.17a0/.gitignore

@@ -0,0 +1,66 @@
+*.py[cod]
+
+# C extensions
+*.so
+
+# Packages
+*.egg
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+doc/_build
+
+# docker stuff
+.devcontainer/*
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+.mypy*
+**/.mypy_cache/*
+.coverage*
+.tox
+.nox
+coverage.xml
+junit-*.xml
+nosetests.xml
+lcov*.info
+.ruff_cache/*
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+.idea/*
+.DS_Store
+__pycache__
+*.code-workspace
+*.wpr
+*.wpu
+.vscode/*
+venv*
+.venv*
+working/
+*.ipynb
+*.ipynb_checkpoints/
+
+# vi
+.*.swp
+
+
+CLAUDE.md
+
+site/*

scinexus-2026.4.17a0/.hgignore

@@ -0,0 +1,44 @@
+syntax:glob
+.svn
+*.pyc
+*.pyo
+*.so
+*.o
+*.DS_Store
+*.tmproj
+*.rej
+*.orig
+*.wpr
+*.pdf
+_build/*
+build
+*htmlcov*
+*.idea
+*.coverage*
+*egg-info*
+*.wpu
+.cache*
+*taskpaper
+*.ipynb
+*.ipynb_checkpoints*
+*.sublime*
+*.patch
+*.pytest_cache
+*.tox
+*.nox
+*.vscode
+*.code-workspace
+coverage.xml
+__pycache__
+junit-*.xml
+dist/*
+working/*
+lcov*.info
+.ruff_cache/*
+.devcontainer/*
+venv*
+.venv*
+.mypy*
+CLAUDE.md
+site/*
+docs/data/*

scinexus-2026.4.17a0/.readthedocs.yaml

@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.14"
+  commands:
+    # Install the required dependencies
+    - pip install requests
+    # Run the script to download and extract the pre-built docs
+    - python rtd_get_docs.py
+    - echo "Documentation downloaded and extracted"
+
+# Disable the default build processes since we're using pre-built docs
+sphinx:
+  configuration: null
+
+python:
+  install: []

scinexus-2026.4.17a0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, cogent3
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

scinexus-2026.4.17a0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: scinexus
+Version: 2026.4.17a0
+Summary: A composable app infrastructure for scientific computing
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Requires-Dist: charset-normalizer
+Requires-Dist: citeable
+Requires-Dist: loky
+Requires-Dist: scitrack
+Requires-Dist: tqdm
+Requires-Dist: typeguard
+Provides-Extra: mpi
+Requires-Dist: mpi4py; extra == 'mpi'
+Provides-Extra: rich
+Requires-Dist: rich; extra == 'rich'
+Description-Content-Type: text/markdown
+
+[![Coverage Status](https://coveralls.io/repos/github/cogent3/scinexus/badge.svg?branch=main)](https://coveralls.io/github/cogent3/scinexus?branch=main)
+[![Codacy Badge](https://app.codacy.com/project/badge/Grade/fd8810efd4f142069bd84144e14350b4)](https://app.codacy.com/gh/cogent3/scinexus/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![CI](https://github.com/cogent3/scinexus/actions/workflows/ci.yml/badge.svg)](https://github.com/cogent3/scinexus/actions/workflows/ci.yml)
+
+# scinexus
+
+*A composable app infrastructure for scientific computing. What dataclasses are for structured data, `scinexus` apps are for structured algorithms.*
+
+Many scientific problems require repeating calculations across many files or database records. Such tasks suit data-level parallelism, but writing robust, maintainable code for them is often tedious and quickly becomes complex.
+
+As the Unix philosophy articulates, writing algorithms that do one thing well and can be composed together through piping data of known type is a *Very Good Thing*™.
+
+**`scinexus` encourages this design pattern.** We leverage the Python type annotation system to govern the compatibility (composability) of different applications. This enables in-process composition of your applications with validation of the consistency of the pipeline and the consistency of the data being run through it.
+
+**`scinexus` is designed for scientific reproducibility.** Scientific computations should record all conditions needed to reproduce an analysis. `scinexus` reduces the effort by intercepting all arguments (including defaults) used in app construction and logging the resulting app state.
+
+## Examples
+
+Developers can choose inheriting from a base class or use the `scinexus.define_app` decorator to make composable apps. The following examples show simple composition
+
+<details>
+<summary>Loading files so missing data does not cause a crash</summary>
+
+```python
+from scinexus import define_app
+
+@define_app(app_type="loader")
+def read_json(path: str) -> dict:
+    import json
+    with open(path) as f:
+        return json.load(f)
+
+@define_app
+def validate(data: dict, required_field: str) -> dict:
+    if required_field not in data:
+        raise ValueError(f"missing {required_field!r} field")  # becomes NotCompleted, doesn't crash
+    return data
+
+app = read_json() + validate(required_field="name")
+```
+
+You can apply `app` to a single file path as `app(filepath)`, or operate in parallel (and show a progress bar) on a sequence of file paths as
+
+```python
+results = list(app.as_completed(["some_file_path.json", "some_other_file_path.json"], parallel=True, show_progress=True)
+```
+
+</details>
+
+<details>
+<summary>A contrived numerical example</summary>
+
+```python
+from scinexus import define_app
+
+
+@define_app
+def normalise(values: list[float]) -> list[float]:
+    lo, hi = min(values), max(values)
+    return [(v - lo) / (hi - lo) for v in values]
+
+@define_app
+def threshold(values: list[float]) -> list[bool]:
+    return [v > 0.5 for v in values]
+
+app = normalise() + threshold()
+app([1.0, 5.0, 3.0, 9.0])
+```
+
+</details>
+
+<details>
+<summary>A configurable app</summary>
+
+```python
+from scinexus import define_app
+
+
+@define_app(app_type="loader")
+def load_csv(path: str) -> list[dict]:
+    import csv
+
+    with open(path) as f:
+        return list(csv.DictReader(f))
+
+@define_app
+class summarise:
+    def __init__(self, column: str) -> None:
+        """column contains the values to produce summary stats for"""
+        self.column = column
+
+    def main(self, rows: list[dict]) -> dict[str, float]:
+        vals = [float(r[self.column]) for r in rows]
+        return {"mean": sum(vals) / len(vals), "min": min(vals), "max": max(vals)}
+
+app = load_csv() + summarise(column="price")
+```
+
+</details>
+
+## Features
+
+- Type checking at composition time
+- Durable computing -- failures recorded as `NotCompleted` records, not exceptions
+- Data-level parallel execution via `loky` or MPI
+- Progress bars (`tqdm` or `rich`)
+- Automated logging and citation tracking
+- Checkpointing via data stores (directory, SQLite)
+
+## Installation
+
+```bash
+pip install scinexus
+```
+
+## History
+
+The app framework and utility functions in `scinexus` incubated inside [cogent3](https://github.com/cogent3/cogent3) from March 2019, accumulating over five years of development, testing, and real-world use in computational genomics before being extracted into a standalone package. The design is mature and has underpinned analyses in published studies.
+
+The extraction into `scinexus` makes the infrastructure available to any scientific Python project, free of the `cogent3` dependency.
+
+We acknowledge here that many members of the `cogent3` community contributed to the code that now lives here, including [@rmcar17](https://github.com/rmcar17), [@Nick-Foto](https://github.com/Nick-Foto), [@KatherineCaley](https://github.com/KatherineCaley), [@fredjaya](https://github.com/fredjaya), and [@khiron](https://github.com/khiron).