tlo.dependencies module

Functions for getting, checking and sorting dependencies of Module subclasses.

exception ModuleDependencyError[source]

Bases: Exception

Raised when a module dependency is missing or there are circular dependencies.

exception MultipleModuleInstanceError[source]

Bases: Exception

Raised when multiple instances of the same module are registered.

get_init_dependencies(module: Union[Module, Type[Module]], module_names_present: Set[str]) → Set[str][source]

Get the initialisation dependencies for a Module subclass.

Parameters

  • module – Module subclass to get dependencies for.

  • module_names_present – Set of names of Module subclasses that will be present in simulation to use to select optional initialisation dependencies.

Returns

Set of Module subclass names corresponding to initialisation dependencies of module, including any optional dependencies present.

get_all_dependencies(module: Union[Module, Type[Module]], module_names_present: Set[str]) → Set[str][source]

Get all dependencies for a Module subclass.

Parameters

  • module – Module subclass to get dependencies for.

  • module_names_present – Set of names of Module subclasses that will be present in simulation to use to select optional initialisation dependencies.

Returns

Set of Module subclass names corresponding to dependencies of module, including any optional dependencies present.

get_all_required_dependencies(module: Union[Module, Type[Module]], module_names_present: Optional[Set[str]] = None) → Set[str][source]

Get all non-optional dependencies for a Module subclass.

Parameters

  • module – Module subclass to get dependencies for.

  • module_names_present – Set of names of Module subclasses that will be present in simulation to use to select optional initialisation dependencies. Unused by this function, but kept as an argument to ensure a consistent interface with the other dependency-getter functions.

Returns

Set of Module subclass names corresponding to non-optional dependencies of module.

topologically_sort_modules(module_instances: ~typing.Iterable[~tlo.core.Module], get_dependencies: ~typing.Callable[[~typing.Union[~tlo.core.Module, ~typing.Type[~tlo.core.Module]], ~typing.Set[str]], ~typing.Set[str]] = <function get_init_dependencies>) → Generator[Module, None, None][source]

Generator which yields topological sort of modules based on their dependencies.

A topological sort of a dependency graph is ordered such that any dependencies of a node in the graph are guaranteed to be yielded before the node itself. This implementation uses a depth-first search algorithm (https://en.wikipedia.org/wiki/Topological_sorting#Depth-first_search).

Parameters

  • module_instances – The set of module instances to topologically sort. The yielded module instances will consist of all nodes in this set which must include instances of their (recursive) dependencies.

  • get_dependencies – Function which given a module gets the set of module dependencies. Defaults to returing the Module.INIT_DEPENDENCIES class attribute.

Raises

  • ModuleDependencyError – Raised when a module dependency is missing from module_instances or a module has circular dependencies.

  • MultipleModuleInstanceError – Raised when multiple instances of the same module are passed in module_instances.

Returns

Generator which yields module instances in topologically sorted order.

is_valid_tlo_module_subclass(obj: Any, excluded_modules: Set[str]) → bool[source]

Determine whether object is a Module subclass and not in an excluded set.

Parameters

  • obj – Object to check if Module subclass.

  • excluded_modules – Set of names of Module subclasses to force check to return False for.

Returns

True is obj is a _strict_ subclass of Module and not in the excluded_modules set.

get_module_class_map(excluded_modules: Set[str]) → Mapping[str, Type[Module]][source]

Constructs a map from Module subclass names to class objects.

Parameters

excluded_modules – Set of Module subclass names to exclude from map.

Returns

A mapping from unqualified Module subclass to names to the correponding class objects. This adds an implicit requirement that the names of all the Module subclasses are unique.

Raises

RuntimError – Raised if multiple Module subclasses with the same name are defined (and not included in the exclude_modules set).

get_dependencies_and_initialise(*module_classes: ~typing.Type[~tlo.core.Module], module_class_map: ~typing.Mapping[str, ~typing.Type[~tlo.core.Module]], excluded_module_classes: ~typing.Optional[~typing.Set[~tlo.core.Module]] = None, get_dependencies: ~typing.Callable[[~typing.Union[~tlo.core.Module, ~typing.Type[~tlo.core.Module]], ~typing.Set[str]], ~typing.Set[str]] = <function get_init_dependencies>, **module_class_kwargs) → Generator[Module, None, None][source]

Generate a sequence of Module instances including all dependencies.

The generated sequence of initialised Module subclass instances will correspond to all the (recursive) dependencies of the seed Module subclasses in module_classes.

Parameters

  • module_classes – Module subclass(es) to seed dependency search with.

  • module_class_map – Mapping from Module subclass names to classes.

  • excluded_module_classes – Any Module subclasses to not yield instances of in the returned generator.

  • get_dependencies – Function which given a module gets the set of module dependencies. Defaults to returing the Module.INIT_DEPENDENCIES class attribute.

  • module_class_kwargs – Any keyword arguments to pass to initialisers for Module subclasses if present in their __init__ method signature.

Returns

Sequence of initialised Module subclass instances corresponding to all of the Module subclasses and their the (recursive) dependencies in the seed module_classes.

check_dependencies_present(module_instances: ~typing.Iterable[~tlo.core.Module], get_dependencies: ~typing.Callable[[~typing.Union[~tlo.core.Module, ~typing.Type[~tlo.core.Module]], ~typing.Set[str]], ~typing.Set[str]] = <function get_all_dependencies>)[source]

Check whether an iterable of modules contains the required dependencies.

Parameters

  • module_instances – Iterable of Module subclass instances to check.

  • get_dependencies – Callable which extracts the set of dependencies to check for from a module instance. Defaults to extracting all dependencies.

Raises

ModuleDependencyError – Raised if any dependencies are missing.