Coverage for python/lsst/pex/config/configChoiceField.py: 18%

1# This file is part of pex_config.

3# Developed for the LSST Data Management System.

4# This product includes software developed by the LSST Project

5# (http://www.lsst.org).

6# See the COPYRIGHT file at the top-level directory of this distribution

7# for details of code ownership.

9# This software is dual licensed under the GNU General Public License and also

10# under a 3-clause BSD license. Recipients may choose which of these licenses

11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt,

12# respectively. If you choose the GPL option then the following text applies

13# (but note that there is still no warranty even if you opt for BSD instead):

14#

15# This program is free software: you can redistribute it and/or modify

16# it under the terms of the GNU General Public License as published by

17# the Free Software Foundation, either version 3 of the License, or

18# (at your option) any later version.

19#

20# This program is distributed in the hope that it will be useful,

21# but WITHOUT ANY WARRANTY; without even the implied warranty of

22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

23# GNU General Public License for more details.

24#

25# You should have received a copy of the GNU General Public License

26# along with this program. If not, see <http://www.gnu.org/licenses/>.

27from __future__ import annotations

29__all__ = ["ConfigChoiceField"]

31import collections.abc

32import copy

33import weakref

34from typing import Any, ForwardRef, overload

36from .callStack import getCallStack, getStackFrame

37from .comparison import compareConfigs, compareScalars, getComparisonName

38from .config import Config, Field, FieldValidationError, UnexpectedProxyUsageError, _joinNamePath, _typeStr

41class SelectionSet(collections.abc.MutableSet):

42 """A mutable set class that tracks the selection of multi-select

43 `~lsst.pex.config.ConfigChoiceField` objects.

45 Parameters

46 ----------

47 dict_ : `ConfigInstanceDict`

48 The dictionary of instantiated configs.

49 value : `~typing.Any`

50 The selected key.

51 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`, optional

52 The call stack when the selection was made.

53 label : `str`, optional

54 Label for history tracking.

55 setHistory : `bool`, optional

56 Add this even to the history, if `True`.

58 Notes

59 -----

60 This class allows a user of a multi-select

61 `~lsst.pex.config.ConfigChoiceField` to add or discard items from the set

62 of active configs. Each change to the selection is tracked in the field's

63 history.

64 """

66 def __init__(self, dict_, value, at=None, label="assignment", setHistory=True):

67 if at is None:

68 at = getCallStack()

69 self._dict = dict_

70 self._field = self._dict._field

71 self._config_ = weakref.ref(self._dict._config)

72 self.__history = self._config._history.setdefault(self._field.name, [])

73 if value is not None:

74 try:

75 for v in value:

76 if v not in self._dict:

77 # invoke __getitem__ to ensure it's present

78 self._dict.__getitem__(v, at=at)

79 except TypeError as e:

80 msg = f"Value {value} is of incorrect type {_typeStr(value)}. Sequence type expected"

81 raise FieldValidationError(self._field, self._config, msg) from e

82 self._set = set(value)

83 else:

84 self._set = set()

86 if setHistory:

87 self.__history.append((f"Set selection to {self}", at, label))

89 @property

90 def _config(self) -> Config:

91 # Config Fields should never outlive their config class instance

92 # assert that as such here

93 assert self._config_() is not None

94 return self._config_()

96 def add(self, value, at=None):

97 """Add a value to the selected set.

99 Parameters

100 ----------

101 value : `~typing.Any`

102 The selected key.

103 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\

104 optional

105 Stack frames for history recording.

106 """

107 if self._config._frozen:

108 raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")

109

110 if at is None:

111 at = getCallStack()

112

113 if value not in self._dict:

114 # invoke __getitem__ to make sure it's present

115 self._dict.__getitem__(value, at=at)

116

117 self.__history.append((f"added {value} to selection", at, "selection"))

118 self._set.add(value)

119

120 def discard(self, value, at=None):

121 """Discard a value from the selected set.

122

123 Parameters

124 ----------

125 value : `~typing.Any`

126 The selected key.

127 at : `list` of `~lsst.pex.config.callStack.StackFrame` or `None`,\

128 optional

129 Stack frames for history recording.

130 """

131 if self._config._frozen:

132 raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")

133

134 if value not in self._dict:

135 return

136

137 if at is None:

138 at = getCallStack()

139

140 self.__history.append((f"removed {value} from selection", at, "selection"))

141 self._set.discard(value)

142

143 def __len__(self):

144 return len(self._set)

145

146 def __iter__(self):

147 return iter(self._set)

148

149 def __contains__(self, value):

150 return value in self._set

151

152 def __repr__(self):

153 return repr(list(self._set))

154

155 def __str__(self):

156 return str(list(self._set))

157

158 def __reduce__(self):

159 raise UnexpectedProxyUsageError(

160 f"Proxy container for config field {self._field.name} cannot "

161 "be pickled; it should be converted to a built-in container before "

162 "being assigned to other objects or variables."

163 )

164

165

166class ConfigInstanceDict(collections.abc.Mapping[str, Config]):

167 """Dictionary of instantiated configs, used to populate a

168 `~lsst.pex.config.ConfigChoiceField`.

169

170 Parameters

171 ----------

172 config : `lsst.pex.config.Config`

173 A configuration instance.

174 field : `lsst.pex.config.Field`-type

175 A configuration field. Note that the `lsst.pex.config.Field.fieldmap`

176 attribute must provide key-based access to configuration classes,

177 (that is, ``typemap[name]``).

178 """

179

180 def __init__(self, config, field):

181 collections.abc.Mapping.__init__(self)

182 self._dict = {}

183 self._selection = None

184 self._config = config

185 self._field = field

186 self._history = config._history.setdefault(field.name, [])

187 self.__doc__ = field.doc

188 self._typemap = None

189

190 @property

191 def types(self):

192 return self._typemap if self._typemap is not None else self._field.typemap

193

194 def __contains__(self, k):

195 return k in self.types

196

197 def __len__(self):

198 return len(self.types)

199

200 def __iter__(self):

201 return iter(self.types)

202

203 def _setSelection(self, value, at=None, label="assignment"):

204 if self._config._frozen:

205 raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")

206

207 if at is None:

208 at = getCallStack(1)

209

210 if value is None:

211 self._selection = None

212 elif self._field.multi:

213 self._selection = SelectionSet(self, value, setHistory=False)

214 else:

215 if value not in self._dict:

216 self.__getitem__(value, at=at) # just invoke __getitem__ to make sure it's present

217 self._selection = value

218 self._history.append((value, at, label))

219

220 def _getNames(self):

221 if not self._field.multi:

222 raise FieldValidationError(

223 self._field, self._config, "Single-selection field has no attribute 'names'"

224 )

225 return self._selection

226

227 def _setNames(self, value):

228 if not self._field.multi:

229 raise FieldValidationError(

230 self._field, self._config, "Single-selection field has no attribute 'names'"

231 )

232 self._setSelection(value)

233

234 def _delNames(self):

235 if not self._field.multi:

236 raise FieldValidationError(

237 self._field, self._config, "Single-selection field has no attribute 'names'"

238 )

239 self._selection = None

240

241 def _getName(self):

242 if self._field.multi:

243 raise FieldValidationError(

244 self._field, self._config, "Multi-selection field has no attribute 'name'"

245 )

246 return self._selection

247

248 def _setName(self, value):

249 if self._field.multi:

250 raise FieldValidationError(

251 self._field, self._config, "Multi-selection field has no attribute 'name'"

252 )

253 self._setSelection(value)

254

255 def _delName(self):

256 if self._field.multi:

257 raise FieldValidationError(

258 self._field, self._config, "Multi-selection field has no attribute 'name'"

259 )

260 self._selection = None

261

262 names = property(_getNames, _setNames, _delNames)

263 """List of names of active items in a multi-selection

264 ``ConfigInstanceDict``. Disabled in a single-selection ``_Registry``; use

265 the `name` attribute instead.

266 """

267

268 name = property(_getName, _setName, _delName)

269 """Name of the active item in a single-selection ``ConfigInstanceDict``.

270 Disabled in a multi-selection ``_Registry``; use the ``names`` attribute

271 instead.

272 """

273

274 def _getActive(self):

275 if self._selection is None:

276 return None

277

278 if self._field.multi:

279 return [self[c] for c in self._selection]

280 else:

281 return self[self._selection]

282

283 active = property(_getActive)

284 """The selected items.

285

286 For multi-selection, this is equivalent to: ``[self[name] for name in

287 self.names]``. For single-selection, this is equivalent to: ``self[name]``.

288 """

289

290 def __getitem__(self, k, at=None, label="default"):

291 try:

292 value = self._dict[k]

293 except KeyError:

294 try:

295 dtype = self.types[k]

296 except Exception as e:

297 raise FieldValidationError(

298 self._field, self._config, f"Unknown key {k!r} in Registry/ConfigChoiceField"

299 ) from e

300 name = _joinNamePath(self._config._name, self._field.name, k)

301 if at is None:

302 at = getCallStack()

303 at.insert(0, dtype._source)

304 value = self._dict.setdefault(k, dtype(__name=name, __at=at, __label=label))

305 return value

306

307 def __setitem__(self, k, value, at=None, label="assignment"):

308 if self._config._frozen:

309 raise FieldValidationError(self._field, self._config, "Cannot modify a frozen Config")

310

311 try:

312 dtype = self.types[k]

313 except Exception as e:

314 raise FieldValidationError(self._field, self._config, f"Unknown key {k!r}") from e

315

316 if value != dtype and type(value) is not dtype:

317 msg = (

318 f"Value {value} at key {k} is of incorrect type {_typeStr(value)}. "

319 f"Expected type {_typeStr(dtype)}"

320 )

321 raise FieldValidationError(self._field, self._config, msg)

322

323 if at is None:

324 at = getCallStack()

325 name = _joinNamePath(self._config._name, self._field.name, k)

326 oldValue = self._dict.get(k, None)

327 if oldValue is None:

328 if value == dtype:

329 self._dict[k] = value(__name=name, __at=at, __label=label)

330 else:

331 self._dict[k] = dtype(__name=name, __at=at, __label=label, **value._storage)

332 else:

333 if value == dtype:

334 value = value()

335 oldValue.update(__at=at, __label=label, **value._storage)

336

337 def _rename(self, fullname):

338 for k, v in self._dict.items():

339 v._rename(_joinNamePath(name=fullname, index=k))

340

341 def __setattr__(self, attr, value, at=None, label="assignment"):

342 if hasattr(getattr(self.__class__, attr, None), "__set__"):

343 # This allows properties to work.

344 object.__setattr__(self, attr, value)

345 elif attr in self.__dict__ or attr in [

346 "_history",

347 "_field",

348 "_config",

349 "_dict",

350 "_selection",

351 "__doc__",

352 "_typemap",

353 ]:

354 # This allows specific private attributes to work.

355 object.__setattr__(self, attr, value)

356 else:

357 # We throw everything else.

358 msg = f"{_typeStr(self._field)} has no attribute {attr}"

359 raise FieldValidationError(self._field, self._config, msg)

360

361 def freeze(self):

362 """Freeze the config.

363

364 Invoking this freeze method will create a local copy of the field

365 attribute's typemap. This decouples this instance dict from the

366 underlying objects type map ensuring that and subsequent changes to the

367 typemap will not be reflected in this instance (i.e imports adding

368 additional registry entries).

369 """

370 if self._typemap is None:

371 self._typemap = copy.deepcopy(self.types)

372

373 def __reduce__(self):

374 raise UnexpectedProxyUsageError(

375 f"Proxy container for config field {self._field.name} cannot "

376 "be pickled; it should be converted to a built-in container before "

377 "being assigned to other objects or variables."

378 )

379

380

381class ConfigChoiceField(Field[ConfigInstanceDict]):

382 """A configuration field (`~lsst.pex.config.Field` subclass) that allows a

383 user to choose from a set of `~lsst.pex.config.Config` types.

384

385 Parameters

386 ----------

387 doc : `str`

388 Documentation string for the field.

389 typemap : `dict`-like

390 A mapping between keys and `~lsst.pex.config.Config`-types as values.

391 See *Examples* for details.

392 default : `str`, optional

393 The default configuration name.

394 optional : `bool`, optional

395 When `False`, `lsst.pex.config.Config.validate` will fail if the

396 field's value is `None`.

397 multi : `bool`, optional

398 If `True`, the field allows multiple selections. In this case, set the

399 selections by assigning a sequence to the ``names`` attribute of the

400 field.

401

402 If `False`, the field allows only a single selection. In this case,

403 set the active config by assigning the config's key from the

404 ``typemap`` to the field's ``name`` attribute (see *Examples*).

405 deprecated : None or `str`, optional

406 A description of why this Field is deprecated, including removal date.

407 If not None, the string is appended to the docstring for this Field.

408

409 See Also

410 --------

411 ChoiceField

412 ConfigDictField

413 ConfigField

414 ConfigurableField

415 DictField

416 Field

417 ListField

418 RangeField

419 RegistryField

420

421 Notes

422 -----

423 ``ConfigChoiceField`` instances can allow either single selections or

424 multiple selections, depending on the ``multi`` parameter. For

425 single-selection fields, set the selection with the ``name`` attribute.

426 For multi-selection fields, set the selection though the ``names``

427 attribute.

428

429 This field is validated only against the active selection. If the

430 ``active`` attribute is `None` and the field is not optional, validation

431 will fail.

432

433 When saving a configuration with a ``ConfigChoiceField``, the entire set is

434 saved, as well as the active selection.

435

436 Examples

437 --------

438 While the ``typemap`` is shared by all instances of the field, each

439 instance of the field has its own instance of a particular sub-config type.

440

441 For example, ``AaaConfig`` is a config object

442

443 >>> from lsst.pex.config import Config, ConfigChoiceField, Field

444 >>> class AaaConfig(Config):

445 ... somefield = Field("doc", int)

446

447 The ``MyConfig`` config has a ``ConfigChoiceField`` field called ``choice``

448 that maps the ``AaaConfig`` type to the ``"AAA"`` key:

449

450 >>> TYPEMAP = {"AAA", AaaConfig}

451 >>> class MyConfig(Config):

452 ... choice = ConfigChoiceField("doc for choice", TYPEMAP)

453

454 Creating an instance of ``MyConfig``:

455

456 >>> instance = MyConfig()

457

458 Setting value of the field ``somefield`` on the "AAA" key of the ``choice``

459 field:

460

461 >>> instance.choice["AAA"].somefield = 5

462

463 **Selecting the active configuration**

464

465 Make the ``"AAA"`` key the active configuration value for the ``choice``

466 field:

467

468 >>> instance.choice = "AAA"

469

470 Alternatively, the last line can be written:

471

472 >>> instance.choice.name = "AAA"

473

474 (If the config instance allows multiple selections, you'd assign a sequence

475 to the ``names`` attribute instead.)

476

477 ``ConfigChoiceField`` instances also allow multiple values of the same

478 type:

479

480 >>> TYPEMAP["CCC"] = AaaConfig

481 >>> TYPEMAP["BBB"] = AaaConfig

482 """

483

484 instanceDictClass = ConfigInstanceDict

485

486 def __init__(self, doc, typemap, default=None, optional=False, multi=False, deprecated=None):

487 source = getStackFrame()

488 self._setup(

489 doc=doc,

490 dtype=self.instanceDictClass,

491 default=default,

492 check=None,

493 optional=optional,

494 source=source,

495 deprecated=deprecated,

496 )

497 self.typemap = typemap

498 self.multi = multi

499

500 def __class_getitem__(cls, params: tuple[type, ...] | type | ForwardRef):

501 raise ValueError("ConfigChoiceField does not support typing argument")

502

503 def _getOrMake(self, instance, label="default"):

504 instanceDict = instance._storage.get(self.name)

505 if instanceDict is None:

506 at = getCallStack(1)

507 instanceDict = self.dtype(instance, self)

508 instanceDict.__doc__ = self.doc

509 instance._storage[self.name] = instanceDict

510 history = instance._history.setdefault(self.name, [])

511 history.append(("Initialized from defaults", at, label))

512

513 return instanceDict

514

515 @overload

516 def __get__(

517 self, instance: None, owner: Any = None, at: Any = None, label: str = "default"

518 ) -> ConfigChoiceField: ...

519

520 @overload

521 def __get__(

522 self, instance: Config, owner: Any = None, at: Any = None, label: str = "default"

523 ) -> ConfigInstanceDict: ...

524

525 def __get__(self, instance, owner=None, at=None, label="default"):

526 if instance is None or not isinstance(instance, Config):

527 return self

528 else:

529 return self._getOrMake(instance)

530

531 def __set__(

532 self, instance: Config, value: ConfigInstanceDict | None, at: Any = None, label: str = "assignment"

533 ) -> None:

534 if instance._frozen:

535 raise FieldValidationError(self, instance, "Cannot modify a frozen Config")

536 if at is None:

537 at = getCallStack()

538 instanceDict = self._getOrMake(instance)

539 if isinstance(value, self.instanceDictClass):

540 for k, v in value.items():

541 instanceDict.__setitem__(k, v, at=at, label=label)

542 instanceDict._setSelection(value._selection, at=at, label=label)

543

544 else:

545 instanceDict._setSelection(value, at=at, label=label)

546

547 def rename(self, instance):

548 instanceDict = self.__get__(instance)

549 fullname = _joinNamePath(instance._name, self.name)

550 instanceDict._rename(fullname)

551

552 def validate(self, instance):

553 instanceDict = self.__get__(instance)

554 if instanceDict.active is None and not self.optional:

555 msg = "Required field cannot be None"

556 raise FieldValidationError(self, instance, msg)

557 elif instanceDict.active is not None:

558 if self.multi:

559 for a in instanceDict.active:

560 a.validate()

561 else:

562 instanceDict.active.validate()

563

564 def toDict(self, instance):

565 instanceDict = self.__get__(instance)

566

567 dict_ = {}

568 if self.multi:

569 dict_["names"] = instanceDict.names

570 else:

571 dict_["name"] = instanceDict.name

572

573 values = {}

574 for k, v in instanceDict.items():

575 values[k] = v.toDict()

576 dict_["values"] = values

577

578 return dict_

579

580 def freeze(self, instance):

581 instanceDict = self.__get__(instance)

582 instanceDict.freeze()

583 for v in instanceDict.values():

584 v.freeze()

585

586 def _collectImports(self, instance, imports):

587 instanceDict = self.__get__(instance)

588 for config in instanceDict.values():

589 config._collectImports()

590 imports |= config._imports

591

592 def save(self, outfile, instance):

593 instanceDict = self.__get__(instance)

594 fullname = _joinNamePath(instance._name, self.name)

595 for v in instanceDict.values():

596 v._save(outfile)

597 if self.multi:

598 outfile.write(f"{fullname}.names={sorted(instanceDict.names)!r}\n")

599 else:

600 outfile.write(f"{fullname}.name={instanceDict.name!r}\n")

601

602 def __deepcopy__(self, memo):

603 """Customize deep-copying, because we always want a reference to the

604 original typemap.

605

606 WARNING: this must be overridden by subclasses if they change the

607 constructor signature!

608 """

609 other = type(self)(

610 doc=self.doc,

611 typemap=self.typemap,

612 default=copy.deepcopy(self.default),

613 optional=self.optional,

614 multi=self.multi,

615 )

616 other.source = self.source

617 return other

618

619 def _compare(self, instance1, instance2, shortcut, rtol, atol, output):

620 """Compare two fields for equality.

621

622 Used by `lsst.pex.ConfigChoiceField.compare`.

623

624 Parameters

625 ----------

626 instance1 : `lsst.pex.config.Config`

627 Left-hand side config instance to compare.

628 instance2 : `lsst.pex.config.Config`

629 Right-hand side config instance to compare.

630 shortcut : `bool`

631 If `True`, this function returns as soon as an inequality if found.

632 rtol : `float`

633 Relative tolerance for floating point comparisons.

634 atol : `float`

635 Absolute tolerance for floating point comparisons.

636 output : callable

637 A callable that takes a string, used (possibly repeatedly) to

638 report inequalities.

639

640 Returns

641 -------

642 isEqual : bool

643 `True` if the fields are equal, `False` otherwise.

644

645 Notes

646 -----

647 Only the selected configurations are compared, as the parameters of any

648 others do not matter.

649

650 Floating point comparisons are performed by `numpy.allclose`.

651 """

652 d1 = getattr(instance1, self.name)

653 d2 = getattr(instance2, self.name)

654 name = getComparisonName(

655 _joinNamePath(instance1._name, self.name), _joinNamePath(instance2._name, self.name)

656 )

657 if not compareScalars(f"selection for {name}", d1._selection, d2._selection, output=output):

658 return False

659 if d1._selection is None:

660 return True

661 if self.multi:

662 nested = [(k, d1[k], d2[k]) for k in d1._selection]

663 else:

664 nested = [(d1._selection, d1[d1._selection], d2[d1._selection])]

665 equal = True

666 for k, c1, c2 in nested:

667 result = compareConfigs(

668 f"{name}[{k!r}]", c1, c2, shortcut=shortcut, rtol=rtol, atol=atol, output=output

669 )

670 if not result and shortcut:

671 return False

672 equal = equal and result

673 return equal