Class RankedValue

src/python/pants/option/ranked_value.py:38–96

An option value, together with a rank inferred from its source. Allows us to control which source wins: e.g., a command-line flag overrides an environment variable which overrides a config, etc. For example: Consider this config: [compile.java] foo: 11 And this envi

@dataclass(frozen=True)
class RankedValue:
    """An option value, together with a rank inferred from its source.

     Allows us to control which source wins: e.g., a command-line flag overrides an environment
     variable which overrides a config, etc. For example:

     Consider this config:

     [compile.java]
     foo: 11

     And this environment variable:

     PANTS_COMPILE_FOO: 22

    If the command-line is

     ./pants compile target

     we expect the value of foo in the compile.java scope to be 22, because it was explicitly
     set by the user in the enclosing compile scope. I.e., the outer scope's environment value
     overrides the inner scope's config value.

     However if the command-line is

     ./pants compile.java --foo=33 target

     we now expect the value of foo in the compile.java to be 33. I.e., the inner scope's flag
     overrides the outer scope's environment value.

     To tell these cases apart we need to know the "ranking" of the value.
    """

    @classmethod
    def prioritized_iter(
        cls,
        flag_val: Value,
        env_val: Value,
        config_val: Value,
        config_default_val: Value,
        hardcoded_val: Value,
        default: Value,
    ) -> Iterator["RankedValue"]:
        """Yield the non-None values from highest-ranked to lowest, wrapped in RankedValue
        instances."""
        if flag_val is not None:
            yield RankedValue(Rank.FLAG, flag_val)
        if env_val is not None:
            yield RankedValue(Rank.ENVIRONMENT, env_val)
        if config_val is not None:
            yield RankedValue(Rank.CONFIG, config_val)
        if config_default_val is not None:
            yield RankedValue(Rank.CONFIG_DEFAULT, config_default_val)
        if hardcoded_val is not None:
            yield RankedValue(Rank.HARDCODED, hardcoded_val)
        yield RankedValue(Rank.NONE, default)

    rank: Rank