Merge branch 'main' into enh/renamer

Author: tclose

.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

.gitattributes

@@ -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 }}

.github/workflows/pythonpackage.yaml

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

.github/workflows/pythonpackage.yml

@@ -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

.gitignore

@@ -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.

.pre-commit-config.yaml

@@ -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]