Skip to content

Commit 0591437

Browse files
oestebanoesteban
committed
docs: reorganize settings guidance
1 parent 7718e6a commit 0591437

File tree

1 file changed

+125
-32
lines changed

1 file changed

+125
-32
lines changed

‎docs/installation.rst‎

Lines changed: 125 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -18,38 +18,131 @@ You should see the version number.
1818

1919
Settings
2020
--------
21-
The *TemplateFlow Client* has two modes of operation: (a) based on
22-
`DataLad <https://datalad.org>`__, or (b) direct downloads from Amazon S3.
23-
24-
By default, the client will operate in direct download mode (b) which is
25-
more lightweight and comes with some limitations, as all the advanced
26-
version control management afforded by DataLad will not be available.
27-
28-
For the most part, and considering that templates/atlases do not substantially
29-
change over time, the direct download mode should be sufficient to anyone
30-
developing new pipelines and tools, as it will provided the latest version
31-
of any available template set.
32-
33-
**TemplateFlow "home" folder**.
34-
The lazy-loading implementation of the client requires some folder on the host
35-
where template resources can be stored (therefore, write permissions are
36-
required). By default, the home folder will be ``$HOME/.cache/templateflow``.
37-
This setting can be overridden by defining the environment variable ``TEMPLATEFLOW_HOME``
38-
before running the client, for example::
39-
40-
$ export TEMPLATEFLOW_HOME=$DATA/.templateflow
41-
42-
**Configuring the operation mode**.
43-
By default, the client will operate without DataLad (and hence, without version control).
44-
To set up the DataLad mode, make sure DataLad is installed and functioning on your host,
45-
and then::
46-
47-
$ export TEMPLATEFLOW_USE_DATALAD=on
48-
49-
It is recommended that the ``$TEMPLATEFLOW_HOME`` folder is wiped out before running the
50-
client again, in case the tool has already been operated in direct download mode::
51-
52-
$ rm -r ${TEMPLATEFLOW_HOME:-$HOME/.cache/templateflow}
21+
``TemplateFlowClient`` is the central entry point for configuring how the
22+
archive is cached and updated. Each constructor argument mirrors an
23+
environment variable (when available) and exposes its live value through the
24+
metadata descriptors defined in :mod:`templateflow.conf`.
25+
26+
.. list-table:: ``TemplateFlowClient`` configuration
27+
:header-rows: 1
28+
29+
* - Argument
30+
- Environment variable
31+
- Default
32+
- Metadata descriptor
33+
* - ``root``
34+
- ``TEMPLATEFLOW_HOME``
35+
- ``platformdirs.user_cache_dir('templateflow')`` (e.g., ``~/.cache/templateflow``)
36+
- ``templateflow.conf.TF_HOME``
37+
* - ``use_datalad``
38+
- ``TEMPLATEFLOW_USE_DATALAD``
39+
- ``False`` (automatically disabled if DataLad is not installed)
40+
- ``templateflow.conf.TF_USE_DATALAD``
41+
* - ``autoupdate``
42+
- ``TEMPLATEFLOW_AUTOUPDATE``
43+
- ``True``
44+
- ``templateflow.conf.TF_AUTOUPDATE``
45+
* - ``timeout``
46+
- *(none)*
47+
- ``10`` seconds
48+
- ``templateflow.conf.TF_GET_TIMEOUT``
49+
* - ``origin`` (DataLad)
50+
- *(none)*
51+
- ``https://github.com/templateflow/templateflow.git``
52+
- ``templateflow.conf.TF_GITHUB_SOURCE``
53+
* - ``s3_root`` (direct download)
54+
- *(none)*
55+
- ``https://templateflow.s3.amazonaws.com``
56+
- ``templateflow.conf.TF_S3_ROOT``
57+
58+
Cache location
59+
~~~~~~~~~~~~~~
60+
The client stores downloads in a writable cache that defaults to the
61+
platform-specific ``TEMPLATEFLOW_HOME`` directory. You can point the CLI to a
62+
different location by exporting the environment variable before invoking any
63+
command; the current value is always available through
64+
``templateflow.conf.TF_HOME``.
65+
66+
.. code-block:: console
67+
68+
$ export TEMPLATEFLOW_HOME=$DATA/.templateflow
69+
$ templateflow config
70+
71+
.. code-block:: python
72+
73+
from templateflow.client import TemplateFlowClient
74+
75+
client = TemplateFlowClient(root="/data/templateflow")
76+
print(client.cache.config.root)
77+
78+
If you switch between cache locations, wipe the previous cache (``templateflow
79+
wipe`` or :func:`templateflow.conf.wipe`) to avoid mixing S3 and DataLad
80+
layouts.
81+
82+
DataLad mode
83+
~~~~~~~~~~~~
84+
Two backends are available: a lightweight S3 mirror and a DataLad dataset.
85+
Setting ``TEMPLATEFLOW_USE_DATALAD=on`` switches the CLI into DataLad mode
86+
(automatically falling back to S3 if DataLad is missing). The active backend
87+
can be inspected via ``templateflow.conf.TF_USE_DATALAD``.
88+
89+
.. code-block:: console
90+
91+
$ export TEMPLATEFLOW_USE_DATALAD=on
92+
$ templateflow config
93+
94+
.. code-block:: python
95+
96+
from templateflow.client import TemplateFlowClient
97+
98+
client = TemplateFlowClient(root="/data/tf-datalad", use_datalad=True)
99+
client.cache.ensure()
100+
print(client.cache.config.use_datalad)
101+
102+
When switching from the default S3 mode to DataLad, start with an empty cache
103+
directory (for example by deleting ``$TEMPLATEFLOW_HOME``) so that git-annex can
104+
initialise cleanly.
105+
106+
S3 origins
107+
~~~~~~~~~~
108+
S3-backed installations download assets from the ``s3_root`` mirror referenced
109+
in the configuration. The CLI always reports the active mirror through the
110+
``templateflow.conf.TF_S3_ROOT`` descriptor.
111+
112+
.. code-block:: console
113+
114+
$ python - <<'PY'
115+
from templateflow.conf import TF_S3_ROOT
116+
print(TF_S3_ROOT)
117+
PY
118+
119+
.. code-block:: python
120+
121+
from templateflow.client import TemplateFlowClient
122+
123+
mirror = TemplateFlowClient(s3_root="https://my-mirror.s3.amazonaws.com")
124+
print(mirror.cache.config.s3_root)
125+
126+
To use a custom DataLad remote, pass ``origin=...`` when constructing the
127+
client and call :func:`templateflow.conf.update` to refresh the cache metadata.
128+
129+
Autoupdates, timeouts, and cache metadata
130+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131+
Automatic cache refreshes are controlled by ``autoupdate``. Disable them for
132+
air-gapped deployments with ``TEMPLATEFLOW_AUTOUPDATE=off`` or by creating the
133+
client with ``autoupdate=False``; the current flag is exported as
134+
``templateflow.conf.TF_AUTOUPDATE``.
135+
136+
Network operations time out after 10 seconds by default. Provide a different
137+
``timeout`` when constructing ``TemplateFlowClient`` and inspect the value via
138+
``templateflow.conf.TF_GET_TIMEOUT``.
139+
140+
Whenever the cache contents change outside the client (for example, when
141+
switching mirrors or pulling updates with DataLad), rebuild the BIDS layout by
142+
calling :func:`templateflow.conf.update` or ``TemplateFlowClient.cache.update``.
143+
The layout object is exposed as ``templateflow.conf.TF_LAYOUT`` and is
144+
invalidated automatically whenever :func:`templateflow.conf.update` succeeds,
145+
ensuring that new metadata descriptors are reflected in subsequent queries.
53146

54147
**Naming conventions**.
55148
Naming conventions for templates and atlases are available within the

0 commit comments

Comments
 (0)