Deprecation of the env resolver for variable environment interpolations

[odelalleau]

In OmegaConf 2.1, the env resolver is being deprecated in favor of a new oc.env resolver.

To migrate to this new resolver:

• Replace ${env:MYVAR} with ${oc.env:MYVAR}
• Consider whether your config or code may need to be updated due to the following three main differences with oc.env:
  1. Unlike env, oc.env does not convert environment variables to primitives automatically (booleans, integers and floats) and always return the string representation. If you wish to convert from string to a different type, you may either take advantage of automatic conversion for typed nodes (see example below), or use the new oc.decode resolver (see its documentation)
  2. The default value of oc.env is converted to string using str(default) unless it's null (representing Python None). For instance, ${env:OMP_NUM_THREADS,1} will return the string "1" if OMP_NUM_THREADS is not set. And ${env:OMP_NUM_THREADS,null} will return None if if OMP_NUM_THREADS is not set.
  3. Unlike env, oc.env is un-cached. this means that if MYVAR is updated within the program's process, the change will appear when accessing ${oc.env:MYVAR}.

[odelalleau]

This is an example of how to take advantage of the automatic conversion for typed nodes (see also the documentation):

import os
from dataclasses import dataclass
from typing import Any

from omegaconf import II, OmegaConf


@dataclass
class Config:
    some_int: int = II("oc.env: SOME_INT, '123'")      # converted to int
    some_bool: bool = II("oc.env: SOME_BOOL, 'True'")  # converted to bool
    some_any: Any = II("oc.env: SOME_ANY, '123'")      # not converted (untyped)


cfg = OmegaConf.structured(Config)

assert cfg.some_int == 123
assert cfg.some_bool is True
assert cfg.some_any == "123"

os.environ["SOME_INT"] = "456"
os.environ["SOME_BOOL"] = "false"
os.environ["SOME_ANY"] = "false"

assert cfg.some_int == 456
assert cfg.some_bool is False
assert cfg.some_any == "false"