diff --git a/.gitignore b/.gitignore index a31c2a55..48a6924c 100644 --- a/.gitignore +++ b/.gitignore @@ -73,7 +73,6 @@ instance/ # Sphinx documentation docs/_build/ -docs/api/ # PyBuilder target/ diff --git a/docs/api/templateflow.api.rst b/docs/api/templateflow.api.rst new file mode 100644 index 00000000..bbc491ae --- /dev/null +++ b/docs/api/templateflow.api.rst @@ -0,0 +1,12 @@ +templateflow.api module +======================= + +``templateflow.api`` mirrors the long-standing global helpers while delegating +all heavy lifting to a shared :class:`templateflow.client.TemplateFlowClient` +instance. The directives below document both the public functions and the +proxied client so that migration guides can reference consistent API signatures. + +.. automodule:: templateflow.api + :members: get, ls, templates, get_metadata, get_citations, TemplateFlowClient + :imported-members: + :member-order: bysource diff --git a/docs/api/templateflow.cli.rst b/docs/api/templateflow.cli.rst new file mode 100644 index 00000000..f9eaed25 --- /dev/null +++ b/docs/api/templateflow.cli.rst @@ -0,0 +1,7 @@ +templateflow.cli module +======================= + +.. automodule:: templateflow.cli + :members: + :undoc-members: + :member-order: bysource diff --git a/docs/api/templateflow.client.rst b/docs/api/templateflow.client.rst new file mode 100644 index 00000000..53f3929a --- /dev/null +++ b/docs/api/templateflow.client.rst @@ -0,0 +1,18 @@ +templateflow.client module +========================== + +The client module provides the object-oriented entry point around the global +cache described in :mod:`templateflow.conf`. Its documentation surfaces the +constructor, cache descriptor, and convenience methods so that downstream code +can migrate from the module-level API to the richer class interface. + +.. automodule:: templateflow.client + :members: TemplateFlowClient + :undoc-members: + :member-order: bysource + +.. autoclass:: templateflow.client.TemplateFlowClient + :members: + :special-members: __init__, __repr__ + :member-order: bysource + :show-inheritance: diff --git a/docs/api/templateflow.conf.rst b/docs/api/templateflow.conf.rst new file mode 100644 index 00000000..002731d3 --- /dev/null +++ b/docs/api/templateflow.conf.rst @@ -0,0 +1,22 @@ +templateflow.conf package +========================= + +``templateflow.conf`` centralizes configuration state for both the legacy module +level helpers (``update``/``wipe``) and the newer :class:`~templateflow.conf.cache.TemplateFlowCache` +object. The documentation below highlights the migration path so that users can +incrementally adopt the cache classes without losing backwards-compatible entry +points. + +.. automodule:: templateflow.conf + :members: requires_layout, setup_home, update, wipe + :imported-members: + :member-order: bysource + +Cache management classes +------------------------ + +.. automodule:: templateflow.conf.cache + :members: CacheConfig, TemplateFlowCache, S3Manager, DataladManager + :special-members: __init__ + :undoc-members: + :member-order: bysource diff --git a/docs/cli.rst b/docs/cli.rst index 33012261..c91fa119 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -9,7 +9,66 @@ Examples -------- Listing all the compressed NIfTI files in ``fsaverage``:: - $ templateflow ls fsaverage -x .nii.gz - ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz - ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz - ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz + $ templateflow ls fsaverage -x .nii.gz + ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_den-41k_T1w.nii.gz + ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_desc-brain_mask.nii.gz + ~/.cache/templateflow/tpl-fsaverage/tpl-fsaverage_res-01_T1w.nii.gz + +Managing client configuration +----------------------------- +The ``templateflow`` CLI transparently manipulates the same cache configuration used +by :class:`templateflow.client.TemplateFlowClient`. Running ``templateflow config`` +exposes the options stored in the underlying :class:`templateflow.conf.cache.CacheConfig` +instance:: + + $ templateflow config show + TEMPLATEFLOW_HOME=/home/user/.cache/templateflow + TEMPLATEFLOW_USE_DATALAD=0 + TEMPLATEFLOW_AUTOUPDATE=1 + TEMPLATEFLOW_GET_TIMEOUT=10 + +Changing a value updates the cached client configuration immediately. For example, +enabling the DataLad backend is equivalent to instantiating a client with +``TemplateFlowClient(use_datalad=True)`` because the command mutates the +``CacheConfig`` object used by the global client:: + + $ templateflow config set TEMPLATEFLOW_USE_DATALAD 1 + Updated TEMPLATEFLOW_USE_DATALAD → 1 (DataLad downloads will be used on next access) + +When the CLI is invoked afterwards, the cache will be re-initialized using +``use_datalad=True`` without requiring any additional Python code. The same +mechanism applies to paths (``TEMPLATEFLOW_HOME``), origins, and timeout +settings provided via ``templateflow config``. + +Updating an existing cache +-------------------------- +The :mod:`templateflow.conf` module exposes an ``update`` helper that the CLI +mirrors through ``templateflow update``. Executing the command instructs the +underlying :class:`templateflow.conf.cache.TemplateFlowCache` instance to refresh +its content using the currently selected backend:: + + $ templateflow update --silent + Cache mode: S3 + Cache root: /home/user/.cache/templateflow + TemplateFlow cache is up to date + +If ``TEMPLATEFLOW_USE_DATALAD`` (or ``--use-datalad``) is enabled, the command +delegates to :class:`templateflow.conf.cache.DataladManager` and performs a +recursive ``datalad update``. Otherwise the S3 manager fetches new or changed +files while keeping existing downloads intact. + +Wiping the cache +---------------- +The ``templateflow wipe`` command is a thin wrapper around +:meth:`templateflow.conf.cache.TemplateFlowCache.wipe`. It clears the local cache +and invalidates the in-memory layout so that subsequent ``templateflow`` CLI +calls or new :class:`templateflow.client.TemplateFlowClient` instances trigger a clean re-install:: + + $ templateflow wipe + Removing cache at /home/user/.cache/templateflow … + Cache cleared; next access will reinstall the archive + +In DataLad mode the wipe operation reports that no deletion occurs because +``TemplateFlowCache`` delegates to :class:`~templateflow.conf.cache.DataladManager`, +preserving the working tree. This makes it safe to toggle between backends via +``templateflow config`` without unintentionally removing a managed repository. diff --git a/docs/datalad.rst b/docs/datalad.rst index 22c97452..0a45c5ed 100644 --- a/docs/datalad.rst +++ b/docs/datalad.rst @@ -5,6 +5,22 @@ Therefore, it is possible (and recommended for those who want to leverage the power of DataLad) to access the Archive using just DataLad. +.. tip:: Prefer the Python client for routine access + + The high-level :class:`templateflow.client.TemplateFlowClient` can be + configured with ``use_datalad=True`` (or via ``templateflow config set + TEMPLATEFLOW_USE_DATALAD 1``) to transparently manage the cache with + DataLad. This is a good default when you want TemplateFlow to perform + ``datalad get`` and ``datalad update`` commands automatically while still + interacting with the archive through the familiar client API. + +.. note:: Drop down to raw DataLad when you need full control + + Advanced workflows—such as pinning remotes, creating custom siblings, or + operating entirely offline—are better served by running DataLad commands + directly. In those scenarios leave ``use_datalad`` disabled in the client + and use the instructions below to operate on the repository yourself. + Installing the Archive ---------------------- The archive is indexed by a superdataset, which can be installed with::