Template for packaging spinalcordtoolbox datasets in pip.

.github/workflows/build.yml

@@ -0,0 +1,24 @@
+name: Test the Build
+
+on:
+  # test on PRs and double-test on merges to master, or manually.
+  pull_request:
+  push:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+    - name: Build tools
+      run: |
+          python -m pip install --upgrade pip
+          pip install build
+    - name: Build
+      run: |
+          python -m build --wheel --sdist

.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Publish
+
+on:
+  # publish from the Releases page:
+  release:
+    types: [published]
+  # publish from the Actions page:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version (e.g. 2.0.3)'
+        required: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python
+      uses: actions/setup-python@v1
+    - name: Build tools
+      run: |
+          python -m pip install --upgrade pip
+          pip install build
+    - name: Build
+      run: |
+          python -m build --wheel --sdist
+    ### TODO: can the uploads be parallelized?
+    - name: Publish to Github
+      uses: softprops/action-gh-release@v1
+      with:
+        files: 'dist/*'
+        fail_on_unmatched_files: true
+        tag_name: ${{ github.event.inputs.version }} # in the workflow_dispatch case, make a new tag from the given input; in the published release case, this will be empty and will fall back to updating that release.
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        #password: ${{ secrets.PYPI_PASSWORD }}
+        # DEBUG:
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+        repository_url: https://test.pypi.org/legacy/

.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+
+*.whl
+*.egg-info
+__pycache__

README.md

@@ -0,0 +1,41 @@
+# <dataset> template
+
+Part of [`spinalcordtoolbox`](https://github.com/neuropoly/spinalcordtoolbox).
+
+
+## Usage
+
+1. Clone this repo.
+
+    ```
+    git mv src/spinalcordtoolbox/data/dataset src/spinalcordtoolbox/data/${dataset-name} 
+    cp ${data_files} src/spinalcordtoolbox/data/${dataset_name} 
+    vi setup.py # to edit name= and url=
+    vi README.md # to edit the title and *remove* this usage section
+    git add .
+    git commit
+    git remote add origin git@github.com:neuropoly/spinalcordtoolbox-data-${dataset_name}
+    git push
+    ```
+
+2. Go to https://github.com/neuropoly/spinalcordtoolbox-data-${dataset_name}/releases
+
+    1. Click "Draft Release"
+    2. Fill in a version tag. We use [this versioning policy](TODO)
+    3. Click "Publish Release"
+    4. Wait a few minutes;
+    5. Monitor the progress at https://github.com/neuropoly/spinalcordtoolbox-data-${dataset_name}/actions/workflows/release.yml
+    6. The release should appear on https://github.com/neuropoly/spinalcordtoolbox-data-${dataset_name}/releases
+       with the .tar.gz (sdist) and .whl (wheel) formats attached momentarily.
+
+### Troubleshooting
+
+You can test the repo locally with
+
+```
+pip install build &&
+python -m build --wheel --sdist &&
+pip install dist/*.whl
+```
+
+This should give you enough clues hopefully to track down any problems.

pyproject.toml

@@ -0,0 +1,3 @@
+# this ensures builds are done reliably
+[build-system]
+requires = ["setuptools>=40.8.0", "setuptools_scm[toml]", "wheel"]

setup.py

@@ -0,0 +1,44 @@
+from setuptools import setup, find_packages, find_namespace_packages
+import pathlib
+
+here = pathlib.Path(__file__).parent.resolve()
+
+# workaround a bug introduced by pyproject.toml
+# https://github.com/pypa/pip/issues/7953#issuecomment-645133255
+import site, sys; site.ENABLE_USER_SITE = True
+
+setup(
+  name='spinalcordtoolbox-data-<dataset>',
+  description='Part of https://github.com/neuropoly/spinalcordtoolbox',
+  long_description=(here / 'README.md').read_text(encoding='utf-8'),
+  long_description_content_type='text/markdown',
+  author='Neuropoly',
+  author_email='neuropoly@googlegroups.com',
+  url='https://spinalcordtoolbox.com/',
+  project_urls={
+      'Source': 'https://github.com/sct-data/<dataset>',
+      #'Documentation': '',
+  },
+  #license='CC-BY-NC', ??
+  #license_files=[ ... ] # TODO?
+
+  packages=find_namespace_packages('src/'),
+  package_dir={"":"src/"},
+
+  # with setuptools_scm, means it includes non-python files if they're under git
+  include_package_data=True,
+
+  # with setuptools_scm, get the version out of the most recent git tag.
+  # the tags must be formatted as semver.
+  use_scm_version=True,
+
+  # pyproject.toml::build-system.requires is supposed to supersede this, but it's still very new so we duplicate it.
+  setup_requires=[
+    'setuptools',
+    'setuptools_scm[toml]',
+    'wheel',
+  ],
+
+  zip_safe=False, # guarantees that importlib.resources.path() is safe
+)
+

src/spinalcordtoolbox/data/dataset/__init__.py

@@ -0,0 +1,2 @@
+# empty __init__.py to enable importlib.resources
+# see < TODO >