Merge branch 'main' into enh/renamer

.coveragerc

@@ -0,0 +1,4 @@
+[run]
+branch = True
+omit =
+    */_version.py

.flake8

@@ -0,0 +1,15 @@
+
+[flake8]
+doctests = True
+exclude =
+    **/__init__.py
+    *build/
+    docs/sphinxext/
+    docs/tools/
+    docs/conf.py
+    docs/source/conf.py
+max-line-length = 88
+select = C,E,F,W,B,B950
+extend-ignore = E203,E501,E129,W503
+per-file-ignores =
+    __init__.py:F401,F403

.github/workflows/pythonpackage.yaml

@@ -0,0 +1,114 @@
+#This workflow will install Python dependencies, run tests and lint with a variety of Python versions
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+# For deployment, it will be necessary to create a PyPI API token and store it as a secret
+# https://docs.github.com/en/actions/reference/encrypted-secrets
+
+name: Python package
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ '*' ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  devcheck:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.7, '3.10']  # Check oldest and newest versions
+        pip-flags: ['', '--editable']
+        pydra:
+        - 'pydra'
+        - '--editable git+https://github.com/nipype/pydra.git#egg=pydra'
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+    - name: Install Pydra
+      run: |
+        pip install ${{ matrix.pydra }}
+        python -c "import pydra as m; print(f'{m.__name__} {m.__version__} @ {m.__file__}')"
+    - name: Install task package
+      run: |
+        pip install ${{ matrix.pip-flags }} ".[dev]"
+        python -c "import pydra.tasks.CHANGEME as m; print(f'{m.__name__} {m.__version__} @ {m.__file__}')"
+        python -c "import pydra as m; print(f'{m.__name__} {m.__version__} @ {m.__file__}')"
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.7, 3.8, 3.9, '3.10']
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install build dependencies
+      run: |
+        python -m pip install --upgrade pip
+    - name: Install task package
+      run: |
+        pip install ".[test]"
+        python -c "import pydra.tasks.CHANGEME as m; print(f'{m.__name__} {m.__version__} @ {m.__file__}')"
+        python -c "import pydra as m; print(f'{m.__name__} {m.__version__} @ {m.__file__}')"
+    - name: Test with pytest
+      run: |
+        pytest -sv --doctest-modules pydra/tasks/CHANGEME \
+            --cov pydra.tasks.CHANGEME --cov-report xml
+    - uses: codecov/codecov-action@v3
+      if: ${{ always() }}
+
+
+  deploy:
+    needs: [devcheck, test]
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.9]
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        submodules: recursive
+        fetch-depth: 0
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install build tools
+      run: python -m pip install build twine
+    - name: Build source and wheel distributions
+      run: python -m build
+    - name: Check distributions
+      run: twine check dist/*
+    - uses: actions/upload-artifact@v3
+      with:
+        name: distributions
+        path: dist/
+    # Deploy on tags if PYPI_API_TOKEN is defined in the repository secrets.
+    # Secrets are not accessible in the if: condition [0], so set an output variable [1]
+    # [0] https://github.community/t/16928
+    # [1] https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-output-parameter
+    - name: Check for PyPI token on tag
+      id: deployable
+      if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
+      env:
+        PYPI_API_TOKEN: "${{ secrets.PYPI_API_TOKEN }}"
+      run: if [ -n "$PYPI_API_TOKEN" ]; then echo "DEPLOY=true" >> $GITHUB_OUTPUT; fi
+    - name: Upload to PyPI
+      if: steps.deployable.outputs.DEPLOY
+      uses: pypa/gh-action-pypi-publish@37f50c210e3d2f9450da2cd423303d6a14a6e29f  # v1.5.1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_API_TOKEN }}

.gitignore

@@ -133,3 +133,9 @@ dmypy.json
 
 # Vim
 .*.sw[op]
+
+# VS Code
+.vscode
+
+# Mac garbarge
+.DS_store

.pre-commit-config.yaml

@@ -2,13 +2,13 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.0.0
+    rev: v4.4.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
     -   id: check-added-large-files
 -   repo: https://github.com/psf/black
-    rev: 19.3b0
+    rev: 22.12.0
     hooks:
     -   id: black

LICENSE

@@ -1,4 +1,4 @@
-   Copyright 2020 Nipype developers
+   Copyright 2021 Nipype developers
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -8,33 +8,43 @@ All tasks will be inserted into the `pydra.tasks.<yourtaskpackagename>` namespac
 1. Click on new repo.
 1. Select this template from the repository template drop down list.
 1. Give your repo a name.
-1. Once the repo is created and cloned, search for TODO (`grep -rn TODO . `) and
+1. Once the repo is created and cloned, search for CHANGEME (`grep -rn CHANGEME . `) and
    replace with appropriate name.
-1. One of the folders is called TODO. This should also be renamed to your package
+1. One of the folders is called CHANGEME. This should also be renamed to your package
    name.
-1. Add tasks to the `pydra/tasks/<yourpackagename>` folder.
-1. An example subpackage is found in `pydra/tasks/<yourpackagename>/utils`.
-   You may wish to add tools to it or delete it.
+1. Under the newly renamed package (i.e. formerly CHANGEME) there is a directory named "v1",
+   `pydra/tasks/<package-name>/v1`, change this to valid Python package name starting with
+   'v' to indicate the version of the tool the Pydra interfaces will be designed for,
+   e.g. FSL v6.0.2 could be `pydra/tasks/fsl/v6` or `pydra/tasks/fsl/v6_0` depending on
+   how stable the CLI of the tool is between minor versions.
+1. Edit `pydra/tasks/<package-name>/latest.py` to update references to `v1` to the
+   tool target version
+1. Add tasks to the `pydra/tasks/<package-name>/v<package-version>` folder.
 1. You may want to initialize a [Sphinx] docs directory.
+1. Review the workflow in `.github/workflows/pythonpackage.yml`. Testing editable installations
+   is probably not useful unless you are reconfiguring namespace packages.
 1. **Update this README after creating the new repository.**
 
 [Sphinx]: https://www.sphinx-doc.org/en/master/usage/quickstart.html
 
 # Features of this template
 
-## Versioneer
+## Tag-based versioning
 
-The [versioneer](https://github.com/warner/python-versioneer) tool allows for versioning based
+The [setuptools_scm](https://github.com/pypa/setuptools_scm) tool allows for versioning based
 on the most recent git tag. The release process can thus be:
 
 ```Shell
 git tag -a 1.0.0
-python setup.py sdist bdist_wheel
+python -m build
 twine upload dist/*
 ```
 
-Note that we assume tags will be version numbers and not be prefixed with `v` or some other
-string. See Versioneer documentation for alternative configurations.
+Note that uploading to PyPI is done via [Continuous integration](#continuous-integration)) when
+a tag is pushed to the repository, so only the first step needs to be donne manually.
+
+Note also that we assume tags will be version numbers and not be prefixed with `v` or some other
+string. See `setuptools_scm` documentation for alternative configurations.
 
 ## Namespace packages
 
@@ -70,6 +80,10 @@ non-compliant package can potentially affect Pydra or other task packages.
 In addition to verifying installations do not break or conflict, pytest is run on the package,
 including all tests found in `test/` directories and [doctests].
 
+Finally, packages are built and uploaded as artifacts for inspection. When a tag is pushed,
+the packages are uploaded to PyPI if a valid [API token](https://pypi.org/help/#apitoken) is placed
+in the [repository secrets](https://docs.github.com/en/actions/reference/encrypted-secrets).
+
 [doctests]: https://docs.python.org/3/library/doctest.html
 
 # Contributing to this template
@@ -83,7 +97,7 @@ task packages.
 ## For developers
 
 Install repo in developer mode from the source directory. It is also useful to
-install pre-commit to take care of styling via black:
+install pre-commit to take care of styling via [black](https://black.readthedocs.io/):
 
 ```
 pip install -e .[dev]

codecov.yml

@@ -0,0 +1,12 @@
+coverage:
+  range: "50...100"
+  ignore:          # files and folders that will be removed during processing
+    - "**/tests"
+    - "**/_version.py"
+  status:
+    project:
+      default:
+        threshold: 1
+    patch:
+      default:
+        target: 80

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,51 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pydra-CHANGEME"
+copyright = "2020, Xihe Xie"
+author = "Xihe Xie"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,15 @@
+Welcome to pydra-CHANGEME's documentation!
+=========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`