Coverage for sparkle/CLI/help/argparse_custom.py: 100%

1"""Custom helper class and functions to process CLI arguments with argparse.""" 

2 

3from __future__ import annotations 

4from pathlib import Path 

5from typing import Any 

6 

7 

8class ArgumentContainer: 

9 """Helper class for more convenient argument packaging and access.""" 

10 

11 def __init__( 

12 self: ArgumentContainer, names: list[str], kwargs: dict[str, Any] 

13 ) -> None: 

14 """Create an ArgumentContainer. 

15 

16 Args: 

17 names: List of names for the contained argument. For positional arguments 

18 this will typically contain two, the first one starting with '-' and the 

19 second one starting with '--'. 

20 kwargs: Keyword arguments needed by the method parser.add_argument which adds 

21 the contained argument to a parser. 

22 """ 

23 self.names = names 

24 self.kwargs = kwargs 

25 

26 

27AllJobsArgument = ArgumentContainer( 

28 names=["--all"], 

29 kwargs={"action": "store_true", "help": "use all known job ID(s) for the command"}, 

30) 

31 

32AllSolverConfigurationArgument = ArgumentContainer( 

33 names=["--all-configurations"], 

34 kwargs={ 

35 "action": "store_true", 

36 "help": "use all known configurations for the command", 

37 }, 

38) 

39 

40AllConfigurationArgument = ArgumentContainer( 

41 names=["--all-configurations"], 

42 kwargs={"action": "store_true", "help": "use all known Solver configurations"}, 

43) 

44 

45BestConfigurationArgument = ArgumentContainer( 

46 names=["--best-configuration"], 

47 kwargs={ 

48 "required": False, 

49 "nargs": "?", 

50 "type": Path, 

51 "const": True, 

52 "default": False, 

53 "help": "Paths to instance(s) or instanceset(s) over " 

54 "which to determine the best configuration. If " 

55 "empty, all known instances are used.", 

56 }, 

57) 

58 

59BestSolverConfigurationArgument = ArgumentContainer( 

60 names=["--best-configuration"], 

61 kwargs={ 

62 "action": "store_true", 

63 "help": "use the best configurations for the command", 

64 }, 

65) 

66 

67CancelJobsArgument = ArgumentContainer( 

68 names=["--cancel"], 

69 kwargs={"action": "store_true", "help": "cancel the job(s) with the given ID(s)"}, 

70) 

71 

72CheckTypeArgument = ArgumentContainer( 

73 names=["type"], 

74 kwargs={ 

75 "choices": [ 

76 "extractor", 

77 "feature-extractor", 

78 "solver", 

79 "instance-set", 

80 "ExtractorFeature-Extractor", 

81 "Instance-Set", 

82 "Solver", 

83 "FeatureExtractor", 

84 "InstanceSet", 

85 ], 

86 "help": "type of the object to check", 

87 }, 

88) 

89 

90CheckPathArgument = ArgumentContainer( 

91 names=["path"], kwargs={"type": Path, "help": "path to the object to check"} 

92) 

93 

94CleanupArgumentAll = ArgumentContainer( 

95 names=["--all"], kwargs={"action": "store_true", "help": "clean all output files"} 

96) 

97 

98CleanupArgumentRemove = ArgumentContainer( 

99 names=["--remove"], 

100 kwargs={ 

101 "action": "store_true", 

102 "help": "remove all files in the platform, including " 

103 "user data such as InstanceSets and Solvers", 

104 }, 

105) 

106 

107CleanUpPerformanceDataArgument = ArgumentContainer( 

108 names=["--performance-data"], 

109 kwargs={"action": "store_true", "help": "clean performance data from empty lines"}, 

110) 

111 

112ConfigurationArgument = ArgumentContainer( 

113 names=["--configuration"], 

114 kwargs={ 

115 "required": False, 

116 "type": str, 

117 "nargs": "+", 

118 "help": "The indices of which configurations to use", 

119 }, 

120) 

121 

122DefaultSolverConfigurationArgument = ArgumentContainer( 

123 names=["--default-configuration"], 

124 kwargs={ 

125 "action": "store_true", 

126 "help": "use the default configurations for the command", 

127 }, 

128) 

129 

130DeterministicArgument = ArgumentContainer( 

131 names=["--deterministic"], 

132 kwargs={ 

133 "action": "store_true", 

134 "help": "Flag indicating the solver is deterministic", 

135 }, 

136) 

137 

138DownloadExamplesArgument = ArgumentContainer( 

139 names=["--download-examples"], 

140 kwargs={ 

141 "action": "store_true", 

142 "default": False, 

143 "required": False, 

144 "help": "Download the Examples into the directory.", 

145 }, 

146) 

147 

148ExtractorPathArgument = ArgumentContainer( 

149 names=["extractor_path"], 

150 kwargs={ 

151 "metavar": "extractor-path", 

152 "type": str, 

153 "help": "path or nickname of the feature extractor", 

154 }, 

155) 

156 

157GenerateJSONArgument = ArgumentContainer( 

158 names=["--only-json"], 

159 kwargs={ 

160 "required": False, 

161 "default": False, 

162 "type": bool, 

163 "help": "if set to True, only generate machine readable output", 

164 }, 

165) 

166 

167InstancePathOptional = ArgumentContainer( 

168 names=["instance_path"], 

169 kwargs={ 

170 "type": Path, 

171 "nargs": "?", 

172 "help": "Path to an instance to use for the command", 

173 }, 

174) 

175 

176InstanceSetPathsArgument = ArgumentContainer( 

177 names=[ 

178 "--instance-path", 

179 "--instance-set-path", 

180 "--instance", 

181 "--instance-set", 

182 "--instances", 

183 "--instance-sets", 

184 "--instance-paths", 

185 "--instance-set-paths", 

186 ], 

187 kwargs={ 

188 "required": False, 

189 "nargs": "+", 

190 "type": Path, 

191 "help": "Path to an instance (set)", 

192 }, 

193) 

194 

195InstanceSetRequiredArgument = ArgumentContainer( 

196 names=["--instance", "--instance-set"], 

197 kwargs={"required": True, "type": Path, "help": "path to instance (set)"}, 

198) 

199 

200InstanceSetTestArgument = ArgumentContainer( 

201 names=["--instance-set-test"], 

202 kwargs={"required": False, "type": Path, "help": "path to test instance set"}, 

203) 

204 

205InstanceSetTrainArgument = ArgumentContainer( 

206 names=["--instance-set-train"], 

207 kwargs={"required": True, "type": Path, "help": "path to training instance set"}, 

208) 

209 

210InstanceSetTestAblationArgument = ArgumentContainer( 

211 names=["--instance-set-test"], 

212 kwargs={"required": False, "type": str, "help": "path to test instance set"}, 

213) 

214 

215InstanceSetTrainOptionalArgument = ArgumentContainer( 

216 names=["--instance-set-train"], 

217 kwargs={"required": False, "type": Path, "help": "path to training instance set"}, 

218) 

219 

220InstanceSetsReportArgument = ArgumentContainer( 

221 names=["--instance-sets", "--instance-set"], 

222 kwargs={ 

223 "required": False, 

224 "nargs": "+", 

225 "type": str, 

226 "help": "Instance Set(s) to use for the report. If not " 

227 "specified, all Instance Sets are used.", 

228 }, 

229) 

230 

231InstancesPathArgument = ArgumentContainer( 

232 names=["instances_path"], 

233 kwargs={ 

234 "metavar": "instances-path", 

235 "type": str, 

236 "help": "path to the instance set", 

237 }, 

238) 

239 

240InstancesPathRemoveArgument = ArgumentContainer( 

241 names=["instances_path"], 

242 kwargs={ 

243 "metavar": "instances-path", 

244 "type": str, 

245 "help": "path to or nickname of the instance set", 

246 }, 

247) 

248 

249JobIDsArgument = ArgumentContainer( 

250 names=["--job-ids"], 

251 kwargs={ 

252 "required": False, 

253 "nargs": "+", 

254 "type": str, 

255 "default": None, 

256 "help": "job ID(s) to use for the command", 

257 }, 

258) 

259 

260NicknameFeatureExtractorArgument = ArgumentContainer( 

261 names=["--nickname"], 

262 kwargs={"type": str, "help": "set a nickname for the feature extractor"}, 

263) 

264 

265NicknameInstanceSetArgument = ArgumentContainer( 

266 names=["--nickname"], 

267 kwargs={"type": str, "help": "set a nickname for the instance set"}, 

268) 

269 

270NicknamePortfolioArgument = ArgumentContainer( 

271 names=["--portfolio-name"], 

272 kwargs={ 

273 "type": Path, 

274 "help": "Specify a name of the portfolio. " 

275 "If none is given, one will be generated.", 

276 }, 

277) 

278 

279NicknameSolverArgument = ArgumentContainer( 

280 names=["--nickname"], kwargs={"type": str, "help": "set a nickname for the solver"} 

281) 

282 

283NoCopyArgument = ArgumentContainer( 

284 names=["--no-copy"], 

285 kwargs={ 

286 "action": "store_true", 

287 "required": False, 

288 "help": "do not copy the source directory to " 

289 "the platform directory, but create a" 

290 " symbolic link instead", 

291 }, 

292) 

293 

294NoSavePlatformArgument = ArgumentContainer( 

295 names=["--no-save"], 

296 kwargs={ 

297 "action": "store_false", 

298 "default": True, 

299 "required": False, 

300 "help": "do not save the platform upon re-initialisation.", 

301 }, 

302) 

303 

304RecomputeFeaturesArgument = ArgumentContainer( 

305 names=["--recompute"], 

306 kwargs={ 

307 "action": "store_true", 

308 "help": "Re-run feature extractor for instances with " 

309 "previously computed features", 

310 }, 

311) 

312 

313RecomputePortfolioSelectorArgument = ArgumentContainer( 

314 names=["--recompute-portfolio-selector"], 

315 kwargs={ 

316 "action": "store_true", 

317 "help": "force the construction of a new portfolio " 

318 "selector even when it already exists for the current " 

319 "feature and performance data.", 

320 }, 

321) 

322 

323RecomputeRunSolversArgument = ArgumentContainer( 

324 names=["--recompute"], 

325 kwargs={ 

326 "action": "store_true", 

327 "help": "recompute the performance of all solvers on all instances", 

328 }, 

329) 

330 

331PerformanceDataJobsArgument = ArgumentContainer( 

332 names=["--performance-data-jobs"], 

333 kwargs={ 

334 "action": "store_true", 

335 "help": "compute the remaining jobs in the Performance DataFrame", 

336 }, 

337) 

338 

339RebuildRunsolverArgument = ArgumentContainer( 

340 names=["--rebuild-runsolver"], 

341 kwargs={ 

342 "action": "store_true", 

343 "required": False, 

344 "default": False, 

345 "help": "Clean the RunSolver executable and rebuild it.", 

346 }, 

347) 

348 

349 

350SeedArgument = ArgumentContainer( 

351 names=["--seed"], kwargs={"type": int, "help": "seed to use for the command"} 

352) 

353 

354SelectionScenarioArgument = ArgumentContainer( 

355 names=["--selection-scenario"], 

356 kwargs={"required": True, "type": Path, "help": "the selection scenario to use"}, 

357) 

358 

359SelectorAblationArgument = ArgumentContainer( 

360 names=["--solver-ablation"], 

361 kwargs={ 

362 "required": False, 

363 "action": "store_true", 

364 "help": "construct a selector for each solver ablation combination", 

365 }, 

366) 

367 

368SettingsFileArgument = ArgumentContainer( 

369 names=["--settings-file"], 

370 kwargs={ 

371 "type": Path, 

372 "help": "Specify the settings file to use in case you want" 

373 " supplement or override the default file.", 

374 }, 

375) 

376 

377SkipChecksArgument = ArgumentContainer( 

378 names=["--skip-checks"], 

379 kwargs={ 

380 "dest": "run_checks", 

381 "default": True, 

382 "action": "store_false", 

383 "help": "Checks the solver's functionality by testing it on an instance " 

384 "and the pcs file, when applicable.", 

385 }, 

386) 

387 

388SnapshotArgument = ArgumentContainer( 

389 names=["snapshot_file_path"], 

390 kwargs={ 

391 "metavar": "snapshot-file-path", 

392 "type": str, 

393 "help": "path to the snapshot file", 

394 }, 

395) 

396 

397SnapshotNameArgument = ArgumentContainer( 

398 names=["--name"], 

399 kwargs={"required": False, "type": str, "help": "name of the snapshot"}, 

400) 

401 

402SolverArgument = ArgumentContainer( 

403 names=["--solver"], 

404 kwargs={"required": True, "type": Path, "help": "path to solver"}, 

405) 

406 

407SolversArgument = ArgumentContainer( 

408 names=["--solvers", "--solver-paths", "--solver", "--solver-path"], 

409 kwargs={ 

410 "required": False, 

411 "nargs": "+", 

412 "type": str, 

413 "help": "Specify the list of solvers to be " 

414 "used. If not specifed, all solvers " 

415 "known in Sparkle will be used.", 

416 }, 

417) 

418SolverRemoveArgument = ArgumentContainer( 

419 names=["solver"], 

420 kwargs={ 

421 "metavar": "solver", 

422 "type": str, 

423 "help": "name, path to or nickname of the solver", 

424 }, 

425) 

426 

427SolverPathArgument = ArgumentContainer( 

428 names=["solver_path"], 

429 kwargs={"metavar": "solver-path", "type": str, "help": "path to the solver"}, 

430) 

431 

432SolversReportArgument = ArgumentContainer( 

433 names=["--solvers", "--solver"], 

434 kwargs={ 

435 "nargs": "+", 

436 "type": str, 

437 "default": None, 

438 "help": "Solver(s) to use for the report. If not specified, all solvers are " 

439 "included.", 

440 }, 

441) 

442 

443TestSetRunAllConfigurationArgument = ArgumentContainer( 

444 names=["--test-set-run-all-configurations"], 

445 kwargs={ 

446 "required": False, 

447 "action": "store_true", 

448 "help": "run all found configurations on the test set", 

449 }, 

450) 

451 

452UseFeaturesArgument = ArgumentContainer( 

453 names=["--use-features"], 

454 kwargs={ 

455 "required": False, 

456 "action": "store_true", 

457 "help": "use the training set's features for configuration", 

458 }, 

459) 

460 

461SolutionVerifierArgument = ArgumentContainer( 

462 names=["--solution-verifier"], 

463 kwargs={ 

464 "type": str, 

465 "default": None, 

466 "help": "the class name of the solution verifier to use " 

467 "for the Solver. If it is a Path, will resolve as " 

468 "a SolutionFileVerifier class with the specified " 

469 "Path instead.", 

470 }, 

471) 

472 

473ObjectiveArgument = ArgumentContainer( 

474 names=["--objective"], kwargs={"type": str, "help": "the objective to use."} 

475)