cape.tnakit.kwutils: Tools for Processing Keyword Arguments

This module contains methods to process keyword argument dictionaries by checking them against

• a list (ideally a set) of acceptable names

• a dictionary of alternate names

• a dictionary of acceptable types

• a dictionary of other keys required for any key with dependencies

class cape.tnakit.kwutils.KwargHandler(_optsdict=None, _warnmode=1, **kw)

Class to process kwargs against preset key lists and types

Call:

>>> opts = KwargHandler(_optsdict=None, _warnmode=1, **kw)

Inputs:

kw: dict

Keyword arguments turned into options

_optsdict: {None} | dict

Dictionary of previous options (overwritten by kw)

_warnmode: 0 | {1} | 2

Warning mode from kwutils

_section: {None} | str

Name of options section to restrict to

_optlist: {None} | set[str]

Specified list of allowed options

Outputs:

opts: MPLOpts

Options interface from kw with checks and applied defaults

Versions:

• 2020-01-16 @ddalle: Generalized from plot_mpl

classmethod combine_kw_subalias(parentcls=None, f=False)

Combine _kw_subalias from two classes

Sections present in both cls._kw_subalias and parentcls._kw_submap are merged.

Call:

>>> cls.combine_kw_subalias(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_kw_submap(parentcls=None, f=False)

Combine _kw_submap from two classes

Sections present in both cls._kw_submap and parentcls._kw_submap are merged.

Call:

>>> cls.combine_kw_submap(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_optdefs(parentcls=None, f=False)

Combine _optlist and all other KwargHandler attrs

Call:

>>> cls.combine_opts(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_optdependencies(parentcls=None, f=False)

Combine _optdependencies from two classes

Call:

>>> cls.combine_optdependencies(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optdict(attr, parentcls=None, f=False)

Combine dict attribute from two classes

Call:

>>> cls.combine_optdict(cls, attr, parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

attr: str

Name of attribute to combine

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | False

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optlist(parentcls=None, f=False)

Combine _optlist from two classes

Call:

>>> cls.combine_optlist(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optlists(parentcls=None, f=False)

Combine _optlists from two classes

Sections present in both cls._optlists and parentcls._optlists are merged.

Call:

>>> cls.combine_optlists(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optmap(parentcls=None, f=False)

Combine _optmap from two classes

Call:

>>> cls.combine_optmap(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optset(attr, parentcls=None, f=False)

Combine set attribute from two classes

Call:

>>> cls.combine_optset(cls, attr, parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

attr: str

Name of attribute to combine

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | False

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_opttypes(parentcls=None, f=False)

Combine _opttypes from two classes

Call:

>>> cls.combine_opttypes(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_optvals(parentcls=None, f=False)

Combine _optvals from two classes

Call:

>>> cls.combine_optvals(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

classmethod combine_rc(parentcls=None, f=False)

Combine _rc from two classes

Options present in both cls._rc and parentcls._rc are merged (recursively).

Call:

>>> cls.combine_rc(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_rc_sections(parentcls=None, f=False)

Combine _rc_sections from two classes

Sections present in both cls._rc_sections and parentcls._rc_sections are merged (recursively).

Call:

>>> cls.combine_rc_sections(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_rst_descriptions(parentcls=None, f=False)

Combine _rst_descriptions from two classes

Call:

>>> cls.combine_rst_descriptions(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_rst_types(parentcls=None, f=False)

Combine _rst_types from two classes

Call:

>>> cls.combine_rst_types(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-12 @ddalle: First version

classmethod combine_tagmap(parentcls=None, f=False)

Combine _tagmap from two classes

Call:

>>> cls.combine_tagmap(parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | {False}

Option to combine even if no value in cls.__dict__

Versions:

• 2020-03-18 @ddalle: First version

classmethod denone(opts)

Remove any keys whose value is None

Call:

>>> opts = denone(opts)

Inputs:

opts: dict

Any dictionary

Outputs:

opts: dict

Input with any keys whose value is None removed; returned for convenience but input is also affected

Versions:

• 2019-03-01 @ddalle: First version

• 2019-12-19 @ddalle: From mplopts

• 2020-01-16 @ddalle: From plot_mpl

get_option(opt, vdef=None, parents=None)

Get value of a specific option, ignoring section

Call:

>>> optval = opts.get_option(opt, vdef=None, parents=None)

Inputs:

opts: KwargHandler

Options interface

opt: str

Name of option

vdef: {None} | any

Default value, ignored if opt in _rc

parents: None | set[str]

List of parents, used to detect recursion

Outputs:

optval: any

Processed value, from opts or opts._rc, with additional processing from opts._kw_submap, and others

Versions:

• 2020-01-17 @ddalle: First version

section_options(sec, mainopt=None)

Process options for a particular section

Call:

>>> kw = opts.section_options(sec, mainopt=None)

Inputs:

opts: KwargHandler

Options interface

sec: str

Name of options section

mainopt: {None} | str

If specified, return value of this option instead of dict of all options from section; this is most often used when mainopt itself has a dict type where the other sec options get mapped into it

Outputs:

kw: dict

Dictionary of options in opts relevant to sec

Versions:

• 2020-01-16 @ddalle: First version

classmethod select_phase(kw, i=0)

Select option i for each option in kw

This cycles through lists of options for named options such as color and repeats if i is longer than the list of options. Special options like dashes that accept a list as a value are handled automatically. If the value of the option is a single value, it is returned regardless of the value of i.

Call:

>>> kw_p = cls.select_plotphase(kw, i=0)

Inputs:

kw: dict

Dictionary of options for one or more graphics features

i: {0} | int

Index

Outputs:

kw_p: dict

Dictionary of options with lists replaced by scalar values

Versions:

• 2019-03-04 @ddalle: First version

• 2020-01-16 @ddalle: From plot_mpl

set_option(opt, val)

Set an option, with checks

The option is first looked up in _optmap and saved with the full name found there, if any. After mapping, opt is checked against the _optlist and _opttypes of the class.

Call:

>>> opts.set_option(opt, val)

Inputs:

opts: KwargHandler

Options interface

opt: str

Name of option

val: any

Specified value

Versions:

• 2020-01-26 @ddalle: First version

setdefault_option(opt, val)

Set an option, with checks, but without overwriting

The option is first looked up in _optmap and saved with the full name found there, if any. After mapping, opt is checked against the _optlist and _opttypes of the class.

Call:

>>> v = opts.setdefault_option(opt, val)

Inputs:

opts: KwargHandler

Options interface

opt: str

Name of option

val: any

Specified value

Outputs:

v: opts[opt] | val

Same as output from setdefault()

Versions:

• 2020-01-26 @ddalle: First version

update(**kw)

Apply several settings, with checks, from kwargs

This works like the standard dict.apply() with two differences:

• The same keyword checks and name changes that take place during __init__() are also done on kw

• If both opts and kw have a value for key k, with v0 for opts[k] and v for kw[k], then the two values are blended using v0.update(v)

Call:

>>> opts.update(**kw)

Inputs:

opts: KwargHandler

Options interface

kw: dict

Additional options added to opts, with checks

Versions:

• 2020-01-24 @ddalle: First version

classmethod update_optdict(attr, parentcls=None, f=False)

Combine dict attribute from two classes

If attr is present in both classes, cls.attr overrides.

Call:

>>> cls.setdefault_optdict(cls, attr, parentcls=None, f=False)

Inputs:

cls: type

KwargHandler class or subclass

attr: str

Name of attribute to combine

parentcls: {cls.__bases__[0]} | type

Second KwargHandler class or subclass

f: True | False

Option to combine even if no value in cls.__dict__

Versions:

• 2020-02-11 @ddalle: First version

cape.tnakit.kwutils.check_kw(kwlist, kwmap, kwdep, mode, **kw)

Check and map valid keyword names

Call:

>>> kwo = check_kw(kwlist, kwmap, kwdep, mode, **kw)

Inputs:

kwlist: {db._kw} | list[str]

List of acceptable parameters

kwmap: {db._kw_map}: dict[str]

Map of alternate: primary abbreviations

kwdep: {db._kw_depends} | dict[list]

Dictionary of required parameters for some parameters

mode: 0 | {1} | 2

Flag for quiet (0), warn (1), or strict (2)

kw: dict

Any keyword arguments

Outputs:

kwo: dict

Valid keywords and their values from kw

Versions:

• 2019-12-13 @ddalle: First version

cape.tnakit.kwutils.check_kw_eltypes(kwlist, kwmap, kwtypes, kwdep, mode, **kw)

Check and map valid keyword names

Each keyword is permitted to be a list of the required type in addition to just being the correct type.

Call:

>>> kwo = check_kw_eltypes(|args2|, **kw)

Inputs:

kwlist: set[str]

List (set) of acceptable parameters

kwtypes: {db._kw_types} | dict

Dictionary of type or tuple[type] for some or all keywords, used with isinstance()

kwmap: {db._kw_map}: dict[str]

Map of alternate: primary abbreviations

kwdep: {db._kw_depends} | dict[list]

Dictionary of required parameters for some parameters

mode: 0 | {1} | 2

Flag for quiet (0), warn (1), or strict (2)

kw: dict

Any keyword arguments

Outputs:

kwo: dict

Valid keywords and their values from kw

Versions:

• 2019-12-13 @ddalle: First version

cape.tnakit.kwutils.check_kw_types(kwlist, kwmap, kwtypes, kwdep, mode, **kw)

Check and map valid keyword names

Call:

>>> kwo = check_kw_types(|args1|, **kw)

Inputs:

db: cape.attdb.ftypes.basefile.BaseFile

Data file interface

kwlist: {db._kw} | list[str]

List of acceptable parameters

kwtypes: {db._kw_types} | dict

Dictionary of type or tuple[type] for some or all keywords, used with isinstance()

kwmap: {db._kw_map}: dict[str]

Map of alternate: primary abbreviations

kwdep: {db._kw_depends} | dict[list]

Dictionary of required parameters for some parameters

mode: 0 | {1} | 2

Flag for quiet (0), warn (1), or strict (2)

kw: dict

Any keyword arguments

Outputs:

kwo: dict

Valid keywords and their values from kw

Versions:

• 2019-12-13 @ddalle: First version

cape.tnakit.kwutils.map_kw(kwmap, **kw)

Map alternate keyword names with no checks

Call:

>>> kwo = map_kw(kwmap, **kw)

Inputs:

kwmap: {db._kw_map}: dict[str]

Map of alternate: primary abbreviations

kw: dict

Any keyword arguments

Outputs:

kwo: dict

Translated keywords and their values from kw

Versions:

• 2019-12-13 @ddalle: First version