PlotSetting

class PlasmaCalcs.plotting.plot_settings.PlotSetting(key, default, typestr, doc, defaults_keystring=None, validation=None, validation_message=None, *, ntab=1, tab=' ')

Bases: object

a single plot setting, with default value.

key: key for this setting. default: default value for this setting typsetr: string describing the type for this setting doc: docstring for this setting (not including the typestr) (will be hit by inspect.cleandoc) defaults_keystring: None, string of the form ‘DEFAULTS.<key>’, or tuple of (defaults_keystring, dict)

if string, self.get(provided=UNSET) will get value from DEFAULTS.

if tuple, first element must be str, and first behaves as if just a str,

but then based on result of self.get, might use dict as follows:

if val=self.get(provided=UNSET) in dict, use value from DEFAULTS implied by dict[val].

E.g. (‘DEFAULTS.PLOT.ROBUST’, {True: ‘DEFAULTS.PLOT.ROBUST_PERCENTILE’}) –>

if val=self.get(provided=UNSET)==True, use DEFAULTS.PLOT.ROBUST_PERCENTILE;

if provided not UNSET, or val!=True, just use val.

Also, in this case, stores the dict portion as defaults_keystring_dict.

validation: None, list-like, or callable.: if provided, tells how to validate any value provided to this property.

list-like –> value must be in this list.

callable –> ensure that bool(callable(value)) evaluates to True.
validation_message: None or str.: if provided, tells what to append to error message if validation fails;

base error message will always be: “invalid value for {self.key!r}: {value!r}.”

If validation_message does not start with a space, one will be prepended.
ntab: number of tabs to indent doc by, underneath typestr.: default 1, is a good number for docstrings of module-level objects.

(but, e.g. for methods defined inside a class, probably use ntab=2.)

tab: string to use for a single tab.

Methods

`__iter__`()	returns iter of tuple of (key, default, typestr, doc, defaults_keystring, validation).
`defaults_keystring_formatting`()	returns dict which will be used to .format the docstring.
`defaults_keystring_value`()	get the value from DEFAULTS.
`docs_dict`([ntab])	returns {self.key: self.docstring(ntab)}
`docstring`([ntab])	return the docstring for this setting, in format:
`get`([provided])	get the value from self.
`get_default`()	get the default value: self.default if defaults_keystring is None else value from DEFAULTS.
`validate`(value)	ensures that value is valid for this setting.
`_get_validation_message`([default])	return self.validation_message, with a space prepended if needed.
`_value_from_DEFAULTS_str`(s, *[, s_name])	get any value from DEFAULTS.

__iter__(): returns iter of tuple of (key, default, typestr, doc, defaults_keystring, validation).

Thus, can create new PlotSetting with:

PlotSetting(self.key, *iter(self))

_get_validation_message(default=None): return self.validation_message, with a space prepended if needed.

if default provided and self.validation_message is None, use default.

static _value_from_DEFAULTS_str(s, *, s_name=''): get any value from DEFAULTS. s_name used if raising an error message.

defaults_keystring_formatting(): returns dict which will be used to .format the docstring.

If self.defaults_keystring is provided:

{‘default_value’: self.defaults_keystring_value(),

‘default_key’: self.defaults_keystring,

‘default’: f’{self.defaults_keystring} (default: {self.defaults_keystring_value()})’}

Also, if self.defaults_keystring_dict is provided, include something similar for each key in dict,

adding ‘defaults_dict_{key}_value’, ‘defaults_dict_{key}_key’, and ‘defaults_dict_{key}’.

E.g. if defaults_keystring=(‘DEFAULTS.PLOT.ROBUST’, {True: ‘DEFAULTS.PLOT.ROBUST_PERCENTILE’}),

when DEFAULTS.PLOT.ROBUST = True and DEFAULTS.PLOT.ROBUST_PERCENTILE = 2.0:

{‘default_value’: True

‘default_key’: ‘DEFAULTS.PLOT.ROBUST’,

‘default’: ‘DEFAULTS.PLOT.ROBUST (default: True)’,

‘defaults_dict_True_value’: 2.0,

‘defaults_dict_True_key’: ‘DEFAULTS.PLOT.ROBUST_PERCENTILE’,

‘defaults_dict_True’: ‘DEFAULTS.PLOT.ROBUST_PERCENTILE (default: 2.0)’}

defaults_keystring_value(): get the value from DEFAULTS.

docs_dict(ntab=UNSET): returns {self.key: self.docstring(ntab)}

docstring(ntab=UNSET): return the docstring for this setting, in format:

{self.typestr} (default: {self.default})

{self.doc}

the typestr line will not be indented at all;

the docstring line(s) will be indented by self.tab * ntab.

self.doc will be hit by .format(**self.defaults_keystring_formatting()).

(If self.defaults_keystring is None, this shouldn’t change the result.)

get(provided=UNSET): get the value from self. return provided if not UNSET, else return self.get_default()

get_default(): get the default value: self.default if defaults_keystring is None else value from DEFAULTS.

validate(value): ensures that value is valid for this setting. Raise InputError if it is not.

return (if no InputError is raised) depends on self.validation:

None –> return None

iterable –> return True if valid in self.validation

callable –> return self.validation(value)