Abstract Base Classes¶

class omnifig.abstract.AbstractConfig¶

Bases: object

Abstract class for config objects

exception SearchFailed¶

Bases: KeyError

Raised when a search fails

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 project: AbstractProject¶

Returns the project object associated with this config

Return type:: AbstractProject

property root: AbstractConfig¶

Returns the root node of the config object

Return type:: AbstractConfig

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

Exports the config object to the given path.

Parameters:

name (Union[str, Path]) – Name/path to export the config object to.
root (Union[str, Path, None]) – Path to use as the root of the config object (defaults to the current working directory).
fmt (Optional[str]) – Format to export the config object in (if None, will be inferred from the path).

Return type:

Optional[Path]

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

Returns a config object given by searching for the query in the config object.

Parameters:

query (Optional[str]) – The query to search for. If None, returns self.
default (Optional[Any]) – The default value to return if the query is not found.
silent (Optional[bool]) – If True, no message is reported based on the search.

Return type:

AbstractConfig

Returns:

The config object found by the query, or the default value if the query is not found, and returns self if no query is provided.

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

Returns the value found by searching for the query in the config object.

Parameters:

query (Optional[str]) – The query to search for. If None, returns default.
default (Optional[Any]) – The default value to return if the query is not found.
silent (Optional[bool]) – If True, no message is reported based on the search.

Return type:

Any

Returns:

The value found by the query, or the default value if the query is not found, and returns the value of self if no query is provided.

push_pull(addr, value, *, overwrite=True, silent=None)¶

Composes the push and pull methods into a single method. Can be used to set a value if none exists, and otherwise pull the existing value.

Parameters:

addr (str) – The address to push/pull from.
value (Any) – The value to push to the address.
overwrite (bool) – If True, the value is pushed to the address even if it already exists.
silent (Optional[bool]) – If True, no message is reported.

Return type:

Any

Returns:

The value found at the address.

push_peek(addr, value, *, overwrite=True, silent=None)¶

Composes the push and peek methods into a single method. Can be used to set a value if none exists, and otherwise peek the existing value.

Parameters:

addr (str) – The address to push/peek from.
value (Any) – The value to push to the address.
overwrite (bool) – If True, the value is pushed to the address even if it already exists.
silent (Optional[bool]) – If True, no message is reported.

Return type:

AbstractConfig

Returns:

The value found at the address.

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

Returns a config object given by searching for the queries in the config object. If multiple queries are provided, each query is searched if the previous query fails.

Parameters:

*queries – Any number of queries to search for.
default (Optional[Any]) – The default value to return if none of the queries are not found.
silent (Optional[bool]) – If True, no message is reported based on the search.

Return type:

AbstractConfig

Returns:

The config object found by the query, or the default value if none of the queries are found.

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

Returns the value found by searching for the queries in the config object.

Parameters:

*queries (str) – Any number of queries to search for.
default (Optional[Any]) – The default value to return if none of the queries are not found.
silent (Optional[bool]) – If True, no message is reported based on the search.

Return type:

Any

Returns:

The value found by the query, or the default value if none of the queries are found.

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

Sets the value at the given address.

Parameters:

addr (str) – The address to set the value at.
value (Any) – The value to set.
overwrite (bool) – If True, the value is set even if it already exists.
silent (Optional[bool]) – If True, no message is reported.

Return type:

bool

Returns:

True if the value was set, False if the value was not set.

update(update)¶

Updates the config object with the given config object (recursively overwriting common keys).

Parameters:: update (AbstractConfig) – Config object to update with.
Return type:: AbstractConfig
Returns:: The updated config object (self).

silence(silent=True)¶

Context manager to silence the config object.

Parameters:: silent (bool) – If True, no messages are reported when querying the config object.
Return type:: ContextManager
Returns:: Context manager to silence the config object.

peek_named_children(*, silent=None)¶

Returns an iterator of the child config objects of self together with their keys.

Parameters:: silent (Optional[bool]) – If True, no messages are reported.
Return type:: Iterator[Tuple[str, AbstractConfig]]
Returns:: An iterator of the child config objects of self together with their keys.

peek_children(*, silent=None)¶

Returns an iterator of the child config objects of self.

Parameters:: silent (Optional[bool]) – If True, no messages are reported.
Return type:: Iterator[AbstractConfig]
Returns:: An iterator of the child config objects of self.

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

Returns an iterator of the child values of self together with their keys.

Parameters:

force_create (Optional[bool]) – If True, creates new child values even if they already exist.
silent (Optional[bool]) – If True, no messages are reported.

Return type:

Iterator[Tuple[str, Any]]

Returns:

An iterator of the child values of self together with their keys.

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

Returns an iterator of the child values of self.

Parameters:

force_create (Optional[bool]) – If True, creates new child values even if they already exist.
silent (Optional[bool]) – If True, no messages are reported.

Return type:

Iterator[Any]

Returns:

An iterator of the child values of self.

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

Creates a new value based on the contents of self silently.

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.

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

Composes the peek and create methods into a single method.

Can be used to create a value using the config object found with the query.

Parameters:

query – The query to search for.
default (Optional[Any]) – If provided, the value is created using the default config object.
*args – Manual arguments to pass to the value constructor.
**kwargs – Manual keyword arguments to pass to the value constructor.

Returns:

The newly created value or default if the query is not found.

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.

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

Composes the peek and process methods into a single method.

Parameters:

query – The query to search for.
default (Optional[Any]) – If provided, the value is processed using the default config object.
*args – Manual arguments to pass to the value constructor. (ignored if a value has already been created)
**kwargs – Manual keyword arguments to pass to the value constructor.
created) ((ignored if a value has already been) –

Returns:

The processed value or default if the query is not found.

class omnifig.abstract.AbstractConfigurable¶

Bases: object

Abstract mix-in for objects that can be constructed using a config object.

classmethod init_from_config(config, args=None, kwargs=None, *, silent=None)¶

Constructor to initialize a class informed by the config object config.

It is recommended that this should be a parent of any class that is registered as a component or modifier.

Parameters:

config (AbstractConfig) – Config object to fill in any needed parameters.
args (Tuple) – Manually specified arguments to pass to the constructor.
kwargs (Dict[str, Any]) – Manually specified keyword arguments to pass to the constructor.
silent (Optional[bool]) – If True, no messages are reported when querying the config object.

Return type:

AbstractConfigurable

Returns:

Initialized instance of this class.

class omnifig.abstract.AbstractCertifiable¶

Bases: AbstractConfigurable

Abstract mix-in for objects that can must be certified after intialization.

class omnifig.abstract.AbstractConfigManager¶

Bases: object

Abstract class for config managers.

exception ConfigNotRegistered¶

Bases: KeyError

A config was not registered

ConfigNode = None¶

register_config(name, path)¶

Registers a path as a config file with the given name.

Parameters:

name (str) – Name to register the config file under.
path (Union[str, Path]) – Path to the config file.

Return type:

NamedTuple

Returns:

The entry that was registered (should contain at least the attributes for the name and path).

register_config_dir(root)¶

Recursively registers all config files found in the given directory.

Parameters:: root (Union[str, Path]) – Path to the directory of the config files that should be registered.
Return type:: List[NamedTuple]
Returns:: A list of the names of the registered config files.

iterate_configs()¶

Iterates over all registered config files.

Return type:: Iterator[NamedTuple]
Returns:: An iterator over all registered config files.

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

Finds the entry for the config file with the given name in the registry.

Parameters:

name (str) – Name of the config file to find.
default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

NamedTuple

Returns:

The entry for the config file with the given name.

Raises:

KeyError – If the config file 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 the config file with the given name in the registry.

Parameters:

name (str) – Name of the config file to find.
default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

Path

Returns:

The path to the config file with the given name.

Raises:

KeyError – If the config file is not registered.

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

Parses the given arguments and returns a config object.

Arguments are expected in the following order (all of which are optional):

Meta rules to modify the config loading process and run mode.
Name of the script to run.
Names of registered config files that should be loaded and merged (in order of precedence).
Manual config parameters (usually keys, prefixed by -- and corresponding values)

Parameters:

argv (Sequence[str]) – List of arguments to parse (expected to be sys.argv[1:]).
script_name (Optional[str]) – Manually specified name of the script (defaults to what is specified in the resulting config).

Return type:

AbstractConfig

Returns:

Config object containing the parsed arguments.

create_config(configs=None, data=None)¶

Creates a config object from the given config file names and provided arguments.

Parameters:

configs (Optional[Sequence[str]]) – Names of registered config files to load and merge (in order of precedence).
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]) – Manual config parameters to populate the config object with.

Return type:

AbstractConfig

Returns:

Config object resulting from loading/merging configs and including data.

load_raw_config(path)¶

Loads a config file from the given path and returns the raw config data (made up of standard python objects, such as dict and list).

Parameters:

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

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:

Config data loaded from the given path.

Raises:

FileNotFoundError – If the config file does not exist.
ValueError – If the config file cannot be loaded.

configurize(raw)¶

Converts the given raw config data into a config object.

Raw config data can include primitives, lists, and dicts (including OrderedDict or tuples), but should not include any other types.

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]) – Raw config data to convert into a config object.
Return type:: AbstractConfig
Returns:: Config object created from the given raw config data.

merge_configs(*configs)¶

Merges the given config objects into a single config object.

Including recursively merging any nested config objects and overwriting any duplicate keys in reverse provided order (so the configs should be provided in order of precedence).

Parameters:: *configs (AbstractConfig) – Provided config objects to merge.
Return type:: AbstractConfig
Returns:: Config object resulting from merging the given config objects.

static update_config(base, update)¶

Updates the config object with the given config object (recursively overwriting common keys).

Parameters:

base (AbstractConfig) – Config object to update.
update (AbstractConfig) – Config object to update base with.

Return type:

AbstractConfig

Returns:

The updated config object base.

class omnifig.abstract.AbstractCustomArtifact¶

Bases: object

static top(config, *args, **kwargs)¶

Return type:: Any

get_wrapped()¶

Return type:: Union[Callable, Type]

class omnifig.abstract.AbstractCreator(config, **kwargs)¶

Bases: object

Abstract class for creators.

classmethod replace(creator, config, **kwargs)¶

Extracts any required information from the required creator to create and return a new creator.

Parameters:

creator (AbstractCreator) – base creator to extract information from.
config (AbstractConfig) – config object to initialize the new creator with.
**kwargs – other keyword arguments to pass to the new creator initialization.

Return type:

AbstractCreator

Returns:

New creator created from the given creator and config.

__init__(config, **kwargs)¶

create(config, *args, **kwargs)¶

Creates an object from the given config node and other arguments.

Parameters:

config (AbstractConfig) – Config node to create the object from.
*args (Any) – Manual arguments to pass to the object.
**kwargs (Any) – Manual keyword arguments to pass to the object.

Return type:

Any

Returns:

Object created from the given config node and other arguments.

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

Creates an object from the given config node and other arguments.

Parameters:

config (AbstractConfig) – Config node to create the object from.
args (Optional[Tuple]) – Manual arguments to pass to the object.
kwargs (Optional[Dict[str, Any]]) – Manual keyword arguments to pass to the object.

Return type:

Any

Returns:

Object created from the given config node and other arguments.

class omnifig.abstract.AbstractRunMode(*args, **kwargs)¶

Bases: Activatable

Abstract class for run modes. Run modes include Projects and Profiles

main(argv, script_name=None)¶

Runs the script with the given arguments using the config object obtained by parsing argv.

Parameters:

argv (Sequence[str]) – List of top-level arguments (expected to be sys.argv[1:]).
script_name (Optional[str]) – specified name of the script
object). ((defaults to what is specified in argv when it is parsed into a config) –

Return type:

Any

Returns:

The output of the script.

run_script(script_name, config, *args, **kwargs)¶

Runs the script with the given arguments using run() of the current project.

Parameters:

script_name (str) – The script name to run (must be registered).
config (AbstractConfig) – Config object to run the script with (must include the script under _meta.script_name).
*args (Any) – Manual arguments to pass to the script.
**kwargs (Any) – Manual keyword arguments to pass to the script.

Return type:

Any

Returns:

The output of the script.

run(config, *args, **kwargs)¶

Runs a script with the given config object and other arguments.

Before running the script using run_local(), the config object is validated with validate_run(), which can modify the run mode.

Parameters:

config (AbstractConfig) – Config object to run the script with (must include the script under _meta.script_name).
args (Any) – Manual arguments to pass to the script.
kwargs (Any) – Manual keyword arguments to pass to the script.

Return type:

Any

Returns:

The output of the script.

cleanup()¶

After running the script through main(), this method is called to clean up any resources used by the run mode.

Returns:: None

behaviors()¶

Iterates over all behaviors associated with this project.

Return type:: Iterator[AbstractBehavior]

validate_run(config)¶

Validates the config object before running the script.

Parameters:: config (AbstractConfig) – Config object to validate.
Return type:: Optional[AbstractRunMode]
Returns:: None if the config is valid, otherwise the run mode to transfer to.

parse_argv(argv, *, script_name=None)¶

Parses the given arguments and returns a config object.

Arguments are expected in the following order (all of which are optional):

Meta rules to modify the config loading process and run mode.
Name of the script to run.
Names of registered config files that should be loaded and merged (in order of precedence).
Manual config parameters (usually keys, prefixed by -- and corresponding values)

Parameters:

argv (Sequence[str]) – List of arguments to parse (expected to be sys.argv[1:]).
script_name (Optional[str]) – Manually specified name of the script (defaults to what is specified in the resulting config).

Return type:

AbstractConfig

Returns:

Config object containing the parsed arguments.

class omnifig.abstract.AbstractProject(path=None, profile=None, **kwargs)¶

Bases: AbstractRunMode, FileInfo, Activatable

Abstract class for projects. Projects track artifacts (eg. configs and components) in registries and manage loading configs and running scripts.

__init__(path=None, profile=None, **kwargs)¶

Loads the info if the provided data is a file path.

Parameters:

data – A file path to a yaml file, or a dictionary containing the info
**kwargs – Other arguments passed on to super()

property profile: AbstractProfile¶

Profile object that the project is associated with.

Return type:: AbstractProfile
Returns:: Profile object.

nonlocal_projects()¶

Iterator over all projects that are related to this one, followed by all active base projects of the profile (without repeating any projects).

Return type:: Iterator[NamedTuple]
Returns:: An iterator over all projects that are related to this one, followed by all active base projects

behaviors()¶

Iterates over all behavior instances associated with this project.

By default, this creates an instance for all behaviors in the profile.

Return type:: Iterator[NamedTuple]
Returns:: Iterator over meta rules in order of priority (highest -> least).

exception UnknownArtifactError(artifact_type, ident)¶

Bases: NotFoundError

Raised when trying to find an artifact that is not registered.

__init__(artifact_type, ident)¶

xray(artifact, *, sort=False, reverse=False, as_list=False)¶

Prints a list of all artifacts of the given type accessible from this project (including related and active base projects).

Parameters:

artifact (str) – artifact type (e.g. ‘script’, ‘config’)
sort (Optional[bool]) – sort the list of artifacts by name
reverse (Optional[bool]) – reverse the order of the list of artifacts
as_list (Optional[bool]) – instead of printing, return the list of artifacts

Returns:

if as_list is True, returns a list of artifacts

Return type:

list

Raises:

UnknownArtifactTypeError – if the given artifact type does not exist

find_local_artifact(artifact_type, ident, default=<class 'omnibelt.typing.unspecified_argument'>)¶

Finds the artifact with the given type and identifier in self without checking related projects or active projects in the profile.

Parameters:

artifact_type (str) – The type of artifact to find.
ident (str) – The identifier of the artifact to find.
default (Optional[Any]) – The default value to return if the artifact is not found.

Return type:

Optional[NamedTuple]

Returns:

The artifact entry from the registry corresponding to the given type.

Raises:

UnknownArtifactTypeError – If the artifact type is not registered.
UnknownArtifactError – If the artifact is not found and no default is given.

find_artifact(artifact_type, ident, default=<class 'omnibelt.typing.unspecified_argument'>)¶

Finds an artifact in the project’s registries. Artifacts are data or functionality such as configs and components.

Parameters:

artifact_type (str) – Type of artifact to find (eg. ‘config’ or ‘component’).
ident (str) – Name of the artifact that was registered.
default (Optional[Any]) – Default value to return if the artifact is not found.

Return type:

NamedTuple

Returns:

Artifact object, or, if a default value is given and artifact is not found.

Raises:

UnknownArtifactError – if the artifact is not found and no default is specified.

register_artifact(artifact_type, ident, artifact, **kwargs)¶

Registers a new artifact in the project’s registries. Overwrites any existing artifact with the same name.

Parameters:

artifact_type (str) – Type of artifact to register (eg. ‘config’ or ‘component’).
ident (str) – Name of the artifact to be registered.
artifact (Union[Type, Callable]) – Artifact object to register (usually a function, type, or path).
**kwargs (Any) – Optional additional parameters to store with the artifact.

Return type:

NamedTuple

Returns:

Registration entry for the artifact.

iterate_artifacts(artifact_type)¶

Iterates over all artifacts of the given type in the project’s registries.

Parameters:: artifact_type (str) – Type of artifact to iterate (eg. ‘config’ or ‘component’).
Return type:: Iterator[NamedTuple]
Returns:: Iterator over all artifacts of the given type.

create_config(*configs, **parameters)¶

Creates a new config object with the given parameters.Creates a config object from the given config file names and provided parameters.

Parameters:

*configs (str) – Names of registered config files to load and merge (in order of precedence).
**parameters (Union[str, int, float, bool, None]) – Manual config parameters to populate the config object with.

Return type:

AbstractConfig

Returns:

Config object.

quick_run(script_name, *configs, **parameters)¶

Composes create_config() and :func:`run_script() into a single method to first create a config object and then run the specified script.

Parameters:

script_name (str) – Name of the script to run (should be registered).
*configs (str) – Names of registered config files to load and merge (in order of precedence).
**parameters (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]) – Manual config parameters to populate the config object with.

Return type:

Any

Returns:

Output of the script.

class omnifig.abstract.AbstractProfile(data=None, **kwargs)¶

Bases: FileInfo, Activatable

Abstract classes for profiles. Profiles manage projects and provide meta rules. Unlike projects, generally a runtime should only use a single global instance of a profile.

classmethod get_project_type(ident)¶

Gets the project type entry for the given identifier (from a registry).

Parameters:: ident (str) – Name of the registered project type.
Return type:: NamedTuple
Returns:: Project type entry.

classmethod replace_profile(profile)¶

Replaces the current profile instance with the given profile. This is used to set the global profile.

Parameters:: profile (AbstractProfile) – New profile instance.
Return type:: AbstractProfile
Returns:: Old profile instance (which is now replaced).

classmethod get_profile()¶

Gets the current profile instance of the runtime environment.

Return type:: AbstractProfile
Returns:: Profile instance.

classmethod register_behavior(name, typ, *, description=None)¶

Registers a new behavior in the profile.

Behaviors are classes which are instantiated and managed by .

Parameters:

name (str) – Name of the behavior.
typ (Type[AbstractBehavior]) – Behavior class (recommended to subclass AbstractBehavior).
description (Optional[str]) – Description of the behavior.

Return type:

NamedTuple

Returns:

Registration entry for the behavior.

classmethod get_behavior(name)¶

Gets the behavior entry for the given identifier (from the registry).

Parameters:: name (str) – Name of the registered behavior.
Return type:: NamedTuple
Returns:: Behavior entry.

classmethod iterate_behaviors()¶

Iterates over all registered behaviors.

Return type:: Iterator[NamedTuple]
Returns:: Iterator over all behavior entries.

entry(script_name=None)¶

Primary entry point for the profile. This method is called when using the fig command.

Parameters:: script_name (Optional[str]) – Manually specified script name to run (if not provided, will be parsed from sys.argv).
Return type:: None
Returns:: None

initialize(*projects)¶

Initializes the specified projects (including activating them, which generally registers all associated configs and imports files and packages)

Parameters:: *projects (str) – Identifiers of projects to initialize (activates the current project only, if none is provided).
Return type:: None
Returns:: None

main(argv, *, script_name=None)¶

Runs the script with the given arguments using main() of the current project.

Parameters:

argv (Sequence[str]) – List of top-level arguments (expected to be sys.argv[1:]).
script_name (Optional[str]) – specified name of the script
object). ((defaults to what is specified in argv when it is parsed into a config) –

Return type:

Any

Returns:

The output of the script.

run_script(script_name, config, *args, **kwargs)¶

Runs the script registered with the given name and the given arguments using run_script() of the current project.

Parameters:

script_name (str) – Name of the script to run (must be registered).
config (AbstractConfig) – Config object to run the script with.
*args (Any) – Manual arguments to pass to the script.
**kwargs (Any) – Manual keyword arguments to pass to the script.

Return type:

Any

Returns:

The output of the script.

run(config, *, args=None, kwargs=None)¶

Runs the script with the given arguments using run() of the current project.

This method assumes the script_name is already contained in the config, otherwise use run_script().

Parameters:

config (AbstractConfig) – Config object to run the script with (must include the script under _meta.script_name).
args (Optional[Tuple]) – Manual arguments to pass to the script.
kwargs (Optional[Dict[str, Any]]) – Manual keyword arguments to pass to the script.

Return type:

Any

Returns:

The output of the script.

quick_run(script_name, *configs, **parameters)¶

Creates a config object and runs the script using quick_run() of the current project.

Parameters:

script_name (str) – Name of the script to run (must be registered).
*configs (str) – Names of registered config files to load and merge (in order of precedence).
**parameters (Any) – Manual config parameters to populate the config object with.

Return type:

Any

Returns:

Output of the script.

cleanup()¶

Calls cleanup() of the current project. Generally not needed to be called manually.

Return type:: None
Returns:: None

create_config(*configs, **parameters)¶

Process the provided data to create a config object (using the current project).

Parameters:

configs (str) – usually a list of parent configs to be merged
parameters (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]) – any manual parameters to include in the config object

Return type:

AbstractConfig

Returns:

Config object resulting from loading/merging configs and including data.

parse_argv(argv, script_name=None)¶

Parses the given arguments and returns a config object.

Arguments are expected in the following order (all of which are optional):

Meta rules to modify the config loading process and run mode.
Name of the script to run.
Names of registered config files that should be loaded and merged (in order of precedence).
Manual config parameters (usually keys, prefixed by -- and corresponding values)

Parameters:

argv (Sequence[str]) – List of arguments to parse (expected to be sys.argv[1:]).
script_name – Manually specified name of the script (defaults to what is specified in the resulting config).

Return type:

AbstractConfig

Returns:

Config object containing the parsed arguments.

extract_info(other)¶

Extract data from the provided profile instance and store it in self.

Recommended to use if a project expects a custom profile different from the currently used one.

Parameters:: profile – Base profile instance.
Return type:: None
Returns:: None

get_current_project()¶

Gets the current project instance.

Return type:: AbstractProject
Returns:: Current project instance.

switch_project(ident=None)¶

Switches the current project to the one with the given identifier.

Parameters:: ident (Optional[str]) – Name of the project to switch to, defaults to the default project (with name: None).
Return type:: AbstractProject
Returns:: New current project instance.

project_context(ident=None)¶

Context manager to temporarily switch to a different current project.

Parameters:: ident (Union[str, AbstractProject, None]) – Name of the project to switch to, defaults to the default project (with name: None).
Return type:: ContextManager[AbstractProject]
Returns:: Context manager to switch to the specified project.

iterate_projects()¶

Iterates over all loaded projects.

Return type:: Iterator[AbstractProject]
Returns:: Iterator over all loaded project instances.

get_project(ident=None)¶

Gets the project with the given identifier, if the project is not already loaded, it will be loaded.

Parameters:: ident (Optional[str]) – Name of the project to get, defaults to the default project (with name: None).
Return type:: AbstractProject
Returns:: Project instance.

class omnifig.abstract.AbstractBehavior(project, **kwargs)¶

Bases: object

Interface for meta rules.

__init__(project, **kwargs)¶

Behaviors are usually instantiated by the project at the beginning main() method.

Otherwise, if main() is not used, the behaviors are instantiated in run() right before the behaviors are filtered using include().

Parameters:

project (AbstractProject) – Project of this behavior instance.
**kwargs (Any) – Additional keyword arguments (unused).

exception TerminationFlag(out=None)¶

Bases: KeyboardInterrupt

Raised if the subsequent script should not be run.

__init__(out=None)¶

Prevents the subsequent script from being run.

Parameters:: out (Any) – User-defined output to be returned instead of the output of the script.

out = None¶

static parse_argv(meta, argv, script_name=None)¶

Optionally modifies the arguments when the project’s main() is called.

Parameters:

meta (Dict[str, Any]) – Meta-data extracted from the argv so far (can be modified here).
argv (List[str]) – List of arguments to parse (expected to be sys.argv[1:]).
script_name (Optional[str]) – Manually specified name of the script (if not provided, it will be parsed from argv).

Return type:

Optional[List[str]]

Returns:

Modified list of arguments (or None if no modification is needed).

static validate_project(config)¶

Validates the project (provided in constructor) using the given config object before running it.

If a different project should be used, it can be returned here.

Parameters:: config (AbstractConfig) – The config object to use for validation.
Return type:: Optional[AbstractProject]
Returns:: The new project to use for the script execution or None if no new project was returned.

static include(meta)¶

Checks if the current behavior should be included in the subsequent script execution.

Parameters:: meta (AbstractConfig) – Meta config to configure behavior and script execution.
Return type:: bool
Returns:: True if the behavior should be included, False otherwise.

static pre_run(meta, config)¶

Runs before the script is executed, within the project run().

Parameters:

meta (AbstractConfig) – Meta config to configure behavior and script execution.
config (AbstractConfig) – Config object which will be passed to the script.

Return type:

Optional[AbstractConfig]

Returns:

New config object to pass to the script instead (or None to use the original config).

Raises:

TerminationFlag – If the subsequent script should not be run.

exception IgnoreException(out=None)¶

Bases: Exception

Raised if the underlying exception raised while running the script should be ignored.

__init__(out=None)¶

Instead of raising the exception, out will be returned.

Parameters:: out (Any) – User-defined output to be returned instead of raising the exception.

static handle_exception(meta, config, exc)¶

Runs if the script raises an exception.

Parameters:

meta (AbstractConfig) – Meta config to configure behavior and script execution.
config (AbstractConfig) – Config object to run the script with.
exc (Exception) – Exception that was raised.

Return type:

None

Returns:

None

Raises:

IgnoreException – If the exception should be ignored.
TerminationFlag – If the subsequent behaviors should not be run.

static post_run(meta, config, output)¶

Function called after the script is run. If the function returns a value, it will be used as the output of the script.

Parameters:

meta (AbstractConfig) – Meta config to configure behavior and script execution.
config (AbstractConfig) – Config object used to run the script with.
output (Any) – Output of the script.

Return type:

Optional[Any]

Returns:

New output of the script, or None to use the original output.

Raises:

TerminationFlag – If the subsequent behaviors should not be run.

static cleanup()¶

Function called at the end of the project main() during cleanup.

Note that this is only called if the project main(). To define a cleanup function for the behavior that is called every time a script is run, use post_run().

Returns:: None

class omnifig.config.abstract.AbstractSearch(origin, queries, default, **kwargs)¶

Bases: object

Abstract class for search objects used by the config object to find the format data

__init__(origin, queries, default, **kwargs)¶

exception SearchFailed(*queries)¶

Bases: SearchFailed

Raised when a search fails to find a value

__init__(*queries)¶

find_node(silent=None)¶

Finds the node that contains the product

Return type:: AbstractConfig

find_product(silent=None)¶

Finds the node that contains the product, and then extracts the product

Return type:: Any

static sub_search(origin)¶

Creates a context manager for new searches to be able to reference the original search origin

Return type:: ContextManager

class omnifig.config.abstract.AbstractReporter¶

Bases: object

Abstract class for reporters used by the config object to report changes

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

Prints the given message to the console

Return type:: str

get_key(trace)¶

Returns the key of the node resulting of the search

Return type:: str

report_node(node, *, silent=None)¶

Reports information about a config node

Return type:: Optional[str]

report_product(node, *, silent=None)¶

Reports the product of a config node

Return type:: Optional[str]

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

Reports a config node defaulted to the given value

Return type:: Optional[str]

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

Reports the start of an iterator over the config node

Return type:: Optional[str]

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

Reports that the product of the given node is being reused

Return type:: Optional[str]

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

Reports that the product of the given node is a primitive

Return type:: Optional[str]

create_container(node, *, silent=None)¶

Reports that the product of the given node is a container (e.g. a dict or list)

Return type:: Optional[str]

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

Reports that the product of the given node is a component

Return type:: Optional[str]