Project Base¶

class omnifig.organization.workspaces.ProjectBase(path=None, profile=None, **kwargs)¶

Bases: AbstractProject

Generally, each workspace (e.g. repo, directory, package) should define its own project, which keeps track of all the configs and artifacts defined therein.

Projects don’t just contain all the project specific registries, but can also modify the behavior of the top-level methods such as (such as main(), run(), etc.).

It is recommended to subclass this class to create a custom project class with expected functionality (unlike AbstractProject) and automatically register it to the global project type registry.

global_type_registry = {'default': Class_Registry_Entry(name='default', cls=<class 'omnifig.organization.default.Project'>), 'general': Class_Registry_Entry(name='general', cls=<class 'omnifig.organization.workspaces.GeneralProject'>)}¶: Global registry for project types (usually used by the profile to create custom project types).

classmethod get_project_type(ident, default=<class 'omnibelt.typing.unspecified_argument'>)¶

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

Return type:: NamedTuple

class omnifig.organization.workspaces.GeneralProject(path, *, script_registry=None, config_manager=None, **kwargs)¶

Bases: ProjectBase

Project class that includes basic functionality such as a script registry and config manager.

info_file_names = {'.fig.project.yaml', '.fig.project.yml', '.omnifig.yaml', '.omnifig.yml', 'fig.project.yaml', 'fig.project.yml', 'omnifig.yaml', 'omnifig.yml'}¶

infer_path(path=None)¶

Infers the path of the project from the given path or the current working directory.

Return type:: Path

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

class Script_Registry(*args, _sister_registry_object=None, _sister_registry_cls=None, **kwargs)¶

Bases: Function_Registry

Registry for scripts (functions) that can be run from the command line.

entry_cls¶: alias of Script_Registry_Entry

Config_Manager¶: alias of ConfigManager

__init__(path, *, script_registry=None, config_manager=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()

load()¶

Loads all dependencies for the project including config files/directories, packages, and source files based on the contents of the project’s info file.

Packages are imported (or reloaded) and source files are executed locally.

Returns:: self
Return type:: Project

unload()¶: Unloads all dependencies for the project (opposite of load()).

load_configs(paths=())¶

Registers all specified config files and directories

Return type:: None

extract_info(other)¶

Extracts the info from the given project into this project.

Return type:: None

validate()¶

Validates the project and returns a new project with the validated info.

Return type:: AbstractProject

property name¶: The name of the project

property root: Path¶

The root directory of the project.

Return type:: Path

property info_path: Path¶

The path to the info file.

Return type:: Path

create_config(*parents, **parameters)¶: Creates a config with the given parameters using the config manager.

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

Parses the given command line arguments into a config object.

Return type:: AbstractConfig

behaviors()¶

Iterates over all behaviors associated with this project.

Return type:: Iterator[AbstractBehavior]

validate_run(config)¶

Validates the project self using the given config object before running it.

More specifically, this method calls validate_project() on all behaviors associated with the project with the config object as argument. If any of the behaviors returns a new project, this project is returned (and used for the script execution instead). Otherwise, None is returned.

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.

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

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

More specifically, this method does the following:

Activates the project (loads any specified source files or packages for the script, if not done yet).
Instantiates all behaviors associated with the project.
Parses the command line arguments into a config object.
Validates the current project using the config object and behaviors (see validate_run()).
Runs the script using the config object (see run_script()).
Cleans up the project (see cleanup()).

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) – Additional positional arguments to pass to the script.
kwargs (Any) – Additional keyword arguments to pass to the script.

Return type:

Any

Returns:

The output of the script.

exception NoScriptError¶

Bases: ValueError

Raised when the script name is not specified.

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

Runs the given script with the given config using this project.

Parameters:

config (AbstractConfig) – The config to use for running the script (must include the script under _meta.script_name).
args (Any) – Additional positional arguments to pass to the script.
kwargs (Any) – Additional keyword arguments to pass to the script.

Return type:

Any

Returns:

The return value of the script.

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¶

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.

exception UnknownArtifactTypeError¶

Bases: KeyError

Raised when an unknown artifact type is encountered.

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

Finds the artifact of the given type and registered with the given identifier.

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, including related and active base projects. 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, *, project=<class 'omnibelt.typing.unspecified_argument'>, **kwargs)¶

Registers the given artifact with the given type and identifier and any additional info.

Parameters:

artifact_type – The type of artifact to register.
ident (str) – The identifier of the artifact to register.
artifact (Union[str, Type, Callable]) – The artifact to register (usually a type or config file path).
project (Optional[AbstractProject]) – The project to register the artifact for (defaults to this project).
kwargs – Additional keyword arguments to pass to the registry.

Return type:

NamedTuple

Returns:

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

Raises:

UnknownArtifactTypeError – If the artifact type does not exist.

iterate_artifacts(artifact_type)¶

Iterates over all artifacts of the given type.

Parameters:: artifact_type (str) – The type of artifact to iterate over (e.g. ‘script’, ‘config’).
Return type:: Iterator[NamedTuple]
Returns:: An iterator over all artifacts of the given type.
Raises:: UnknownArtifactTypeError – If the artifact type does not exist.

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

Finds the config with the given name.

Parameters:

name (str) – name the config was registered with.
default (Optional[Any]) – default value to return if the config is not found.

Return type:

NamedTuple

Returns:

The config entry corresponding to the given name.

Raises:

UnknownArtifactError – If the config is not found and no default is given.

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 Path_Registry.register method

Return type:

NamedTuple

Returns:

The entry of the config file that was registered

iterate_configs()¶

Iterates over all registered config file entries.

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

register_config_dir(path, *, 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:

path (Union[str, Path]) – path to 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.

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

Finds the script with the given name.

Parameters:

name (str) – the script was registered with.
default (Optional[Any]) – default value to return if the script is not found.

Return type:

NamedTuple

Returns:

The script entry corresponding to the given name.

Raises:

UnknownArtifactError – If the script is not found and no default is given.

register_script(name, fn, *, description=None, hidden=None)¶

Register a script with the given name.

Parameters:

name (str) – to register the script under
fn (Callable[[AbstractConfig], Any]) – the script function (should expect the first positional argument to be the config object)
description (Optional[str]) – description of the script
hidden (Optional[bool]) – whether to hide the script from the list of available scripts
underscore) ((defaults to whether the name starts with an) –

Return type:

NamedTuple

Returns:

The entry of the script that was registered

iterate_scripts()¶

Iterates over all registered script entries.

Return type:: Iterator[NamedTuple]
Returns:: An iterator over all registered script entries.