Initial merge

.github/workflows/check-apis.yml

@@ -0,0 +1,42 @@
+name: check-apis
+
+# A weekly canary against the live IMGT and OGRDB APIs. It runs the same code a
+# user's download would, using the endpoint constants the sources define, so a
+# red run here is the early warning that an upstream API changed shape. It never
+# blocks a merge; it only watches. workflow_dispatch allows an on-demand check.
+on:
+  schedule:
+    - cron: "0 6 * * 1"   # Mondays, 06:00 UTC
+  workflow_dispatch:
+
+concurrency:
+  group: check-apis
+  cancel-in-progress: true
+
+jobs:
+  probe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+      - name: Probe the reference APIs
+        env:
+          SOURCERER_LIVE: '1'
+        run: python -m unittest tests.test_live -v
+      # On failure the run goes red and GitHub notifies the watchers. Opening an
+      # issue automatically is intentionally left off; enable the step below if a
+      # tracked issue is wanted instead of (or as well as) the email.
+      #
+      # - name: Open an issue on failure
+      #   if: failure()
+      #   uses: JasonEtco/create-an-issue@v2
+      #   env:
+      #     GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      #   with:
+      #     filename: .github/api-breakage-issue.md

.github/workflows/ci.yml

@@ -0,0 +1,101 @@
+name: CI
+
+on:
+  push:
+    branches: ["master", "dev"]
+  pull_request:
+    branches: ["master", "dev"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  min-deps:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install minimum dependencies
+        run: |
+          python -m pip install --upgrade pip
+          sed "s/[<>]/=/" requirements.txt > requirements_min.txt
+          pip install -r requirements_min.txt
+      - name: Install package
+        run: pip install .
+      - name: Unit tests
+        run: python -m unittest discover -v
+
+  python-versions:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+      - name: Unit tests
+        run: python -m unittest discover -v
+
+  # Proves that the packaged schema snapshots and the runtime dependencies both
+  # ship in the wheel. Running from /tmp guarantees the source tree cannot be
+  # picked up instead of the installed package.
+  wheel:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Build the wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build --wheel
+      - name: Install the wheel into a clean environment
+        run: |
+          python -m venv /tmp/clean
+          /tmp/clean/bin/pip install dist/*.whl
+      - name: Run from outside the source tree
+        working-directory: /tmp
+        run: /tmp/clean/bin/sourcerer --version
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.14'
+      - name: Install ruff
+        run: pip install ruff
+      - name: Lint
+        run: ruff check .
+
+  # Builds with -W so that a broken cross-reference, or autoprogram failing to
+  # import sourcerer.Cli:getArgParser(), fails CI instead of only showing up
+  # once the docs are published.
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install package and doc dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          pip install -r docs/doc_requires.txt
+      - name: Build docs
+        run: sphinx-build -W -b html docs docs/_build/html

.gitignore

@@ -0,0 +1,25 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+docs/_build/
+dist/
+.venv/
+venv/
+.history/
+.ruff_cache/
+.pytest_cache/
+
+# Raw upstream payloads cached by `schema refresh --keep-raw`; never committed.
+*.raw.json
+
+# Nextflow run artifacts (created by running airrflow locally)
+.nextflow/
+.nextflow.log*
+work/
+airrflow.config
+
+# Local and temporary files
+*.code-workspace
+*\.local\.*
+tmp/

.readthedocs.yaml

@@ -0,0 +1,21 @@
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+
+# We recommend specifying your dependencies to enable reproducible builds:
+# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+  - method: pip
+    path: .
+  - requirements: docs/doc_requires.txt

INSTALL.rst

@@ -0,0 +1,50 @@
+Installation
+================================================================================
+
+``sourcerer`` is not yet published on PyPI (the name is already taken by an
+unrelated package). Until that is resolved, install directly from GitHub or
+from a local checkout.
+
+The current development build can be installed using pip and git::
+
+    > pip3 install git+https://github.com/immcantation/sourcerer@master --user
+
+If you currently have a development version installed, then you will likely
+need to add the arguments ``--upgrade --no-deps --force-reinstall`` to the
+pip3 command.
+
+To install from a local checkout instead::
+
+    > git clone https://github.com/immcantation/sourcerer
+    > cd sourcerer
+    > pip3 install . --user
+
+For development, install in editable mode with the ``dev`` extra, which adds
+``ruff``::
+
+    > pip3 install -e ".[dev]"
+
+Requirements
+--------------------------------------------------------------------------------
+
++  `Python 3.11 <https://python.org>`__
++  `requests 2.28 <https://requests.readthedocs.io>`__
++  `beautifulsoup4 4.11 <https://www.crummy.com/software/BeautifulSoup>`__
++  `PyYAML 6.0 <https://pyyaml.org>`__
++  `pandas 2.2.3 <https://pandas.pydata.org>`__
++  `airr 2.0 <https://airr-standards.readthedocs.io>`__
++  `tqdm 4.64 <https://tqdm.github.io>`__
+
+All of the above are installed automatically by pip; there is nothing to
+install by hand.
+
+Optional
+--------------------------------------------------------------------------------
+
+``sourcerer`` itself has no dependency on Nextflow or Docker. They are only
+needed to run the ``nf-core/airrflow`` pipeline on the samplesheets
+``sourcerer`` writes:
+
++  `Nextflow <https://www.nextflow.io>`__
++  `Docker <https://www.docker.com>`__ or another Nextflow-supported container
+   engine