Default Projects

class omnifig.organization.default.Project(path=None, *, creator_registry=None, component_registry=None, modifier_registry=None, **kwargs)

Bases: GeneralProject

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

Bases: Class_Registry

Registry for creators which determine how components are instantiated from the config.

entry_cls

alias of Creator_Registry_Entry

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

Bases: Class_Registry

Registry for components (classes) which can be instantiated through the config.

entry_cls

alias of Component_Registry_Entry

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

Bases: Class_Registry

Registry for modifiers (classes) which can modify components through the config by dynamically defining subclasses.

entry_cls

alias of Modifier_Registry_Entry

__init__(path=None, *, creator_registry=None, component_registry=None, modifier_registry=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()

related()

Iterate over all projects related to this one (based on related in the project info file).

Return type:

Iterator[AbstractProject]

Returns:

An iterator over all projects related to this one.

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

xray(artifact, *, include_nonlocal=True, as_list=False, sort=False, reverse=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’)

• include_nonlocal (Optional[bool]) – whether to include artifacts from non-local projects (related and active base projects)

• as_list (Optional[bool]) – instead of printing, return the list of artifacts

• sort (Optional[bool]) – sort the list of artifacts by name

• reverse (Optional[bool]) – reverse the order of 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

missing_related()

Iterate over all projects related to this one that cannot be found by the current profile.

Return type:

Iterator[str]

Returns:

An iterator over all projects related to this one that cannot be found by the current profile.

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

Finds the creator with the given name.

Parameters:

• name (str) – the creator was registered with.

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

Return type:

NamedTuple

Returns:

The creator entry corresponding to the given name.

Raises:

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

register_creator(name, typ, *, description=None)

Register a creator with the given name.

Parameters:

• name (str) – to register the script under

• typ (Type[AbstractCreator]) – the creator type (should be a subclass of AbstractCreator)

• description (Optional[str]) – description of the creator

Return type:

NamedTuple

Returns:

The entry of the creator that was registered

iterate_creators()

Iterates over all registered creator entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered creator entries.

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

Finds the component with the given name.

Parameters:

• name (str) – the component was registered with.

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

Return type:

NamedTuple

Returns:

The component entry corresponding to the given name.

Raises:

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

register_component(name, typ, *, creator=None, description=None)

Register a component with the given name.

Parameters:

• name (str) – to register the component under

• typ (Type) – the component type (recommended to be a subclass of Configurable)

• creator (Union[str, AbstractCreator]) – the creator to use for this component (if none is specified in the config)

• description (Optional[str]) – description of the component

Return type:

NamedTuple

Returns:

The entry of the component that was registered

iterate_components()

Iterates over all registered component entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered component entries.

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

Finds the modifier with the given name.

Parameters:

• name (str) – the modifier was registered with.

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

Return type:

NamedTuple

Returns:

The modifier entry corresponding to the given name.

Raises:

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

register_modifier(name, typ, *, description=None)

Register a modifier with the given name.

Parameters:

• name (str) – to register the modifier under

• typ (Type) – the modifier type (recommended to be a subclass of Configurable)

• description (Optional[str]) – description of the modifier

Return type:

NamedTuple

Returns:

The entry of the modifier that was registered

iterate_modifiers()

Iterates over all registered modifiers entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered modifier entries.

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

Finds the artifact of the given type and registered with the given identifier by searching first in the current project, then any related projects, and finally any active base projects specified by the profile. Note, that if the artifact ident may specify a project to search in by prefixing the ident with the project name and a colon (e.g. proj:ident).

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:

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.

• UnknownProjectError – If the project specified in the artifact ident is not found.

class omnifig.organization.default.Profile(data=None)

Bases: ProfileBase

class Project(path=None, *, creator_registry=None, component_registry=None, modifier_registry=None, **kwargs)

Bases: GeneralProject

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

Bases: Class_Registry

Registry for components (classes) which can be instantiated through the config.

entry_cls

alias of Component_Registry_Entry

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

Bases: Class_Registry

Registry for creators which determine how components are instantiated from the config.

entry_cls

alias of Creator_Registry_Entry

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

Bases: Class_Registry

Registry for modifiers (classes) which can modify components through the config by dynamically defining subclasses.

entry_cls

alias of Modifier_Registry_Entry

__init__(path=None, *, creator_registry=None, component_registry=None, modifier_registry=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()

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

Finds the artifact of the given type and registered with the given identifier by searching first in the current project, then any related projects, and finally any active base projects specified by the profile. Note, that if the artifact ident may specify a project to search in by prefixing the ident with the project name and a colon (e.g. proj:ident).

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:

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.

• UnknownProjectError – If the project specified in the artifact ident is not found.

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

Finds the component with the given name.

Parameters:

• name (str) – the component was registered with.

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

Return type:

NamedTuple

Returns:

The component entry corresponding to the given name.

Raises:

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

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

Finds the creator with the given name.

Parameters:

• name (str) – the creator was registered with.

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

Return type:

NamedTuple

Returns:

The creator entry corresponding to the given name.

Raises:

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

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

Finds the modifier with the given name.

Parameters:

• name (str) – the modifier was registered with.

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

Return type:

NamedTuple

Returns:

The modifier entry corresponding to the given name.

Raises:

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

iterate_components()

Iterates over all registered component entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered component entries.

iterate_creators()

Iterates over all registered creator entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered creator entries.

iterate_modifiers()

Iterates over all registered modifiers entries.

Return type:

Iterator[NamedTuple]

Returns:

An iterator over all registered modifier entries.

missing_related()

Iterate over all projects related to this one that cannot be found by the current profile.

Return type:

Iterator[str]

Returns:

An iterator over all projects related to this one that cannot be found by the current profile.

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

register_component(name, typ, *, creator=None, description=None)

Register a component with the given name.

Parameters:

• name (str) – to register the component under

• typ (Type) – the component type (recommended to be a subclass of Configurable)

• creator (Union[str, AbstractCreator]) – the creator to use for this component (if none is specified in the config)

• description (Optional[str]) – description of the component

Return type:

NamedTuple

Returns:

The entry of the component that was registered

register_creator(name, typ, *, description=None)

Register a creator with the given name.

Parameters:

• name (str) – to register the script under

• typ (Type[AbstractCreator]) – the creator type (should be a subclass of AbstractCreator)

• description (Optional[str]) – description of the creator

Return type:

NamedTuple

Returns:

The entry of the creator that was registered

register_modifier(name, typ, *, description=None)

Register a modifier with the given name.

Parameters:

• name (str) – to register the modifier under

• typ (Type) – the modifier type (recommended to be a subclass of Configurable)

• description (Optional[str]) – description of the modifier

Return type:

NamedTuple

Returns:

The entry of the modifier that was registered

related()

Iterate over all projects related to this one (based on related in the project info file).

Return type:

Iterator[AbstractProject]

Returns:

An iterator over all projects related to this one.

xray(artifact, *, include_nonlocal=True, as_list=False, sort=False, reverse=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’)

• include_nonlocal (Optional[bool]) – whether to include artifacts from non-local projects (related and active base projects)

• as_list (Optional[bool]) – instead of printing, return the list of artifacts

• sort (Optional[bool]) – sort the list of artifacts by name

• reverse (Optional[bool]) – reverse the order of 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

__init__(data=None)

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

Parameters:

• data (Union[str, Path, Dict, None]) – A file path to a yaml file, or a dictionary containing the info

• **kwargs – Other arguments passed on to super()

property projects: List[Project]

Convenience property for accessing the projects in the profile. Recemmended for debugging only.

Return type:

List[Project]

initialize(*projects, **kwargs)

Initializes the profile by activating it and then activating all projects specified, also adds the projects to the profile’s active base projects.

Parameters:

• *projects (str) – The names of projects to activate and add to the active base projects.

• **kwargs (Any) – Additional keyword arguments to pass to the project initialization methods.

Return type:

None

Returns:

None

iterate_base_projects()

Iterates through the active base projects in the profile.

The active base projects are those specified in the profile’s active-projects list, and are expected to be fallback projects for the current project for finding artifacts.

Return type:

Iterator[Project]

Returns:

An iterator over the active base projects.

iterate_projects()

Iterates through the projects in the profile in the order they were created. Note that this iterator will not include duplicates, even if the same project is loaded under multiple names.

Return type:

Iterator[Project]

Returns:

An iterator over the projects in the profile.

exception UnknownProjectError

Bases: KeyError

Raised when trying to get a project with an invalid path.

get_project(ident=None, is_current=None)

Gets the project with the given name/path. If no name/path is given, then the current project is returned. If the specified project has not been initialized, then it is created using the profile’s Project class (but it is not activated).

If a name is given, it must be the name of a project that has already been loaded, or it must be a key in the dict projects the profile’s info file where the value is the corresponding path.

If a path is given, the path may either be a yaml file (interpretted as the project’s info file) or a directory (in which case the project’s info file is assumed to be named .fig.project.yaml).

Parameters:

• ident (Union[str, Path]) – of the project to get. If not given, then the current project is returned.

• is_current (Optional[bool]) – if True, then the project is set as the current project.

Return type:

AbstractProject

Returns:

The project with the given name/path.

Raises:

• UnknownProjectError – If the project is not found.

• ValueError – If the project is found, but it has a name that a different project is already using.