PlotSettings

class PlasmaCalcs.plotting.plot_settings.PlotSettings(*, pop_from={}, **kw)

Bases: object

class for managing plot settings.

class stores default settings and docstrings;

instance stores current settings, e.g. for a particular object.

UNSET is used as default value for many settings;

this is to distinguish between “not provided” and “provided as None”,

since None is a valid value for many settings (usually, None means “use matplotlib defaults).

all settings can be provided as kwargs during __init__.

kwargs which are not recognized as valid PlotSettings.valid_keys() will be ignored.

CAUTION: adjusting plot settings after instantiation might break mutually-dependent settings.

[TODO] make mutually-dependent settings be property-like, instead, to mitigate this?^

CAUTION: do not use self.kw directly;

instead, use self.get(key), self.set(**kw), self[key], self[key]=value, or del self[key].

This ensures values are validated and that only valid keys are used.

Methods

__contains__(key)	returns whether key is in self.kw.
__delitem__(key)	delete self.kw[key]
__getitem__(key)	return self.get(key).
__setitem__(key, value)	set self.kw[key] = value, after ensuring this is valid, via self.validate.
cls_get_mpl_kwargs(mpl_funcname, **kw)	returns dict of kwargs to pass to matplotlib func with name mpl_funcname.
cls_pop_mpl_kwargs(mpl_funcname, kw, *[, ...])	pops kwargs from kw which are supposed to go to matplotlib func with name mpl_funcname.
copy()	return new PlotSettings, with copy of self.kw
default(key)	get the default for a plot setting.
dict_from_valid_keys(d, *[, pop])	return dict but only with keys that are valid for PlotSettings, i.e. in PlotSettings.valid_keys().
docs_dict([ntab])	return dict of {key: docstring} for all settings.
format_docstring(*[, ntab])	return function decorator which formats docstring of a plotter function.
get(key[, provided, default, fdefault, ...])	get a plot setting.
get_default(key)	get the default value for a plot setting.
get_mpl_func_settings(mpl_funcname)	return dict of {key: value} for all mpl kwargs for mpl_funcname, with values from self.
get_mpl_keys(mpl_funcname, *[, mode])	returns tuple of keys which are supposed to go to matplotlib func with name mpl_funcname, as kwargs.
get_mpl_kwargs(mpl_funcname, **kw)	return kwargs to use for mpl_funcname, using values from self as defaults, and kw if provided.
is_default(key)	return whether key has the default value for this setting.
pop_mpl_kwargs(mpl_funcname, kw, **other_kwargs)	return kwargs to use for mpl_funcname, using values from self as defaults, and kw if provided.
set(**kw)	set plot settings, in self.
take_from(d)	update self.kw with d, popping keys from d instead of just copying values.
update(d, *[, pop])	update self.kw with d, but only for keys in self.valid_keys().
valid_keys()	return set of all valid keys for plot settings.
validate(key, value)	raise InputError if value is invalid for key, or PlotSettingsError if key not in self.valid_keys().
_instantiate_default_settings()	convert all DEFAULT_SETTINGS to PlotSetting (or SharedPlotSetting) instances.

Attributes

DEFAULT_SETTINGS
MPL_KWARGS

__contains__(key)

returns whether key is in self.kw.

__delitem__(key)

delete self.kw[key]

__getitem__(key)

return self.get(key).

__setitem__(key, value)

set self.kw[key] = value, after ensuring this is valid, via self.validate.

Only set key if value is not self.default(key) or self.get_default(key) (compared via ‘is’).

classmethod _instantiate_default_settings()

convert all DEFAULT_SETTINGS to PlotSetting (or SharedPlotSetting) instances.

classmethod cls_get_mpl_kwargs(mpl_funcname, **kw)

returns dict of kwargs to pass to matplotlib func with name mpl_funcname.

see also: pop_mpl_kwargs.

classmethod cls_pop_mpl_kwargs(mpl_funcname, kw, *, defaults={}, **other_kwargs)

pops kwargs from kw which are supposed to go to matplotlib func with name mpl_funcname.

valid mpl_funcname options determined by cls.MPL_KWARGS.

returns dict of kwargs to pass to matplotlib func.

if other_kwargs provided, use these for values not found in kw, if not UNSET.

if defaults provided, use these for values not found in kw or other_kwargs, if not UNSET.

Note: might be fancy, e.g. ‘axes_class’ from kw for ‘plt.subplots’

would be passed as subplot_kw=dict(axes_class=…).

copy()

return new PlotSettings, with copy of self.kw

classmethod default(key)

get the default for a plot setting.

This is the default entered at the definition of the setting; it might be UNSET.

See also cls.get_default.

classmethod dict_from_valid_keys(d, *, pop=False)

return dict but only with keys that are valid for PlotSettings, i.e. in PlotSettings.valid_keys().

if pop, also pop these keys from d instead of just copying their values.

classmethod docs_dict(ntab=1)

return dict of {key: docstring} for all settings. See: format_docstring.

classmethod format_docstring(*, ntab=1, **kw_format_docstring)

return function decorator which formats docstring of a plotter function.

Provides docs for all settings, by default.

ntab tells number of tabs for docs.

Use 1 for module-level functions, 2 for class methods, 3+ if indenting deeper than that…

additional kw go to tools.format_docstring.

get(key, provided=UNSET, *, default=NO_VALUE, fdefault=NO_VALUE, last_resort_default=NO_VALUE)

get a plot setting. if provided is not UNSET, return it.

There are multiple ways to set defaults.

A pneumonic for the order of precedence when multiple defaults / values are entered, is:

“provided > self.kw > default > fdefault > self.DEFAULT_SETTINGS > last_resort_default”

More precisely, when getting key, does the following, in order:

– assert key in self.valid_keys(); raise PlotSettingsError if not.

- return provided (if not UNSET).

- return self.kw[key] (if it exists and is not UNSET)

- return default (if not NO_VALUE).

- return fdefault() (if not NO_VALUE).

- return self.get_default(key), if key in self.DEFAULT_SETTINGS.

- return last_resort_default, if it was provided (not NO_VALUE).

– give up; raise PlotSettingsError.

classmethod get_default(key)

get the default value for a plot setting.

This is setting.get_default(), where setting is cls.DEFAULT_SETTINGS[key].

Note that setting.get_default() does not necessarily equal setting.default;

in particular they will differ if the default is UNSET,

and a defaults_keystring was provided to that setting.

get_mpl_func_settings(mpl_funcname)

return dict of {key: value} for all mpl kwargs for mpl_funcname, with values from self.

Note: this is different get_mpl_kwargs, since the result will not have any nested kwargs.

classmethod get_mpl_keys(mpl_funcname, *, mode='nested')

returns tuple of keys which are supposed to go to matplotlib func with name mpl_funcname, as kwargs.

some elements might be tuples instead of strings. If so, it means that they are nested kwargs.

E.g. (‘subplot_kw’, (‘axes_class’, ‘polar’)) means that kw[‘axes_class’] and kw[‘polar’]

would be passed to mpl func as subplot_kw=dict(axes_class=kw[‘axes_class’], polar=kw[‘polar’]).

if mode==’flat’, returns a flat tuple of keys, instead of nesting them.

in this case, the dict-like matplotlib keys will NOT be included.

E.g. in the example above, the result would be (‘axes_class’, ‘polar’).

(‘subplot_kw’ gets excluded since it is a dict-like key.)

get_mpl_kwargs(mpl_funcname, **kw)

return kwargs to use for mpl_funcname, using values from self as defaults, and kw if provided.

is_default(key)

return whether key has the default value for this setting.

pop_mpl_kwargs(mpl_funcname, kw, **other_kwargs)

return kwargs to use for mpl_funcname, using values from self as defaults, and kw if provided.

pop values from kw if they are used.

use values from kw if possible,

else from other_kwargs if possible (exists and not UNSET).

else from self if possible (not UNSET).

set(**kw)

set plot settings, in self.

kwargs which are not recognized as valid PlotSettings.valid_keys() will be ignored.

take_from(d)

update self.kw with d, popping keys from d instead of just copying values.

update(d, *, pop=False)

update self.kw with d, but only for keys in self.valid_keys().

if pop, pop keys from d instead of just copying values.

classmethod valid_keys()

return set of all valid keys for plot settings.

This includes all keys from cls.DEFAULT_SETTINGS as well as all mpl keys.

classmethod validate(key, value)

raise InputError if value is invalid for key, or PlotSettingsError if key not in self.valid_keys().

return None if no validation was performed, else the result of validate (see PlotSetting.validate()).