Skip to content

Commit b6a63b3

Browse files
oestebanoesteban
committed
Document TemplateFlow cache management in CLI and API stubs
1 parent 7718e6a commit b6a63b3

File tree

7 files changed

+138
-5
lines changed

7 files changed

+138
-5
lines changed

‎.gitignore‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,6 @@ instance/
7373

7474
# Sphinx documentation
7575
docs/_build/
76-
docs/api/
7776

7877
# PyBuilder
7978
target/

‎docs/api/templateflow.api.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
templateflow.api module
2+
=======================
3+
4+
``templateflow.api`` mirrors the long-standing global helpers while delegating
5+
all heavy lifting to a shared :class:`templateflow.client.TemplateFlowClient`
6+
instance. The directives below document both the public functions and the
7+
proxied client so that migration guides can reference consistent API signatures.
8+
9+
.. automodule:: templateflow.api
10+
:members: get, ls, templates, get_metadata, get_citations, TemplateFlowClient
11+
:imported-members:
12+
:member-order: bysource

‎docs/api/templateflow.cli.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
templateflow.cli module
2+
=======================
3+
4+
.. automodule:: templateflow.cli
5+
:members:
6+
:undoc-members:
7+
:member-order: bysource

‎docs/api/templateflow.client.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
templateflow.client module
2+
==========================
3+
4+
The client module provides the object-oriented entry point around the global
5+
cache described in :mod:`templateflow.conf`. Its documentation surfaces the
6+
constructor, cache descriptor, and convenience methods so that downstream code
7+
can migrate from the module-level API to the richer class interface.
8+
9+
.. automodule:: templateflow.client
10+
:members: TemplateFlowClient
11+
:undoc-members:
12+
:member-order: bysource
13+
14+
.. autoclass:: templateflow.client.TemplateFlowClient
15+
:members:
16+
:special-members: __init__, __repr__
17+
:member-order: bysource
18+
:show-inheritance:

‎docs/api/templateflow.conf.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
templateflow.conf package
2+
=========================
3+
4+
``templateflow.conf`` centralizes configuration state for both the legacy module
5+
level helpers (``update``/``wipe``) and the newer :class:`~templateflow.conf.cache.TemplateFlowCache`
6+
object. The documentation below highlights the migration path so that users can
7+
incrementally adopt the cache classes without losing backwards-compatible entry
8+
points.
9+
10+
.. automodule:: templateflow.conf
11+
:members: requires_layout, setup_home, update, wipe
12+
:imported-members:
13+
:member-order: bysource
14+
15+
Cache management classes
16+
------------------------
17+
18+
.. automodule:: templateflow.conf.cache
19+
:members: CacheConfig, TemplateFlowCache, S3Manager, DataladManager
20+
:special-members: __init__
21+
:undoc-members:
22+
:member-order: bysource

‎docs/cli.rst‎

Lines changed: 63 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,66 @@ Examples
99
--------
1010
Listing all the compressed NIfTI files in ``fsaverage``::
1111

12-
$ templateflow ls fsaverage -x .nii.gz
13-
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz
14-
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz
15-
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz
12+
$ templateflow ls fsaverage -x .nii.gz
13+
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz
14+
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz
15+
~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz
16+
17+
Managing client configuration
18+
-----------------------------
19+
The ``templateflow`` CLI transparently manipulates the same cache configuration used
20+
by :class:`templateflow.client.TemplateFlowClient`. Running ``templateflow config``
21+
exposes the options stored in the underlying :class:`templateflow.conf.cache.CacheConfig`
22+
instance::
23+
24+
$ templateflow config show
25+
TEMPLATEFLOW_HOME=/home/user/.cache/templateflow
26+
TEMPLATEFLOW_USE_DATALAD=0
27+
TEMPLATEFLOW_AUTOUPDATE=1
28+
TEMPLATEFLOW_GET_TIMEOUT=10
29+
30+
Changing a value updates the cached client configuration immediately. For example,
31+
enabling the DataLad backend is equivalent to instantiating a client with
32+
``TemplateFlowClient(use_datalad=True)`` because the command mutates the
33+
``CacheConfig`` object used by the global client::
34+
35+
$ templateflow config set TEMPLATEFLOW_USE_DATALAD 1
36+
Updated TEMPLATEFLOW_USE_DATALAD → 1 (DataLad downloads will be used on next access)
37+
38+
When the CLI is invoked afterwards, the cache will be re-initialized using
39+
``use_datalad=True`` without requiring any additional Python code. The same
40+
mechanism applies to paths (``TEMPLATEFLOW_HOME``), origins, and timeout
41+
settings provided via ``templateflow config``.
42+
43+
Updating an existing cache
44+
--------------------------
45+
The :mod:`templateflow.conf` module exposes an ``update`` helper that the CLI
46+
mirrors through ``templateflow update``. Executing the command instructs the
47+
underlying :class:`templateflow.conf.cache.TemplateFlowCache` instance to refresh
48+
its content using the currently selected backend::
49+
50+
$ templateflow update --silent
51+
Cache mode: S3
52+
Cache root: /home/user/.cache/templateflow
53+
TemplateFlow cache is up to date
54+
55+
If ``TEMPLATEFLOW_USE_DATALAD`` (or ``--use-datalad``) is enabled, the command
56+
delegates to :class:`templateflow.conf.cache.DataladManager` and performs a
57+
recursive ``datalad update``. Otherwise the S3 manager fetches new or changed
58+
files while keeping existing downloads intact.
59+
60+
Wiping the cache
61+
----------------
62+
The ``templateflow wipe`` command is a thin wrapper around
63+
:meth:`templateflow.conf.cache.TemplateFlowCache.wipe`. It clears the local cache
64+
and invalidates the in-memory layout so that subsequent ``templateflow`` CLI
65+
calls or new :class:`templateflow.client.TemplateFlowClient` instances trigger a clean re-install::
66+
67+
$ templateflow wipe
68+
Removing cache at /home/user/.cache/templateflow …
69+
Cache cleared; next access will reinstall the archive
70+
71+
In DataLad mode the wipe operation reports that no deletion occurs because
72+
``TemplateFlowCache`` delegates to :class:`~templateflow.conf.cache.DataladManager`,
73+
preserving the working tree. This makes it safe to toggle between backends via
74+
``templateflow config`` without unintentionally removing a managed repository.

‎docs/datalad.rst‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,22 @@ Therefore, it is possible (and recommended for those who want to
55
leverage the power of DataLad) to access the Archive using just
66
DataLad.
77

8+
.. tip:: Prefer the Python client for routine access
9+
10+
The high-level :class:`templateflow.client.TemplateFlowClient` can be
11+
configured with ``use_datalad=True`` (or via ``templateflow config set
12+
TEMPLATEFLOW_USE_DATALAD 1``) to transparently manage the cache with
13+
DataLad. This is a good default when you want TemplateFlow to perform
14+
``datalad get`` and ``datalad update`` commands automatically while still
15+
interacting with the archive through the familiar client API.
16+
17+
.. note:: Drop down to raw DataLad when you need full control
18+
19+
Advanced workflows—such as pinning remotes, creating custom siblings, or
20+
operating entirely offline—are better served by running DataLad commands
21+
directly. In those scenarios leave ``use_datalad`` disabled in the client
22+
and use the instructions below to operate on the repository yourself.
23+
824
Installing the Archive
925
----------------------
1026
The archive is indexed by a superdataset, which can be installed with::

0 commit comments

Comments
 (0)