YAML Tags

Argument and Return use Python primitive type as common reference.
- To convert to YAML node definitions:
  - Any is any type.
  - str is “scalar”
  - list is “sequence”
  - tuple is a sized “sequence”
  - dict is “mapping”
    - All “mapping” mapping nodes return as a Configuration.
      - Or MutableConfiguration, when using MutableLazyLoadConfiguration.
- Tags in YAML only support “scalar”, “sequence”, and “mapping”.
  - As such,!Tag 1.0 is always a string, despite 1.0 normally being a floating point number.
YAML Tags provided by this library are lazy (running when the value is request, not load time) unless noted.
YAML Tags that are lazy do not support being used as keys to mappings.

Summary Table

Category	Tag	Argument	Usage
Formatters	`!Sub` ⁱ⁺	`str`	`!Sub ${ENVIRONMENT_VARIABLE}` `!Sub ${ENVIRONMENT_VAR:-default value}` `!Sub Normal Text + ${ENVIRONMENT_VAR}` `!Sub ${/JSON/Pointer/expression}` `!Sub ${$.JSON.Path.expression}` `!Sub ${$}` `!Sub ${${ Escaped HTML }}`
Manipulators	`!Del`	`str`	`!Del key: value`
	`!Merge`	`list[dict\|None]`	!Merge - key1: value1 - key2: value2
	`!Placeholder`	`str`	`!Placeholder helpful message`
	`!Ref` ⁱ⁺	`str`	`!Ref /JSON/Pointer/expression` `!Ref $.JSON.Path.expression`
Parsers	`!ParseEnv`	`str \|` `tuple[str,Any]`	`!ParseEnv ENVIRONMENT_VARIABLE` `!ParseEnv ["ENVIRONMENT_VAR", 42]`
	`!ParseEnvSafe`	`str \|` `tuple[str,Any]`	`!ParseEnvSafe ENVIRONMENT_VARIABLE` `!ParseEnvSafe ["ENVIRONMENT_VAR", 42]`
	`!ParseFile` ⁱ⁺	`str`	`!ParseFile relative/path.yaml`
	`!OptionalParseFile` ⁱ⁺	`str`	`!OptionalParseFile optional.yaml`
Typers	`!Class` ^i-	`str`	`!Class uuid.UUID`
	`!Date` ^i-	`str`	`!Date 1988-12-28`
	`!DateTime` ^i-	`str`	`!Date 1988-12-28T23:38:00-0600` `!Date 2019-18-17T16:15:14`
	`!Func` ^i-	`str`	`!Func functools.reduce`
	`!Mask` ^i-	`str`	`!Mask ${SECRET}`
	`!UUID` ^i-	`str`	`!UUID 9d7130a6-{...}-29f0b765be9e`

EagerIO Tag Table

See EagerIO documentation for more details on EagerIO.

Category	Tag	Argument	Usage
Parsers	`!EagerParseFile` ^i-	`str`	`!EagerParseFile relative/path.yaml`
	`!EagerOptionalParseFile` ^i-	`str`	`!EagerOptionalParseFile optional.yaml`

ⁱ⁺ : Supports full interpolation syntax of !Sub.
^i- : Supports reduced interpolation syntax of !Sub without JSON Path or JSON Pointer syntax.

Formatters

`!Sub`

environment_variable: !Sub ${ENVIRONMENT_VARIABLE_THAT_EXISTS}
with_a_default: !Sub ${ENVIRONMENT_VARIABLE_MIGHT_NOT_EXIST:-some default value}
with_other_text: !Sub Normal Text + ${ENVIRONMENT_VARIABLE_THAT_EXISTS}
json_pointer: !Sub ${/json/pointer/expression}
json_path: !Sub ${$.json.path.expression}
$: !Sub ${$}
"${}": !Sub ${&#x24;&#x7B;&#x7D;}

Argument: str
Returns: str ‒ string produced by the interpolation syntax.
Interpolations:
- ${ENVIRONMENT_VARIABLE}: Replaced with the specified Environment Variable.
  - If the variable does not exist, raises EnvironmentVaribleNotFound
  - Use :: to escape colons in environment variable names.
- ${ENVIRONMENT_VARIABLE:-default}: Replaced with the specified Environment Variable.
  - If variable does not exist, use the text after :-.
  - Note: specifier is :-.
- ${ENVIRONMENT_VARIABLE:+<nested_interpolation_spec>}: Replaced with the specified Environment Variable.
  - If variable does not exist, use the text after :+ to interpolate a result.
  - Note: specifier is :+.
- ${/json/pointer/expression}: Replaced by the object in the configuration specified in JSON Pointer syntax.
  - Paths must start at full root of the configuration, using / as the first character.
  - Results:
    - Referencing strings is recommended.
      - Paths that return a Mapping or Sequence will be repr()-ed.
      - Other objects will be str-ed.
    - Paths that do not exist raise JSONPointerQueryFailed.
- ${$.json.path.expression}: Replaced by the object in the configuration specified in JSON Path syntax.
  - Paths must start at full root of the configuration, using $ as the first character.
  - JSON Pointer is recommended over JSON Path.
  - JSON Path syntax includes the ability to construct objects. While allowed, it is not recommended behavior.
  - Results:
    - Referencing strings is recommended.
      - Paths that return a Mapping or Sequence will be repr()-ed.
      - Other objects will be str-ed.
    - Paths that do not exist raise JSONPathQueryFailed.
- ${$}: Replaced with $.
  - !Sub ${$}{} produces ${}
- ${&...;}: Replaced by the results of html.unescape().
  - !Sub ${${}} produces ${}
  - !Sub ${$()} produces $()
  - !Sub ${$[]} produces $[]
- Reserved Syntax:
  - Modes other than :- and :+ are reserved and throw InterpolationSyntaxError.
    - Use :: to escape colons in environment variable names.
  - $(...) is reserved future for use and will warn with InterpolationWarning if used.
Notes:
- ${...} is greedy and does not support nesting (i.e. !Sub ${${}} sees ${ as the inner expression).
- !Sub checks if there is an JSON Path or JSON Pointer expression before keeping a reference to the root of the configuration.

Recursion Possible

Example: Loading a: !Sub ${$.a} will throw RecursionError, when CONFIG.a is called.

`!Env`

environment_variable: !Env "{{ENVIRONMENT_VARIABLE_THAT_EXISTS}}"
with_a_default: !Env "{{ENVIRONMENT_VARIABLE_MIGHT_NOT_EXIST:some default value}}"

Argument: str.
Returns: str ‒ string produced by the string format, replacing {{VARIABLE_NAME}} with the Environment Variable specified. Optionally, a default value can be specified should the Environment Variable not exist.
Notes:
- Does not support environment variables with colons.

Deprecated

!Sub replaces this functionality and offers more options. !Env will not be removed but will not see future updates.

Manipulators

`!Del`

!Del hidden: &common_setting Some Value
copy1: *common_setting
copy2: *common_setting
# Loads as: {"copy1: "Some Value", "copy2": "Some Value"}

!Del setting_with_tag: !UUID &user_id 83e3c814-2cdf-4fe6-b703-89b0a379759e
user: *user_id
# Loads as: {"user": UUID("83e3c814-2cdf-4fe6-b703-89b0a379759e")}

Argument: str.
Action: Marks the key and value to be removed just after load.
- This allows YAML anchors to be defined in the value and used elsewhere is the file, but by the time the configuration is merged and built, the key and value are already removed.
- Technically: This acts as a part of the load, not explicitly afterward.
Notes:
- !Del will only act when applied to the key of mapping pair.
  - Works: !Del key: value
  - Does nothing: key: !Del value.
- !Del is an exception to laziness and acts at load time.

`!Merge`

!Merge
- setting1: some_default_value
- !ParseFile relative/path/to/file.yaml
- !OptionalParseFile relative/path/to/optional/file.yaml
- setting2: some_overriding_value

Argument: list[Any].
Returns: Configuration ‒ The merged Configuration from the sequence of mappings, filtering out any non-mapping entries.
- When merging with MutableLazyLoadConfiguration, the return type is MutableConfiguration.
Notes:
- For more details about merging see Merging.
- The expected use-case for !Merge is to be paired with multiple !ParseFileand/or !OptionalParseFile tags.
- When merging, all objects in the merge list are evaluated.
  - From the example, both the !ParseFile and !OptionalParseFile entries are evaluated with !Merge, not after !Merge.
- If every item is filtered out, the result is an empty Configuration.

Caution

Tags in the sequence argument cannot reference what is being merged.

Following is not allowed, because this !Ref acts during the merge:

key1: !Merge
  - nested_key:
      settings: values
  - !Ref $.key1.nested_key

Following is allowed, because this !Ref acts after the merge:

key1: !Merge
  - nested_key:
      settings: values
  - nested_key2: !Ref $.key1.nested_key

`!Placeholder`

setting1: !Placeholder message to user

Argument: str.
Action: !Placeholder marks a value as needing to be overridden.
- If the !Placeholder is still present when the value is fetched, a PlaceholderConfigurationError is thrown. The exception message includes the attribute name and provided message (e.g. !Placeholder at `$.setting1` was not overwritten. Message: "message to user")
Note:
- The Placeholder object is created at Load Time. The exception is thrown when Fetched.
- PlaceholderConfigurationError is thrown by the Configuration class. !Placeholder as a scalar or sequence will just return a Placeholder instance.

`!Ref`

json_pointer: !Ref /json/pointer/expression
json_path: !Ref $.json.path.expression

Argument: str.
- Supports Full Interpolation Syntax
Returns: Any ‒ Object referenced in absolute JSON Path or JSON Pointer syntax.
Notes:
- Must begin with either $ for JSON Path or / for JSON Pointer. Otherwise, a RefMustStartFromRoot exception is thrown.
- JSON Pointer is recommended over JSON Path.
- !Ref underlies !Sub’s reference interpolation syntax. !Ref returns the object. Whereas !Sub stringifies the object.
- JSON Pointer is limited by designed to be a single reference.
- JSON Path can be used to created objects. $.*.things returns a sequence of all values from mappings contain the things key.
  - This behavior is not restricted, but not recommended.
  - JSON Path was made available first, because cloud services used a restricted version similarly.

Recursion Possible

Example: Loading a: !Ref /a will throw RecursionError, when CONFIG.a is called.

Parsers

`!ParseEnv` | `ParseEnvSafe`

environment_variable_must_exist: !ParseEnv ENVIRONMENT_VARIABLE
environment_variable_may_exist: !ParseEnv
  - ENVIRONMENT_VARIABLE
  - <YAML object>
single_line_example: !ParseEnv [ENV_VAR, false]

Argument: str | tuple[str, Any]
Returns: Any ‒ Result of parsing the specified environment variable.
- When environment variable does not exist:
  - If argument is str, a EnvironmentVaribleNotFound error will be thrown.
  - If argument is tuple, the second object will be returned.
Notes:
- !ParseEnvSafe uses a pure safe YAML loader. !ParseEnv uses this library’s loader.
- This was created to make Boolean environment variables more consistent.
  - For value: !ParseEnvSafe [ENV_VAR, false]:
    - If ENV_VAR=TRUE, Config.value is True.
    - If ENV_VAR=FALSE, Config.value is False.
    - If ENV_VAR is not set, Config.value is False.
    - Using !Sub, FALSE would need to be an empty string (""), which is less obvious than FALSE.
- (Since 2.1.0) !ParseEnv detects loading loops and throws ParsingTriedToCreateALoop when trying to load an environment variable already part of the chain.
  - See Loading Loops for an explanation with examples.

`!ParseFile` | `!OptionalParseFile`

file_must_exist: !ParseFile relative/path/to/file.yaml
file_may_exist: !ParseFile relative/path/to/optional/file.yaml

Argument: str
- Supports Full Interpolation Syntax
Returns: Any ‒ Result of loading the specified file.
- When the file does not exist:
  - !ParseFile throws FileNotFoundError.
  - !OptionalParseFile return null (None).
Notes:
- !ParseFile can be used at the root of the configuration document to act as a file redirect.
- !OptionalParseFile is intended to be used with !Merge, where nulls are filtered out.
- (Since 2.1.0) !ParseFile detects file loading loops and throws ParsingTriedToCreateALoop when trying to load a file already part of the chain.
  - See Loading Loops for an explanation with examples.
EagerIO Versions:
- !EagerParsefile and !EagerOptionalParseFile work the same as their original counterparts.
  - Files are read at Load Time and parsed at Fetch Time.
    - Because of this, EagerIO Tags only support the Reduced Interpolation Syntax.
    - Added: 2.3.0

Typers

`!Class`

class_type: !Class uuid.UUID

Argument: str
- Supports Reduced Interpolation Syntax
Returns: type ‒ Specified the class.
Notes:
- The current working directory is added prior to importing the specified module.
- Returned object must pass inspect.isclass() as True.

`!Date`

date: !Date 1988-12-28

Argument: str
- Supports Reduced Interpolation Syntax
Returns: date ‒ String parsed as ISO 8601 in a Python datetime.date.
Notes:
- For Python 3.11+, date.fromisoformat() is used.
- For Python 3.10, dateutil.parser.parse(value, yearfirst=True, dayfirst=False).date() is used.

`!DateTime`

with_time_zone: !DateTime "2012-10-31T13:12:09-0600"
without_time_zone: !DateTime "2012-10-31T13:12:09"

Argument: str
- Supports Reduced Interpolation Syntax
Returns: datetime ‒ String parsed as ISO 8601 in a Python datetime.datetime.
Notes:
- For Python 3.11+, datetime.fromisoformat() is used.
- For Python 3.10, dateutil.parser.parse(value, yearfirst=True, dayfirst=False) is used.

`!Func`

function: !Func functools.reduce

Argument: str
- Supports Reduced Interpolation Syntax
Returns: Callable ‒ Specified function.
Notes:
- The current working directory is added prior to importing the specified module.
- Returned object must pass callable() as True.

`!Mask`

function: !Mask ${SECRET}

Argument: str
- Supports Reduced Interpolation Syntax
Returns: Masked ‒ The string as a Masked
Notes:
- Masked inherits from str, with the __repr__() overridden to always return the same constant literal '<****>'.
- Some libraries (such as requests) explicitly only support str and not subclasses of str.
  - In those cases, you can str(masked_value) to get back the pure str.

`!UUID`

id: !UUID 9d7130a6-192f-41e6-88ce-29f0b765be9e

Argument: str
- Supports Reduced Interpolation Syntax
Returns: UUID ‒ The string parsed by Python uuid.UUID,

YAML Tags

Summary Table

EagerIO Tag Table

Formatters

!Sub

!Env

Manipulators

!Del

!Merge

!Placeholder

!Ref

Parsers

!ParseEnv | ParseEnvSafe

!ParseFile | !OptionalParseFile