Config Manager

class omnifig.config.manager.ConfigManager(project)

Bases: AbstractConfigManager

class 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.

class ConfigContext(config, settings)

Bases: object

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

__init__(config, settings)
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.

__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)

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

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

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

DefaultNode

alias of ConfigSparseNode

DenseNode

alias of ConfigDenseNode

exception ReadOnlyError

Bases: Exception

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

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)

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

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_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

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)

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

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

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

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

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.

__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)

confidential_prefix = '_'
delegation_origin_prefix = '<o>'
delegation_prefix = '<>'
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

force_create_prefix = '<!>'
missing_key_payload = '__x__'
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

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

Return type:

ContextManager

exception SearchFailed(*queries)

Bases: SearchFailed

Raised when a search fails to find a value

__init__(*queries)
Settings

alias of OrderedDict

SparseNode

alias of ConfigSparseNode

__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

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, ...]

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

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

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, ...]

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

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

property manager

Returns the manager associated with this config tree.

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_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

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)

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(*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

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

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

print(*terms, force=False, sep=' ', end='\\n', **kwargs)

Convenience method for printing iff (force or not self.silent)

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

property project

Returns the project associated with this config tree.

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

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

property reporter: Reporter

Returns the reporter associated with this config tree.

Return type:

Reporter

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

property settings: OrderedDict

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

Return type:

OrderedDict

silence(silent=True)

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

Return type:

ContextManager

property silent: bool

Returns whether this config node is in silent mode.

Return type:

bool

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

property trace: Search | None

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

Return type:

Optional[Search]

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).

class Config_Registry(*args, _sister_registry_object=None, _sister_registry_cls=None, **kwargs)

Bases: Path_Registry

Registry for config files.

entry_cls

alias of Config_Registry_Entry

__init__(project)
export(config, name, *, root=None, fmt=None)

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

Parameters:

  • config (ConfigNode) – object to export

  • name (Union[str, Path]) – of file to export to

  • root (Optional[Path]) – 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:

Path

Returns:

The path to which the config was exported

iterate_configs()

Iterates over all registered config file entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered config file entries.

register_config(name, path=None, **kwargs)

Registers a config file with the given name.

Note

It is generally not recommended to register configs manually, but rather to use the register_config_dir method to register all configs in a directory at once.

Parameters:

  • name (Union[str, Path]) – to register the config under

  • path (Union[str, Path]) – of the config file (if not provided, the provided name is assumed to be a path)

  • **kwargs – Other arguments to pass to the Config_Registry.register method

Return type:

NamedTuple

Returns:

The entry of the config file that was registered

register_config_dir(root, *, recursive=True, prefix=None, delimiter=None)

Registers all yaml files found in the given directory (possibly recursively)

When recusively checking all directories inside, the internal folder hierarchy is preserved in the name of the config registered, so for example if the given path points to a directory that contains a directory a and two files f1.yaml and f2.yaml:

Contents of path and corresponding registered names:

  • f1.yaml => f1

  • f2.yaml => f2

  • a/f3.yaml => a/f3

  • a/b/f4.yaml => a/b/f3

If a prefix is provided, it is appended to the beginning of the registered names

Parameters:

  • root (Union[str, Path]) – root directory to search through

  • recursive (Optional[bool]) – search recursively through subdirectories for more config yaml files

  • prefix (Optional[str]) – prefix for names of configs found herein

  • delimiter (Optional[str]) – string to merge directories when recursively searching (default /)

Return type:

List[NamedTuple]

Returns:

A list of all config entries that were registered.

exception UnknownBehaviorError(term)

Bases: ValueError

While parsing command-line arguments, a meta config was referenced that was not registered

__init__(term)
parse_argv(argv, script_name=<class 'omnibelt.typing.unspecified_argument'>)

Parses command-line arguments and returns a config object that contains the parsed arguments.

Parameters:

  • argv (Sequence[str]) – raw command-line arguments

  • script_name (Optional[str]) – if not provided, the script name is inferred from argv

Return type:

AbstractConfig

Returns:

A config object containing the parsed arguments

Raises:

  • UnknownBehaviorError – if an unknown behavior config is encountered

  • ValueError – if an argument is invalid

find_local_config_entry(name, default=<class 'omnibelt.typing.unspecified_argument'>)

Finds the entry for a config by name.

Parameters:

  • name (str) – used to register the config

  • default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

NamedTuple

Returns:

The entry for the config

Raises:

ConfigNotFoundError – if the config is not registered

find_project_config_entry(name, default=<class 'omnibelt.typing.unspecified_argument'>)

Finds the entry for a config by name. Including checking the nonlocal projects.

Parameters:

  • name (str) – of the config file used to register the config

  • default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

NamedTuple

Returns:

The entry for the config

Raises:

ConfigNotFoundError – if the config is not registered

find_config_path(name, default=<class 'omnibelt.typing.unspecified_argument'>)

Finds the path to a config file by name. Including checking the nonlocal projects.

Parameters:

  • name (str) – of the config file used to register the config

  • default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

Path

Returns:

The path to the config file

Raises:

ConfigNotFoundError – if the config is not registered

load_raw_config(path)

Loads raw data of a config file (formats: JSON, YAML, TOML).

Parameters:

path (Union[str, Path]) – to the config file

Return type:

Union[Dict[str, Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], List[Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], str, int, float, bool, None]

Returns:

The raw data of the config file

Raises:

ValueError – if the config file is not a valid format

exception ConfigCycleError(bad)

Bases: ValueError

Indicates that a cycle in the config bases was detected.

__init__(bad)
create_config(configs=None, data=None, *, project=<class 'omnibelt.typing.unspecified_argument'>)

Creates a config object from a list of configs and raw data.

Parameters:

  • configs (Optional[Sequence[Union[str, Path]]]) – names of registered configs or paths to config files to load

  • data (Union[Dict[str, Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], List[Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], str, int, float, bool, None]) – raw data to merge into the config (e.g. from command line arguments)

  • project (Optional[AbstractProject]) – to associate the resulting config with

Return type:

AbstractConfig

Returns:

The config object

Raises:

ConfigNotFoundError – if a requested config is not registered

configurize(raw, **kwargs)

Converts raw data into a config object (using the config class of this manager ConfigNode).

Parameters:

  • raw (Union[Dict[str, Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], List[Union[Dict[str, JSONABLE], List[JSONABLE], str, int, float, bool, None]], str, int, float, bool, None]) – python data structure to convert (e.g. from a JSON or YAML file)

  • **kwargs (Any) – additional arguments to pass to the config class constructor

Return type:

AbstractConfig

Returns:

The config object

merge_configs(*configs)

Given a list of config objects, merges them into a single config object in the given order.

Parameters:

*configs (AbstractConfig) – objects to merge

Return type:

AbstractConfig

Returns:

The merged config object

static update_config(base, update)

Updates a config object with the contents of another config object.

Parameters:
Return type:

AbstractConfig

Returns:

The updated config object