rf: Factor TemplateFlow into Cache and Client classes

[effigies]

TemplateFlow depends a lot on import-time initialization, which can slow down any tool that imports it. It also makes the tests extremely contorted as they have to monkey patch global variables and then either reload modules or rerun module import-time behavior.

This PR creates the following classes:

• templateflow.conf.cache.CacheConfig: a dataclass that will auto-populate in the way the TF_* global config variables did, if no alternatives are passed.
• templateflow.conf.cache.TemplateFlowCache: A wrapper around a specific cache location that implements ensure (install if missing), update and wipe methods and holds a persistent Layout that is built on first access and deleted after an update or wipe so the next access triggers a rebuild.
• templateflow.client.TemplateFlowClient: This provides the templateflow.api functions. It simply holds a TemplateFlowCache and uses its layout instead of a global TF_LAYOUT.

templateflow.cache.__init__ now creates a default TemplateFlowCache and templateflow.api now wraps that in a TemplateFlowClient, and provides its old methods through a module __getattr__. I've left the tests in place to demonstrate that the previously expected behavior remains.

Following @mgxd's review, I've adjusted the TemplateFlowClient.__init__ to be the only interface we advertise. There is a cache and a config object, which can be passed as an expert option, but there's no good reason for people to use it.

---

Open questions:

1. How do you feel about this API and separation of concerns?
2. What about the TemplateFlowClient.__init__ method? I feel like __init__(self, *, cache=None, **config_kwargs) might be a neater way of doing it, so nobody needs to directly construct a CacheConfig instead of TemplateFlowClient(root='/tmp/templateflow', timeout=2).
3. Should we have a module-level __setattr__ to update templateflow.cache.TF_* constants? I don't think that was a well-supported feature, since many were imported into templateflow.api, so changing them in one place wouldn't change them in the other.

Any other thoughts would be welcome. I want copy the test_api test battery to test the client directly (using only the new classes), and add docstrings before finalizing this.

[mgxd]

TemplateFlow depends a lot on import-time initialization, which can slow down any tool that imports it. It also makes the tests extremely contorted as they have to monkey patch global variables and then either reload modules or rerun module import-time behavior.

Agreed, this is a welcome change IMO 👍

How do you feel about this API and separation of concerns?

On board with TemplateFlowCache and TemplateFlowClient, but not sure CacheConfig needs to be public - especially with the suggestions in 2.

What about the TemplateFlowClient.init method?

Yes please, though WDYT about TemplateFlowClient.__init__(self, root: str | None, *, config=None, **config_kwargs) - inspired by BIDSLayout. Then users will only concern themselves with a single import / API. Which parameters should take precedence here? I would assume, from first to last:

1. config is loaded
2. kwargs overwrite
3. root overwrite

Should we have a module-level setattr to update templateflow.cache.TF_* constants? I don't think that was a well-supported feature, since many were imported into templateflow.api, so changing them in one place wouldn't change them in the other.

I don't think so - in fact, isn't this what CacheConfig is essentially addressing?

[mgxd]

This looks good to me, left a suggestion for the pytest error, though not sure about the docs...

[oesteban]

Outstanding work, Chris, thanks for this. Thanks also for your effort to keep things all caught up with best practices, new tools and the general landscape.

[oesteban]

• How do you feel about this API and separation of concerns?

I think this work is very much needed, thanks!

• What about the TemplateFlowClient.__init__ method? I feel like __init__(self, *, cache=None, **config_kwargs) might be a neater way of doing it, so nobody needs to directly construct a CacheConfig instead of TemplateFlowClient(root='/tmp/templateflow', timeout=2).

It feels more natural. I wonder whether we should just break backwards compatibility and recommend people to try to create the client with the new API and then fall back to the old api.stuff() model.

• Should we have a module-level __setattr__ to update templateflow.cache.TF_* constants? I don't think that was a well-supported feature, since many were imported into templateflow.api, so changing them in one place wouldn't change them in the other.

I think it could be useful for people trying to do weird things (e.g., multiple atlases, playing with versions of the Archive, etc.). However, I would leave that for a future PR if people request it.