Config Objects¶

class omnifig.config.nodes.ConfigNode(*args, reporter=None, settings=None, project=None, manager=None, **kwargs)¶

Bases: AutoTreeNode, AbstractConfig

The main config node class. This class is used to represent the config tree and is the main interface for interacting with the config.

Settings¶: alias of OrderedDict

classmethod from_raw(raw, *, parent=<class 'omnibelt.typing.unspecified_argument'>, parent_key=None, **kwargs)¶

Converts the given raw data into a config node. This will recursively convert all nested data into config nodes.

Parameters:

raw (Any) – python data to convert (may be a primitive or a dict/list-like object)
parent (Optional[ConfigNode]) – the parent node (if any) of the node to be created
parent_key (Optional[str]) – the key of the node to be created (if any) in the parent node
**kwargs – additional arguments to pass to the constructor

Return type:

ConfigNode

Returns:

The created config node

class Search(origin, queries, default, parent_search=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Bases: AbstractSearch

Used to traverse the config tree and find the node corresponding to the given set of queries.

confidential_prefix = '_'¶

force_create_prefix = '<!>'¶

delegation_prefix = '<>'¶

delegation_origin_prefix = '<o>'¶

missing_key_payload = '__x__'¶

sub_search()¶

Returns a context manager that allows new searches to reference back to this search

Return type:: ContextManager

__init__(origin, queries, default, parent_search=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Evaluates the given queries and default values to find the node (or consequent product) in the config tree.

Parameters:

origin (ConfigNode) – the node from which to start the search
queries (Optional[Sequence[str]]) – keys to search for (in order) in the config tree
default (Any) – if the search fails, this value is returned
parent_search (Optional[Search]) – if the search is nested, this is the search that was used to find the parent node
**kwargs – additional arguments to pass to the constructor (not used)

find_node(silent=None)¶

Traverses the config tree from the origin node to find the node corresponding to the queries (given in __init__). If no queries are provided, the origin node is returned.

This method should be used when the end result of the search should be the node (not a product).

Return type:: ConfigNode
Returns:: The node corresponding to the queries with the current search as the trace (for reporting)
Raises:: SearchFailed – if the node could not be found and no default was provided

find_product(silent=None)¶

Traverses the config tree from the origin node to find the node corresponding to the queries and then produces the product of that node (using the “process” or “create” method of the node).

This method should be used when the end result of the search should be the product (i.e. value contained by the node).

If all the queries failed, the default is returned (if provided) and reported using the origin’s reporter.

Parameters:: silent (Optional[bool]) – propagate the silent flag the reporter or node processing
Return type:: Any
Returns:: Result of resolving the queries, which is either the product of the node or the default value if no node was found
Raises:: SearchFailed – if the node could not be found and no default was provided

process_node(node)¶

Processes the node by checking for delegations (and then resolving those) or any other special search features (such as making sure this node is still valid).

A delegation is a node where the value is itself interpretted as a query to a different node (e.g. using the prefix “<>”). There are a few specific prefixes that can be used for different types of delegations:

<>: delegate to a new node starting the search from the current node

<o>: delegate to a new node starting the search from the origin node

<!>: delegate to a new node for which the product is always newly created
(rather than reused if it already exists)

If the current node delegates, the unused queries and query chain may be updated through the _resolve_query() method.

If the value of a node is “__x__”, the node is considered to be missing (i.e. it effectively doesn’t exist).

Parameters:: node (ConfigNode) – the result of resolving the queries thus far
Return type:: ConfigNode
Returns:: The node once all delegations and special features have been resolved
Raises:: SearchFailed – if the node is not valid or a delegation could not be resolved

exception SearchFailed(*queries)¶

Bases: SearchFailed

Raised when a search fails to find a value

__init__(*queries)¶

class Reporter(indent=' > ', flair='| ', alias_fmt=' --> ', colon=': ', max_num_aliases=3, **kwargs)¶

Bases: AbstractReporter

Formats and prints the results of a search over the config tree.

__init__(indent=' > ', flair='| ', alias_fmt=' --> ', colon=': ', max_num_aliases=3, **kwargs)¶

Specifies the format in which the search results are printed to the console.

Parameters:

indent (str) – for each depth, this string is prepended to the line
flair (str) – prepended to every line this reporter prints (to distinguish it from other output)
alias_fmt (str) – used to indicate that a query was replaced by another (e.g. due to delegation or missing)
colon (str) – separates the key from the value
max_num_aliases (int) – the maximum number of aliases to print before truncating the list
**kwargs – passed to the parent class (unused)

static log(*msg, end='\\n', sep=' ', silent=None)¶

Prints the message to the console (similar to print).

Parameters:

*msg (str) – terms to join and print
end (str) – ending character (default is newline)
sep (str) – character to join terms (default is space)
silent (Optional[bool]) – if True, the message is not printed (but still returned)

Return type:

str

Returns:

The message that was printed

get_key(trace)¶

Formats the key of the node (taking parents into account).

Parameters:: trace (Search) – the search context (used to get the node)
Return type:: str
Returns:: The formatted key (including aliases and parents)

report_node(node, *, silent=None)¶

Reports when a node was found and prints it to the console. By default, no message is printed.

Parameters:

node (ConfigNode) – result of the search
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

None

report_default(node, default, *, silent=None)¶

Reports when a default value was used and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
default (Any) – value that was used instead
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

report_empty(node, *, silent=None)¶

Reports when a node was found, but it was empty and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

report_iterator(node, product=False, *, silent=None)¶

Reports when a node was found and returned as an iterator and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
product (Optional[bool]) – if True, the iterator returns the products of the nodes (defaults to False)
silent (Optional[bool]) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

reuse_product(node, product, *, silent=None)¶

Reports when a node was found and its product was reused and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
product (Any) – the product that was reused
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

create_primitive(node, value=<class 'omnibelt.typing.unspecified_argument'>, *, silent=None)¶

Reports when a product was created that was a primitive and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
value (Union[str, int, float, bool, None]) – of the product
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

create_container(node, *, silent=None)¶

Reports when a product was created that was a container and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

create_component(node, *, component_type=None, modifiers=None, creator_type=None, silent=None)¶

Reports when a product was created that was a component and prints it to the console.

Parameters:

node (ConfigNode) – result of the search
component_type (str) – registered name of the component
modifiers (Optional[Sequence[str]]) – registered names of the modifiers
creator_type (str) – registered name of the creator (defaults to None)
silent (bool) – if True, the message is not printed (but still returned)

Return type:

Optional[str]

Returns:

Message that was printed

exception CycleError(config)¶

Bases: RuntimeError

Raised when a cycle is detected in the config tree.

__init__(config)¶

class DefaultCreator(config, *, component_type=<class 'omnibelt.typing.unspecified_argument'>, modifiers=None, project=None, component_entry=<class 'omnibelt.typing.unspecified_argument'>, silent=None, **kwargs)¶

Bases: AbstractCreator

Manages the creation of products of config nodes. Generally, there are three types of products:

primitives (int, float, str, bool, None)
containers (list, dict)
components (objects, must be registered, and may optionally be modified)

The default creator is responsible for creating the products, but you can also create your own creators (e.g. subclassses) and then specify them when registering components (to make those the defaults) or in the config directly. Alternatively, you can force a specific creator to be used by changing the config setting “creator”.

Note, that it is generally up to the creator to call the config reporter to report the creation of products.

classmethod replace(creator, config, *, component_type=None, modifiers=None, project=<class 'omnibelt.typing.unspecified_argument'>, component_entry=<class 'omnibelt.typing.unspecified_argument'>, silent=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Extracts information from the given creator to replace it. Used primarily in DefaultCreator.validate().

Return type:: AbstractCreator

__init__(config, *, component_type=<class 'omnibelt.typing.unspecified_argument'>, modifiers=None, project=None, component_entry=<class 'omnibelt.typing.unspecified_argument'>, silent=None, **kwargs)¶

A default creator is instantiated each time a product of a config node is created.

Parameters:

config (ConfigNode) – node for which the product is being created
component_type (Optional[str]) – if not specified, the type is extracted from the config node with the key “_type”
modifiers (Optional[Sequence[str]]) – if not specified, the modifiers are extracted from the config node with the key “_mod”
project (Optional[AbstractProject]) – the owning project, if not specified, the same project as the config is used
component_entry (Optional[NamedTuple]) – if the component entry has already been found, it can be passed here
silent (Optional[bool]) – if True, suppresses the reporter from printing messages
**kwargs – additional arguments (unused)

validate(config)¶

Validates the creator. If the creator is invalid, a new one is created and returned based on what is specified in the config or component_entry.

If a different creator is specified, the current one is replaced with DefaultCreator.replace(). Otherwise, the creator is returned unchanged.

Parameters:: config (AbstractConfig) – node for which the product is being created
Return type:: AbstractCreator
Returns:: Validated creator

create_product(config, args=None, kwargs=None, *, silent=None)¶

Top level method for creating the product from the config node which is called by the config node.

Parameters:

config (ConfigNode) – node for which the product is being created
args (Optional[Tuple]) – manual positional arguments to be passed to the component constructor
kwargs (Optional[Dict[str, Any]]) – manual keyword arguments to be passed to the component constructor
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

Any

Returns:

Product created from the config node

search(*queries, default=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Creates a search object that can be used to resolve the given queries to find the corresponding node.

Note that this method is usually not called directly, but rather through the top level methods such as ConfigNode.pull() or ConfigNode.peek().

Parameters:

*queries (str) – list of queries to be resolved
default (Optional[Any]) – if all the queries fail, this value will be returned
**kwargs – additional keyword arguments to be passed to the search object constructor

Return type:

Search

Returns:

Search object that can be used to traverse the config tree

peeks(*queries, default=<class 'omnibelt.typing.unspecified_argument'>, silent=None)¶

Searches in the config based on the given queries and returns the resulting node.

If multiple queries are given, the first one that resolves to a node will be returned. If all the queries fail, the default value will be returned (if given), otherwise a Search.SearchFailed will be raised.

Parameters:

*queries (str) – list of queries to be resolved
default (Optional[Any]) – value to be returned if all the queries fail
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

ConfigNode

Returns:

Config node that corresponds to the first query that resolves to a node

Raises:

Search.SearchFailed – if all the queries fail and no default value is given

pulls(*queries, default=<class 'omnibelt.typing.unspecified_argument'>, silent=None, **kwargs)¶

Searches in the config based on the given queries and returns the product of the resulting node. The product is the value that node contains, which can be a primitive, a container, or a component. If the product is a container or component, it will be created if it has not been created yet.

If multiple queries are given, the first one that resolves to a node is used If all the queries fail, the default value will be returned (if given), otherwise a Search.SearchFailed will be raised.

Parameters:

*queries (str) – list of queries to be resolved
default (Optional[Any]) – value to be returned if all the queries fail
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

Any

Returns:

Product of the config node corresponding to the first query that doesn’t fail

Raises:

Search.SearchFailed – if all the queries fail and no default value is given

push(addr, value, overwrite=True, silent=None)¶

Inserts a new node into the config tree.

Parameters:

addr (str) – of the new node (i.e. the key or index)
value (Any) – of the new node
overwrite (bool) – if True, overwrites the existing node if there is one
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

bool

Returns:

True if the node was inserted, False if it was not inserted

Raises:

ReadonlyError – if the config is readonly

peek_children(*, silent=None)¶

Returns an iterator over the child nodes of self.

The iterator skips invalid children (such as empty values or __x__).

Parameters:: silent (Optional[bool]) – if True, suppresses the reporter from printing messages
Return type:: Iterator[ConfigNode]
Returns:: Iterator over the children of self

peek_named_children(*, silent=None)¶

Returns an iterator over the child nodes of self, including their keys.

The iterator skips invalid children (such as empty values or __x__).

Parameters:: silent (Optional[bool]) – if True, suppresses the reporter from printing messages
Return type:: Iterator[Tuple[str, ConfigNode]]
Returns:: Iterator producing tuples in the form of (key, child_node)

pull_children(*, force_create=False, silent=None)¶

Returns an iterator over the products of the child nodes of self.

The iterator skips invalid children (such as empty values or __x__).

Parameters:

force_create (Optional[bool]) – if True, will always create new products instead of reuse existing ones
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

Iterator[Any]

Returns:

Iterator over the products of the children of the node

pull_named_children(*, force_create=False, silent=None)¶

Returns an iterator over the products of the child nodes of self, including their keys.

The iterator skips invalid children (such as empty values or __x__).

Parameters:

force_create (Optional[bool]) – if True, will always create new products instead of reuse existing ones
silent (Optional[bool]) – if True, suppresses the reporter from printing messages

Return type:

Iterator[Tuple[str, Any]]

Returns:

Iterator over the products of the children of the node

peek_process(query, default=<class 'omnibelt.typing.unspecified_argument'>, *args, **kwargs)¶

Convenience method which composes peek() and process(), to only process a node if it exists, and otherwise return the given default value.

Parameters:

query – of the node to be processed
default (Optional[Any]) – value to be returned if the node doesn’t exist
*args (Any) – positional arguments to be passed to process() (e.g. to the constructor of the component)
**kwargs (Any) – keyword arguments to be passed to process() (e.g. to the constructor of the component)

Return type:

Any

Returns:

Product of the node corresponding to the query, or the default value if the node doesn’t exist

Raises:

Search.SearchFailed – if the query fails and no default value is given

peeks_process(*queries, default=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Convenience method which composes peeks() and process(), to only process a node if it exists, and otherwise return the given default value.

Note that since this method allows for multiple queries, no positional arguments can be passed to the process() method, and neither can the keyword argument default.

Parameters:

*queries – of the nodes to be processed
default (Optional[Any]) – value to be returned if the node doesn’t exist
**kwargs (Any) – keyword arguments to be passed to process() (e.g. to the constructor of the component)

Return type:

Any

Returns:

Product of the node corresponding to the query, or the default value if the node doesn’t exist

Raises:

Search.SearchFailed – if the query fails and no default value is given

peek_create(query, default=<class 'omnibelt.typing.unspecified_argument'>, *args, **kwargs)¶

Convenience method which composes peek() and create(), to only create the product if the node exists, and otherwise return the given default value.

Parameters:

query – of the node for which the product should be created
default (Optional[Any]) – value to be returned if the node doesn’t exist
*args (Any) – positional arguments to be passed to create() (e.g. to the constructor of the component)
**kwargs (Any) – keyword arguments to be passed to create() (e.g. to the constructor of the component)

Return type:

Any

Returns:

Product of the node corresponding to the query, or the default value if the node doesn’t exist

Raises:

Search.SearchFailed – if the query fails and no default value is given

peeks_create(*queries, default=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Convenience method which composes peeks() and create(), to only create the product if the node exists, and otherwise return the given default value.

Note that since this method allows for multiple queries, no positional arguments can be passed to the create() method, and neither can the keyword argument default.

Parameters:

*queries – of the nodes to be processed
default (Optional[Any]) – value to be returned if the node doesn’t exist
**kwargs (Any) – keyword arguments to be passed to create() (e.g. to the constructor of the component)

Return type:

Any

Returns:

Product of the node corresponding to the query, or the default value if the node doesn’t exist

Raises:

Search.SearchFailed – if the query fails and no default value is given

__init__(*args, reporter=None, settings=None, project=None, manager=None, **kwargs)¶

Initializes a new config node. Most of the arguments passed to this constructor should usually be None so that this node refers to the values of the root config node.

Parameters:

*args – unused positional arguments passed to the constructor of the super class
reporter (Optional[Reporter]) – used for reporting when data is accessed, defers to the root node
settings (Optional[OrderedDict]) – used to determine the behavior of searching and producing products, defers to the root node
project (Optional[AbstractProject]) – associated with this config, defers to the root node
manager (Optional[AbstractConfigManager]) – associated with this config, defers to the root node
**kwargs – unused keyword arguments passed to the constructor of the super class

export(name, *, root=None, fmt=None)¶

Exports the given config to the given path (in yaml format).

Parameters:

config – object to export
name (Union[str, Path]) – of file name or path to export to (without extension)
root (Union[str, Path, None]) – directory to export to (if not provided, the current working directory is used)
fmt (Optional[str]) – format to export to (if not provided, the extension of the file name is used, and defaults to yaml)

Return type:

Optional[Path]

Returns:

The path to which the config was exported

property project¶: Returns the project associated with this config tree.

property cro: Tuple[str, ...]¶

Returns the list of all config files that were composed to produce this config tree. Analogous to the method resolution order (mro) for classes.

Return type:: Tuple[str, ...]

property bases: Tuple[str, ...]¶

Returns the list of config files that were explicitly mentioned to produce this config tree. Analogous to __bases__ for classes.

Return type:: Tuple[str, ...]

property manager¶: Returns the manager associated with this config tree.

property trace: Search | None¶

Returns the current search trace associated this config node (generally only used by creators and reporters).

Return type:: Optional[Search]

property reporter: Reporter¶

Returns the reporter associated with this config tree.

Return type:: Reporter

property settings: OrderedDict¶

Returns the (global) settings associated with this config tree.

Return type:: OrderedDict

property silent: bool¶

Returns whether this config node is in silent mode.

Return type:: bool

exception ReadOnlyError¶

Bases: Exception

Raised when a read-only config node is attempted to be modified.

class ConfigContext(config, settings)¶

Bases: object

Context manager for temporarily modifying the (global) settings of a config tree.

__init__(config, settings)¶

context(**settings)¶

Returns a context manager for temporarily modifying the (global) settings of this config tree.

Return type:: ContextManager

create(*args, **kwargs)¶

Creates a new value based on the contents of self.

Parameters:

*args (Any) – Manual arguments to pass to the value constructor.
**kwargs (Any) – Manual keyword arguments to pass to the value constructor.

Return type:

Any

Returns:

The newly created value.

create_silent(*args, **kwargs)¶

Convenience method for creating a value in silent mode.

Return type:: Any

process(*args, **kwargs)¶

Processes the config object using the contents of self.

If a value for this config object has already been created, it is returned instead of creating a new one.

Parameters:

*args (Any) – Manual arguments to pass to the value constructor. (ignored if a value has already been created)
**kwargs (Any) – Manual keyword arguments to pass to the value constructor.
created) ((ignored if a value has already been) –

Return type:

Any

Returns:

The processed value.

process_silent(*args, **kwargs)¶

Convenience method for processing a value in silent mode.

Return type:: Any

property product_exists: bool¶

Returns True if the product of this config node has already been created.

Return type:: bool

clear_product(recursive=True)¶

Removes the product of this config node (if it exists), and optionally removes the products of all child nodes.

Parameters:: recursive (bool) – if True, the products of all child nodes are also removed
Return type:: None

to_yaml(stream=None, default_flow_style=None, sort_keys=True, **kwargs)¶

Dumps the contents of this config node in YAML format to the specified stream.

Parameters:

stream – destination stream
default_flow_style – YAML formatting option (see PyYAML documentation)
sort_keys – YAML formatting option (if True, keys are sorted alphabetically)
**kwargs (Any) – additional keyword arguments to pass to PyYAML’s dump function

Return type:

None

Returns:

None

update(update, *, clear_product=True)¶

Updates the contents of this config node with the contents of another config node.

Parameters:

update (ConfigNode) – the config node to update from
clear_product (bool) – if True, all references to the products of self and update are removed

Return type:

ConfigNode

Returns:

The updated config node, self

validate()¶

Recursively validates the contents of this config node.

Including removing any children with the value _x_ (marked for removal).

silence(silent=True)¶

Convenience method for temporarily setting the silent flag of this config node.

Return type:: ContextManager

print(*terms, force=False, sep=' ', end='\\n', **kwargs)¶: Convenience method for printing iff (force or not self.silent)

DefaultNode¶: alias of ConfigSparseNode

DenseNode¶: alias of ConfigDenseNode

SparseNode¶: alias of ConfigSparseNode

class omnifig.config.nodes.ConfigSparseNode(*args, reporter=None, settings=None, project=None, manager=None, **kwargs)¶

Bases: AutoTreeSparseNode, ConfigNode

A config node that treats its children as being in a dict.

class omnifig.config.nodes.ConfigDenseNode(*args, reporter=None, settings=None, project=None, manager=None, **kwargs)¶

Bases: AutoTreeDenseNode, ConfigNode

A config node that treats its children as being in a list.