PlasmaCalcs.plotting.plot_settings.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.

__init__(key, default, typestr, doc, defaults_keystring=None, validation=None, validation_message=None, *, ntab=1, tab='    ')

Methods

__init__(key, default, typestr, doc[, ...])
defaults_keystring_formatting()
defaults_keystring_value()
docs_dict([ntab])
docstring([ntab])
get([provided])
get_default()
validate(value)

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)