def _param_resolve(self, param):
# Resolves to canonical parameters, including default case.
if param is None:
assert self._allow_default
assert len(self.param_list) > 0
param = self.param_list[0]
elif not isinstance(param, tuple):
if not isinstance(param, list):
# Assume scalar.
param = (param,)
else:
param = tuple(param)
return get_param_canonical(param)
def _param_resolve(self, param):
# Resolves to canonical parameters, including default case.
if param is None:
assert self._allow_default
assert len(self.param_list) > 0
param = self.param_list[0]
elif not isinstance(param, tuple):
if not isinstance(param, list):
# Assume scalar.
param = (param, )
else:
param = tuple(param)
return get_param_canonical(param)
def add_instantiation(self, param, instantiation):
"""Adds a unique instantiation.
Note:
`param` must not have already been added.
"""
# Ensure that we do not already have this tuple.
param = get_param_canonical(self._param_resolve(param))
if param in self._instantiation_map:
raise RuntimeError(
"Parameter instantiation already registered: {}".format(param))
# Register it.
self.param_list.append(param)
self._add_instantiation_internal(param, instantiation)
return param
def add_instantiation(self, param, instantiation):
"""Adds a unique instantiation.
Note:
`param` must not have already been added.
"""
# Ensure that we do not already have this tuple.
param = get_param_canonical(self._param_resolve(param))
if param in self._instantiation_map:
raise RuntimeError(
"Parameter instantiation already registered: {}".format(param))
# Register it.
self.param_list.append(param)
self._add_instantiation_internal(param, instantiation)
return param
def deprecate_instantiation(self, param, message):
"""Deprecates an instantiation for the given set of parameters.
Note:
This method can only be called once for a given instantiation.
Args:
param: Parameters for an instantiation that is already registered.
message: Message to be shown when issuing a deprecation warning.
Returns:
(instantiation, param), where ``param`` is the resolved parameters.
"""
param = get_param_canonical(self._param_resolve(param))
if param in self._deprecation_map:
raise RuntimeError(f"Deprecation already registered: "
f"{self._instantiation_name(param)}")
instantiation, param = self.get_instantiation(param)
self._deprecation_map[param] = message
return (instantiation, param)
def deprecate_instantiation(self, param, message, *, date=None):
"""Deprecates an instantiation for the given set of parameters.
Note:
This method can only be called once for a given instantiation.
Args:
param: Parameters for an instantiation that is already registered.
message: Message to be shown when issuing a deprecation warning.
date: (Optional) String of the form "YYYY-MM-DD".
If supplied, will reformat the message to add the date as is
done with DRAKE_DEPRECATED and its processing in mkdoc.py. This
must be present if ``message`` does not contain the date
itself.
Returns:
(instantiation, param), where ``param`` is the resolved parameters.
"""
param = get_param_canonical(self._param_resolve(param))
if param in self._deprecation_map:
raise RuntimeError(f"Deprecation already registered: "
f"{self._instantiation_name(param)}")
instantiation, param = self.get_instantiation(param)
self._deprecation_map[param] = _Deprecation(message=message, date=date)
return (instantiation, param)
def _check_alias(self, canonical, alias):
actual = get_param_canonical([alias])[0]
self.assertTrue(actual is canonical)
def _check_alias(self, canonical, alias):
actual = get_param_canonical([alias])[0]
self.assertTrue(actual is canonical)