Merge pull request #91 from templateflow/enh/wipe-cache-feature

ENH: Add a ``wipe()`` utility to clear up the cache

Author: oesteban

templateflow/conf/__init__.py

@@ -19,43 +19,52 @@
 TF_CACHED = True
 
 
+def _init_cache():
+    global TF_HOME, TF_CACHED, TF_USE_DATALAD
+
+    if not TF_HOME.exists() or not list(TF_HOME.iterdir()):
+        TF_CACHED = False
+        warn(
+            f"""\
+TemplateFlow: repository not found at <{TF_HOME}>. Populating a new TemplateFlow stub.
+If the path reported above is not the desired location for TemplateFlow, \
+please set the TEMPLATEFLOW_HOME environment variable.""",
+            ResourceWarning,
+        )
+        if TF_USE_DATALAD:
+            try:
+                from datalad.api import install
+            except ImportError:
+                TF_USE_DATALAD = False
+            else:
+                TF_HOME.parent.mkdir(exist_ok=True, parents=True)
+                install(path=str(TF_HOME), source=TF_GITHUB_SOURCE, recursive=True)
+
+        if not TF_USE_DATALAD:
+            from ._s3 import update as _update_s3
+
+            _update_s3(TF_HOME, local=True, overwrite=True)
+
+
+_init_cache()
+
+
 def requires_layout(func):
     """Decorate function to ensure ``TF_LAYOUT`` is correctly initiated."""
+
     @wraps(func)
     def wrapper(*args, **kwargs):
         from templateflow.conf import TF_LAYOUT
 
         if TF_LAYOUT is None:
             from bids import __version__
-            raise RuntimeError(f"A layout with PyBIDS <{__version__}> could not be initiated")
-        return func(*args, **kwargs)
-    return wrapper
-
 
-if not TF_HOME.exists() or not list(TF_HOME.iterdir()):
-    TF_CACHED = False
-    warn(
-        """\
-TemplateFlow: repository not found at %s. Populating a new TemplateFlow stub.
-If the path reported above is not the desired location for TemplateFlow, \
-please set the TEMPLATEFLOW_HOME environment variable.\
-"""
-        % TF_HOME,
-        ResourceWarning,
-    )
-    if TF_USE_DATALAD:
-        try:
-            from datalad.api import install
-        except ImportError:
-            TF_USE_DATALAD = False
-        else:
-            TF_HOME.parent.mkdir(exist_ok=True, parents=True)
-            install(path=str(TF_HOME), source=TF_GITHUB_SOURCE, recursive=True)
-
-    if not TF_USE_DATALAD:
-        from ._s3 import update as _update_s3
+            raise RuntimeError(
+                f"A layout with PyBIDS <{__version__}> could not be initiated"
+            )
+        return func(*args, **kwargs)
 
-        _update_s3(TF_HOME, local=True, overwrite=True)
+    return wrapper
 
 
 def update(local=False, overwrite=True, silent=False):
@@ -64,6 +73,7 @@ def update(local=False, overwrite=True, silent=False):
         success = True
     else:
         from ._s3 import update as _update_s3
+
         success = _update_s3(TF_HOME, local=local, overwrite=overwrite, silent=silent)
 
     # update Layout only if necessary
@@ -72,10 +82,37 @@ def update(local=False, overwrite=True, silent=False):
         # ensure the api uses the updated layout
         import importlib
         from .. import api
+
         importlib.reload(api)
     return success
 
 
+def wipe():
+    """Clear the cache if functioning in S3 mode."""
+    global TF_USE_DATALAD, TF_HOME
+
+    if TF_USE_DATALAD:
+        print("TemplateFlow is configured in DataLad mode, wipe() has no effect")
+        return
+
+    import importlib
+    from shutil import rmtree
+    from templateflow import api
+
+    def _onerror(func, path, excinfo):
+        from pathlib import Path
+
+        if Path(path).exists():
+            print(
+                f"Warning: could not delete <{path}>, please clear the cache manually."
+            )
+
+    rmtree(TF_HOME, onerror=_onerror)
+    _init_cache()
+
+    importlib.reload(api)
+
+
 def setup_home(force=False):
     """Initialize/update TF's home if necessary."""
     if not force and not TF_CACHED: