Coverage for mlos_bench/mlos_bench/services/types/config_loader_type.py: 67%
21 statements
« prev ^ index » next coverage.py v7.6.10, created at 2025-01-21 01:50 +0000
1#
2# Copyright (c) Microsoft Corporation.
3# Licensed under the MIT License.
4#
5"""Protocol interface for helper functions to lookup and load configs."""
7from __future__ import annotations
9from collections.abc import Iterable
10from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
12from mlos_bench.config.schemas.config_schemas import ConfigSchema
13from mlos_bench.tunables.tunable import TunableValue
15# Avoid's circular import issues.
16if TYPE_CHECKING:
17 from mlos_bench.environments.base_environment import Environment
18 from mlos_bench.services.base_service import Service
19 from mlos_bench.tunables.tunable_groups import TunableGroups
22@runtime_checkable
23class SupportsConfigLoading(Protocol):
24 """Protocol interface for helper functions to lookup and load configs."""
26 # Needed by pyright
27 # pylint: disable=unnecessary-ellipsis,redundant-returns-doc
29 def get_config_paths(self) -> list[str]:
30 """
31 Gets the list of config paths this service will search for config files.
33 Returns
34 -------
35 list[str]
36 """
37 ...
39 def resolve_path(self, file_path: str, extra_paths: Iterable[str] | None = None) -> str:
40 """
41 Prepend the suitable `_config_path` to `path` if the latter is not absolute. If
42 `_config_path` is `None` or `path` is absolute, return `path` as is.
44 Parameters
45 ----------
46 file_path : str
47 Path to the input config file.
48 extra_paths : Iterable[str]
49 Additional directories to prepend to the list of search paths.
51 Returns
52 -------
53 path : str
54 An actual path to the config or script.
55 """
56 ...
58 def load_config(
59 self,
60 json: str,
61 schema_type: ConfigSchema | None,
62 ) -> dict | list[dict]:
63 """
64 Load JSON config file. Search for a file relative to `_config_path` if the input
65 path is not absolute. This method is exported to be used as a service.
67 Parameters
68 ----------
69 json : str
70 Path to the input config file or a JSON string.
71 schema_type : ConfigSchema | None
72 The schema type to validate the config against.
74 Returns
75 -------
76 config : Union[dict, list[dict]]
77 Free-format dictionary that contains the configuration.
78 """
79 ...
81 def build_environment( # pylint: disable=too-many-arguments
82 self,
83 config: dict,
84 tunables: TunableGroups,
85 global_config: dict | None = None,
86 parent_args: dict[str, TunableValue] | None = None,
87 service: Service | None = None,
88 ) -> Environment:
89 # pylint: disable=too-many-arguments,too-many-positional-arguments
90 """
91 Factory method for a new environment with a given config.
93 Parameters
94 ----------
95 config : dict
96 A dictionary with three mandatory fields:
97 "name": Human-readable string describing the environment;
98 "class": FQN of a Python class to instantiate;
99 "config": Free-format dictionary to pass to the constructor.
100 tunables : TunableGroups
101 A (possibly empty) collection of groups of tunable parameters for
102 all environments.
103 global_config : dict | None
104 Global parameters to add to the environment config.
105 parent_args : dict[str, TunableValue] | None
106 An optional reference of the parent CompositeEnv's const_args used to
107 expand dynamic config parameters from.
108 service: Service | None
109 An optional service object (e.g., providing methods to
110 deploy or reboot a VM, etc.).
112 Returns
113 -------
114 env : Environment
115 An instance of the `Environment` class initialized with `config`.
116 """
117 ...
119 def load_environment(
120 self,
121 json: str,
122 tunables: TunableGroups,
123 global_config: dict[str, Any] | None = None,
124 parent_args: dict[str, TunableValue] | None = None,
125 service: Service | None = None,
126 ) -> Environment:
127 # pylint: disable=too-many-arguments,too-many-positional-arguments
128 """
129 Load and build new :py:class:`.Environment` from the config file or JSON string.
131 Parameters
132 ----------
133 json : str
134 The environment JSON configuration file or JSON string.
135 tunables : TunableGroups
136 A (possibly empty) collection of tunables to add to the environment.
137 global_config : dict
138 Global parameters to add to the environment config.
139 parent_args : dict[str, TunableValue]
140 An optional reference of the parent CompositeEnv's const_args used to
141 expand dynamic config parameters from.
142 service : Service
143 An optional reference of the parent service to mix in.
145 Returns
146 -------
147 env : Environment
148 A new benchmarking environment.
149 """
150 ...
152 def load_environment_list(
153 self,
154 json: str,
155 tunables: TunableGroups,
156 global_config: dict | None = None,
157 parent_args: dict[str, TunableValue] | None = None,
158 service: Service | None = None,
159 ) -> list[Environment]:
160 # pylint: disable=too-many-arguments,too-many-positional-arguments
161 """
162 Load and build a list of environments from the config file.
164 Parameters
165 ----------
166 json : str
167 The environment JSON configuration file or a JSON string.
168 Can contain either one environment or a list of environments.
169 tunables : TunableGroups
170 A (possibly empty) collection of tunables to add to the environment.
171 global_config : dict | None
172 Global parameters to add to the environment config.
173 parent_args : dict[str, TunableValue] | None
174 An optional reference of the parent CompositeEnv's const_args used to
175 expand dynamic config parameters from.
176 service : Service | None
177 An optional reference of the parent service to mix in.
179 Returns
180 -------
181 env : list[Environment]
182 A list of new benchmarking environments.
183 """
184 ...
186 def load_services(
187 self,
188 jsons: Iterable[str],
189 global_config: dict[str, Any] | None = None,
190 parent: Service | None = None,
191 ) -> Service:
192 """
193 Read the configuration files and bundle all service methods from those configs
194 into a single Service object.
196 Parameters
197 ----------
198 jsons : list of str
199 A list of service JSON configuration files or JSON strings.
200 global_config : dict
201 Global parameters to add to the service config.
202 parent : Service
203 An optional reference of the parent service to mix in.
205 Returns
206 -------
207 service : Service
208 A collection of service methods.
209 """
210 ...