Merge pull request #1715 from oesteban/cli/version-checks

ENH: Add check for updates and check whether version has been flagged.

Author: effigies

.versions.json

@@ -0,0 +1,5 @@
+{
+	"flagged": {
+		"1.0.0": "Deprecated / too old"
+	}
+}

docs/faq_tips_tricks.rst renamed to docs/faq.rst

@@ -126,3 +126,23 @@ A symptomatic output looks like: ::
 
 If you would like to run *fMRIPrep* in parallel on multiple subjects please use
 `this method <https://neurostars.org/t/fmriprep-workaround-for-running-subjects-in-parallel/4449>`__.
+
+
+.. _upgrading:
+
+A new version of *fMRIPrep* has been published, when should I upgrade?
+----------------------------------------------------------------------
+
+We follow a philosophy of releasing very often, although the pace is slowing down
+with the maturation of the software.
+It is very likely that your version gets outdated over the extent of your study.
+If that is the case (an ongoing study), then we discourage changing versions.
+In other words, **the whole dataset should be processed with the same version (and
+same container build if they are being used) of *fMRIPrep*.**
+
+On the other hand, if the project is about to start, then we strongly recommend
+using the latest version of the tool.
+
+In any case, if you can find your release listed as *flagged* in `this file
+of our repo <https://github.com/poldracklab/fmriprep/blob/master/.versions.json>`__,
+then please update as soon as possible.

docs/index.rst

@@ -21,7 +21,7 @@ Contents
    sdc
    spaces
    outputs
-   faq_tips_tricks
+   faq
    contributors
    citing
    api/index.rst

fmriprep/cli/run.py

@@ -40,8 +40,10 @@ def get_parser():
     """Build parser object"""
     from smriprep.cli.utils import ParseTemplates, output_space as _output_space
     from templateflow.api import templates
+    from packaging.version import Version
     from ..__about__ import __version__
     from ..workflows.bold.resampling import NONSTANDARD_REFERENCES
+    from .version import check_latest, is_flagged
 
     verstr = 'fmriprep v{}'.format(__version__)
 
@@ -274,6 +276,25 @@ def get_parser():
     g_other.add_argument('--sloppy', action='store_true', default=False,
                          help='Use low-quality tools for speed - TESTING ONLY')
 
+    currentv = Version(__version__)
+    latest = check_latest()
+
+    if latest is not None and currentv < latest:
+        print("""\
+You are using fMRIPrep-%s, and a newer version of fMRIPrep is available: %s.
+Please check out our documentation about how and when to upgrade:
+https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading""" % (
+            __version__, latest), file=sys.stderr)
+
+    _blist = is_flagged()
+    if _blist[0]:
+        _reason = _blist[1] or 'unknown'
+        print("""\
+WARNING: Version %s of fMRIPrep (current) has been FLAGGED
+(reason: %s).
+That means some severe flaw was found in it and we strongly
+discourage its usage.""" % (__version__, _reason), file=sys.stderr)
+
     return parser
 
 
@@ -283,7 +304,6 @@ def main():
     from multiprocessing import set_start_method, Process, Manager
     from ..utils.bids import write_derivative_description, validate_input_dir
     set_start_method('forkserver')
-
     warnings.showwarning = _warn_redirect
     opts = get_parser().parse_args()
 

fmriprep/cli/tests/__init__.py

@@ -0,0 +1,51 @@
+"""Test CLI."""
+from packaging.version import Version
+import pytest
+from .. import version as _version
+from ... import __about__
+from ..run import get_parser
+
+
+@pytest.mark.parametrize(('current', 'latest'), [
+    ('1.0.0', '1.3.2'),
+    ('1.3.2', '1.3.2')
+])
+def test_get_parser_update(monkeypatch, capsys, current, latest):
+    """Make sure the out-of-date banner is shown."""
+    expectation = Version(current) < Version(latest)
+
+    def _mock_check_latest(*args, **kwargs):
+        return Version(latest)
+
+    monkeypatch.setattr(__about__, '__version__', current)
+    monkeypatch.setattr(_version, 'check_latest', _mock_check_latest)
+
+    get_parser()
+    captured = capsys.readouterr().err
+
+    msg = """\
+You are using fMRIPrep-%s, and a newer version of fMRIPrep is available: %s.
+Please check out our documentation about how and when to upgrade:
+https://fmriprep.readthedocs.io/en/latest/faq.html#upgrading""" % (current, latest)
+
+    assert (msg in captured) is expectation
+
+
+@pytest.mark.parametrize('flagged', [
+    (True, None),
+    (True, 'random reason'),
+    (False, None),
+])
+def test_get_parser_blacklist(monkeypatch, capsys, flagged):
+    """Make sure the blacklisting banner is shown."""
+    def _mock_is_bl(*args, **kwargs):
+        return flagged
+
+    monkeypatch.setattr(_version, 'is_flagged', _mock_is_bl)
+
+    get_parser()
+    captured = capsys.readouterr().err
+
+    assert ('FLAGGED' in captured) is flagged[0]
+    if flagged[0]:
+        assert ((flagged[1] or 'reason: unknown') in captured)

fmriprep/cli/tests/test_run.py

@@ -0,0 +1,163 @@
+"""Test version checks."""
+from datetime import datetime
+from pathlib import Path
+from packaging.version import Version
+import pytest
+from .. import version as _version
+from ..version import check_latest, DATE_FMT, requests, is_flagged
+
+
+class MockResponse:
+    """Mocks the requests module so that Pypi is not actually queried."""
+
+    status_code = 200
+    _json = {
+        "releases": {
+            '1.0.0': None,
+            '1.0.1': None,
+            '1.1.0': None,
+            '1.1.1rc1': None
+        }
+    }
+
+    def __init__(self, code=200, json=None):
+        """Allow setting different response codes."""
+        self.status_code = code
+        if json is not None:
+            self._json = json
+
+    def json(self):
+        """Redefine the response object."""
+        return self._json
+
+
+def test_check_latest1(tmpdir, monkeypatch):
+    """Test latest version check."""
+    tmpdir.chdir()
+    monkeypatch.setenv('HOME', str(tmpdir))
+    assert str(Path.home()) == str(tmpdir)
+
+    def mock_get(*args, **kwargs):
+        return MockResponse()
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    # Initially, cache should not exist
+    cachefile = Path.home() / '.cache' / 'fmriprep' / 'latest'
+    assert not cachefile.exists()
+
+    # First check actually fetches from pypi
+    v = check_latest()
+    assert cachefile.exists()
+    assert isinstance(v, Version)
+    assert v == Version('1.1.0')
+    assert cachefile.read_text().split('|') == [str(v), datetime.now().strftime(DATE_FMT)]
+
+    # Second check - test the cache file is read
+    cachefile.write_text('|'.join(('1.0.0', cachefile.read_text().split('|')[1])))
+    v = check_latest()
+    assert isinstance(v, Version)
+    assert v == Version('1.0.0')
+
+    # Third check - forced oudating of cache
+    cachefile.write_text('2.0.0|20180121')
+    v = check_latest()
+    assert isinstance(v, Version)
+    assert v == Version('1.1.0')
+
+    # Mock timeouts
+    def mock_get(*args, **kwargs):
+        raise requests.exceptions.Timeout
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    cachefile.write_text('|'.join(('1.0.0', cachefile.read_text().split('|')[1])))
+    v = check_latest()
+    assert isinstance(v, Version)
+    assert v == Version('1.0.0')
+
+    cachefile.write_text('2.0.0|20180121')
+    v = check_latest()
+    assert v is None
+
+    cachefile.unlink()
+    v = check_latest()
+    assert v is None
+
+
+@pytest.mark.parametrize(('result', 'code', 'json'), [
+    (None, 404, None),
+    (None, 200, {'releases': {'1.0.0rc1': None}}),
+    (Version('1.1.0'), 200, None),
+    (Version('1.0.0'), 200, {'releases': {'1.0.0': None}}),
+])
+def test_check_latest2(tmpdir, monkeypatch, result, code, json):
+    """Test latest version check with varying server responses."""
+    tmpdir.chdir()
+    monkeypatch.setenv('HOME', str(tmpdir))
+    assert str(Path.home()) == str(tmpdir)
+
+    def mock_get(*args, **kwargs):
+        return MockResponse(code=code, json=json)
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    v = check_latest()
+    if result is None:
+        assert v is None
+    else:
+        assert isinstance(v, Version)
+        assert v == result
+
+
+@pytest.mark.parametrize('bad_cache', [
+    '3laj#r???d|3akajdf#',
+    '2.0.0|3akajdf#',
+    '|'.join(('2.0.0', datetime.now().strftime(DATE_FMT), '')),
+    ''
+])
+def test_check_latest3(tmpdir, monkeypatch, bad_cache):
+    """Test latest version check when the cache file is corrupted."""
+    tmpdir.chdir()
+    monkeypatch.setenv('HOME', str(tmpdir))
+    assert str(Path.home()) == str(tmpdir)
+
+    def mock_get(*args, **kwargs):
+        return MockResponse()
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    # Initially, cache should not exist
+    cachefile = Path.home() / '.cache' / 'fmriprep' / 'latest'
+    cachefile.parent.mkdir(parents=True, exist_ok=True)
+    assert not cachefile.exists()
+
+    cachefile.write_text(bad_cache)
+    v = check_latest()
+    assert isinstance(v, Version)
+    assert v == Version('1.1.0')
+
+
+@pytest.mark.parametrize(('result', 'version', 'code', 'json'), [
+    (False, '1.2.1', 200, {'flagged': {'1.0.0': None}}),
+    (True, '1.2.1', 200, {'flagged': {'1.2.1': None}}),
+    (True, '1.2.1', 200, {'flagged': {'1.2.1': 'FATAL Bug!'}}),
+    (False, '1.2.1', 404, {'flagged': {'1.0.0': None}}),
+    (False, '1.2.1', 200, {'flagged': []}),
+    (False, '1.2.1', 200, {}),
+])
+def test_is_flagged(monkeypatch, result, version, code, json):
+    """Test that the flagged-versions check is correct."""
+    monkeypatch.setattr(_version, "__version__", version)
+
+    def mock_get(*args, **kwargs):
+        return MockResponse(code=code, json=json)
+    monkeypatch.setattr(requests, "get", mock_get)
+
+    val, reason = is_flagged()
+    assert val is result
+
+    test_reason = None
+    if val:
+        test_reason = json.get('flagged', {}).get(version, None)
+
+    if test_reason is not None:
+        assert reason == test_reason
+    else:
+        assert reason is None

fmriprep/cli/tests/test_version.py

@@ -0,0 +1,77 @@
+# emacs: -*- mode: python; py-indent-offset: 4; indent-tabs-mode: nil -*-
+# vi: set ft=python sts=4 ts=4 sw=4 et:
+"""Version CLI helpers."""
+
+from pathlib import Path
+from datetime import datetime
+import requests
+from .. import __version__
+
+RELEASE_EXPIRY_DAYS = 14
+DATE_FMT = '%Y%m%d'
+
+
+def check_latest():
+    """Determine whether this is the latest version."""
+    from packaging.version import Version, InvalidVersion
+
+    latest = None
+    date = None
+    outdated = None
+    cachefile = Path.home() / '.cache' / 'fmriprep' / 'latest'
+    cachefile.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        latest, date = cachefile.read_text().split('|')
+    except Exception:
+        pass
+    else:
+        try:
+            latest = Version(latest)
+            date = datetime.strptime(date, DATE_FMT)
+        except (InvalidVersion, ValueError):
+            latest = None
+        else:
+            if abs((datetime.now() - date).days) > RELEASE_EXPIRY_DAYS:
+                outdated = True
+
+    if latest is None or outdated is True:
+        try:
+            response = requests.get(url='https://pypi.org/pypi/fmriprep/json', timeout=1.0)
+        except Exception:
+            response = None
+
+        if response and response.status_code == 200:
+            versions = [Version(rel) for rel in response.json()['releases'].keys()]
+            versions = [rel for rel in versions if not rel.is_prerelease]
+            if versions:
+                latest = sorted(versions)[-1]
+        else:
+            latest = None
+
+    if latest is not None:
+        try:
+            cachefile.write_text('|'.join(('%s' % latest, datetime.now().strftime(DATE_FMT))))
+        except Exception:
+            pass
+
+    return latest
+
+
+def is_flagged():
+    """Check whether current version is flagged."""
+    # https://raw.githubusercontent.com/poldracklab/fmriprep/master/.versions.json
+    flagged = tuple()
+    try:
+        response = requests.get(url="""\
+https://raw.githubusercontent.com/poldracklab/fmriprep/master/.versions.json""", timeout=1.0)
+    except Exception:
+        response = None
+
+    if response and response.status_code == 200:
+        flagged = response.json().get('flagged', {}) or {}
+
+    if __version__ in flagged:
+        return True, flagged[__version__]
+
+    return False, None