Improve acre API

[aardschok]

Currently the API feels odd and clunky. As a new user it will be confusing to read through the combination of functions which allow acre to work.

Proposal: refactor of function names

• get_tools --> collect: get_tools makes me think I already have them ready to go
• compute --> evaluate or translate: sounds less stale

There are a few other function name but those names are less in the foreground as the above.

[BigRoy]

get_tools --> collect: get_tools makes me think I already have them ready to go

Good point. How about discover? Might be even better! :)

compute --> evaluate or translate: sounds less stale

None of them really tell me what it does and why it needs done. How about acre.prepare? It could even be acre.get?

I'm looking for something that tells in a couple of steps how to build your environment with Acre, for example:

1. discover your tools
2. prepare the dynamic tools environments for a specific platform
3. merge it into your environment.

# pseudocode
config = acre.discover("global;maya2018")
prepared = acre.prepare(config, platform="windows")
env = acre.merge(env, current_env=os.environ)

# Update live environment
os.environ.update(env)

The issue with the last one is that it doesn't actually merge anything - it just evaluates/computes the changes when implementing into your current environment. You'd still need to update afterwards.

---

Could we maybe even combine prepare and merge into a single function? Or are there use cases where the current separation makes sense? Like, do we ever need to prepare without building it on top of a specific (or current) environment?

[aardschok]

The issue with the last one is that it doesn't actually merge anything - it just evaluates/computes the changes when implementing into your current environment. You'd still need to update afterwards.

This depends on what we need to do with the created environment. For example when we need to launch a program we pass the created environment to the subprocess. In that case we do not need to update the current environment. So I think that is good but the user should be able to tell if he wants to merge it into its live environment

[BigRoy]

This depends on what we need to do with the created environment. For example when we need to launch a program we pass the created environment to the subprocess. In that case we do not need to update the current environment. So I think that is good but the user should be able to tell if he wants to merge it into its live environment

Yes, returning the changes only was done like that for a reason. In that point I was referring to the fact that the function is called merge, but it doesn't actually merge or update anything. :)

discover your tools

Had another thought on discover - I'm 50/50 on discover or collect- I have no arguments to go for one over the other.

Could we maybe even combine prepare and merge into a single function? Or are there use cases where the current separation makes sense? Like, do we ever need to prepare without building it on top of a specific (or current) environment?

@aardschok what did you think on that?

config = acre.discover("global;maya2018")
env = acre.build(config)

# Update live environment
os.environ.update(env)

To target a specific OS:

acre.build(config, platform="windows")

And somehow we'll need to expose whatever merge currently does too.

acre.build(config, env=os.environ)

The os.environ could be the default, so it builds the configuration on top of the local enviroment - note, it does not set it live - like before.

[aardschok]

Reading this again a bit later agree with the function naming provide here. It reads more logical.