Resolvers

Resolvers can be used for extended access to configuration values or to access values outside of the configuration.

Expressions with resolvers take the form ${resolver:parameter,default_value}.

For instance, ${env:PORT,8080} calls the env resolver to retrieve the value of the PORT environment variable. If the return value is empty, then the value of 8080 is used instead.

Parameters to resolvers can also be expressions.

For instance, ${decode:${env:LIMIT},10} would look up the environment variable LIMIT and, if it looks like an integer, convert it to an integer. If LIMIT was not set in the environment, then the value 10 would be decoded into an integer instead.

A list of supported resolvers is below. Built-in namedspaced resolvers (e.g., oc.deprecated) from OmegaConf are also supported.

decode

Resolves the parameter as an expression and coerces it to the datatype it appears to be.

For instance, ${decode:10} returns the integer 10, as does ${decode:${server.port}} if server.port contains the string "10".

Recognized data types include bool, int, float, bytes, dict and list, e.g., "true", "1", "1e-3", b"123", "{a: b}" and "[a, b, c]", with null being decoded as None.

Note: The YAML parser already coerces values that follow certain patterns, so decode is mainly useful for decoding values from other resolvers, or those explicitly stored as strings within a configuration file.

env

Returns the value of an environment variable, or a default value if the variable is not set.

For instance, ${env:PORT} returns the value of the PORT environment variable and ${env:PORT,8080} does the same, but returns the value 8080 if PORT is not set in the environment.

exec

Executes a shell command and returns the output, or None if the command fails.

For instance, a configuration might use this to record the current git revision in its build info:

build_info:
  git_revision: ${exec:git rev-parse HEAD}

Note: Because it runs arbitrary shell commands, exec is not registered by default. A project that needs it must opt in. See Registering Resolvers.

import

Imports a symbol from a Python package.

For instance, a configuration might use this to record the current package version in its build info:

build_info:
  version: ${import:my_package.__version__}

This can also be used to import objects such as shared singletons, for functions or constructors that need a reference to them.

keys

Returns a list of the keys for the mapping at the specified configuration path.

For instance, ${keys:plugins.options} returns a list of the keys at the configuration path plugins.options.

select

Selects a value from the configuration with the ability to provide a default value if the value is not set.

For instance, ${select:server.port,8080} resolves to the value at server.port in the configuration, or 8080 if that value is not set.

It can also be used to resolve configuration paths which contain colons that make them appear to be custom resolvers. For instance, it is possible to use a colon as part of a mapping key within YAML:

options:
  "currency:usd": "$"

However, the expression ${options.currency:usd} will be parsed as passing the usd parameter to the options.currency resolver. To retrieve this value, ${select:"options.currency:usd"} can be used instead.

Registering Resolvers

The decode, env, import, keys and select resolvers are registered automatically, as are the built-in namedspaced resolvers (e.g., oc.deprecated) from OmegaConf.

A project can register its own resolvers, or opt into ones that are not enabled by default, with register_resolver:

from strataconf import exec_resolver, register_resolver

register_resolver("exec", exec_resolver)             # opt into the built-in exec resolver
register_resolver("slugify", my_slugify_function)    # register a custom resolver

A resolver can be removed again with clear_resolver("exec"). Resolvers are registered globally with OmegaConf, so registering one makes it available to every configuration in the process.