tlo.dependencies module

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

exception ModuleDependencyError

Bases: Exception

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

exception MultipleModuleInstanceError

Bases: Exception

Raised when multiple instances of the same module are registered.

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

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: Module | Type[Module], module_names_present: Set[str]) → Set[str]

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_missing_dependencies(module_instances: ~typing.Iterable[~tlo.core.Module], get_dependencies: ~typing.Callable[[~tlo.core.Module | ~typing.Type[~tlo.core.Module], ~typing.Set[str]], ~typing.Set[str]] = <function get_all_dependencies>) → Set[str]

Get the set of missing required dependencies if any from an iterable of modules.

Parameters:

  • module_instances – Iterable of Module subclass instances to get missing dependencies for.

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

Returns:

Set of Module subclass names corresponding to missing dependencies.

initialise_missing_dependencies(modules: Iterable[Module], **module_kwargs) → Set[Module]

Get list of initialised instances of any missing dependencies for an iterable of modules.

Parameters:

  • modules – Iterable of Module subclass instances to get instances of missing dependencies for.

  • module_kwargs – Any keyword arguments to use when initialising missing module dependencies.

Returns:

Set of Module subclass instances corresponding to missing dependencies.

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

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[[~tlo.core.Module | ~typing.Type[~tlo.core.Module], ~typing.Set[str]], ~typing.Set[str]] = <function get_init_dependencies>) → Generator[Module, None, None]

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

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]]

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.Set[~tlo.core.Module] | None = None, get_dependencies: ~typing.Callable[[~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]

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[[~tlo.core.Module | ~typing.Type[~tlo.core.Module], ~typing.Set[str]], ~typing.Set[str]] = <function get_all_dependencies>)

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.