Improve explanation for the Env module

[edublancas]

Envs are a powerful concept but might be a little hard to understand

The best way to interact with Env is via the with_env and load_env decorators. with_env constrains the env's lifetime to the execution body while load_env just gets the current active env.

For simple cases such as passing paths to files, it is straighforward to use them but for cases where we want a Env to customize a function, it might lead to broken code if the user does not correctly understand what's going on.

For example, if a pipeline uses logging_handler_factory, it has to declare a function like this:

def logging_handler_factory(dag_name):
   # make handler
   return handler

If they user wants to load parameters to configure the handler it will be tempted to do:

@load_env
def logging_handler_factory(env, dag_name):
   # make handler
   return handler

But that won't work. By the time the function decorated with @with_env is executed, the env ceases to exist, hence, when logging_handler_factory is called by dag.build, env will be None.

The solution is to make sure all parameters are resolved in the function body, which means doing:

def logging_handler_factory(some_param, dag_name):
   # make handler
   return handler

and then...

@with_env
def make(env):
    # ...
   logging_handler_factory = partial(logging_handler_factory, some_param=env.some_param)

An alternative would be to completely eliminate the load_env decorator to prevent this behavior.