Top-level Interface

omnifig.top.get_current_project()

Get the current project, assuming a profile is loaded, otherwise returns None

Return type:

AbstractProject

omnifig.top.get_project(ident=None)

Checks the profile to return (and possibly load) a project given the name or path ident

Return type:

AbstractProject

omnifig.top.switch_project(ident=None)

Switches the current project to the one of thegiven the project name or path ident

Return type:

AbstractProject

omnifig.top.iterate_projects()

Iterate over all loaded projects

Return type:

Iterator[AbstractProject]

omnifig.top.project_context(ident=None)

Context manager for switching to a project and then switching back

Return type:

ContextManager

omnifig.top.entry(script_name=<class 'omnibelt.typing.unspecified_argument'>)

Recommended entry point when running a script from the terminal. This is also the entry point for the fig command.

This collects the command line arguments in sys.argv and overrides the given script with script_name if it is provided

Parameters:

script_name (Optional[str]) – script to be run (maybe set with arguments) (overrides other arguments if provided)

Return type:

None

Returns:

None

omnifig.top.main(argv, script_name=<class 'omnibelt.typing.unspecified_argument'>)

Runs the desired script using the provided argv which are treated as command line arguments

Before running the script, this function initializes omni-fig using initialize(), and then cleans up after running using cleanup().

Parameters:

  • argv (Sequence[str]) – raw arguments as if passed in through the terminal

  • script_name (Optional[str]) – name of registered script to be run (maybe set with arguments) (overrides other arguments if provided)

Return type:

Any

Returns:

The output of script that is run

omnifig.top.run_script(script_name, config, *args, **kwargs)

Runs the specified script registered with script_name using the current project.

Parameters:

  • script_name (str) – Must be registered in the current project

  • config (AbstractConfig) – The config object passed to the script

  • *args (Any) – Manual arguments to be passed to the script

  • **kwargs (Any) – Manual keyword arguments to be passed to the script

Return type:

Any

Returns:

The output of the script, raises MissingScriptError if the script is not found

omnifig.top.run(config, *args, **kwargs)

Runs the specified script registered with script_name using the current project.

Parameters:

  • config (AbstractConfig) – The config object passed to the script

  • *args (Any) – Manual arguments to be passed to the script

  • **kwargs (Any) – Manual keyword arguments to be passed to the script

Return type:

Any

Returns:

The output of the script, raises MissingScriptError if the script is not found

omnifig.top.quick_run(script_name, *parents, **parameters)

Convenience function to run a simple script without a given config object, instead the config is entirely created using the provided parents and parameters.

Parameters:

  • script_name (str) – name of registered script that is to be run

  • *parents (str) – any names of registered configs to load

  • **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 additional arguments to be provided manually

Return type:

Any

Returns:

The script output

omnifig.top.initialize(*projects, **settings)

Initializes omni-fig by running the “princeps” file (if one exists), loading the profile, and any active projects. Additionally, loads the project in the current working directory (by default).

Generally, this function should be run before running any scripts, as it should register all necessary scripts, components, and configs when loading a project. It is automatically called when running the main() function (ie. running through the terminal). However, when starting scripts from other environments (such as in a jupyter notebook), this should be called manually after importing omnifig.

Parameters:

  • projects (str) – additional projects that should be initialized

  • settings (Any) – extra global settings (unused by default)

Return type:

None

Returns:

None

omnifig.top.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.

omnifig.top.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):

  1. Meta rules to modify the config loading process and run mode.

  2. Name of the script to run.

  3. Names of registered config files that should be loaded and merged (in order of precedence).

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