Decorators

Note

MyPlotSpec’s decorator classes all support arguments provided at decoration (e.g. @decorator(foo = bar)). These use a different syntax from decorator classes without arguments. When the wrapped function is declared, __init__ and __call__ from the decorator are called sequentially. __init__ receives the arguments, while __call__ receives the function. __init__ should store the values of the arguments, while __call__ should prepare and return a wrapped function using their values. Subsequent calls will go to the wrapped function. For decorator classes without arguments, __init__ is called when the function is declared, and should store the reference to the function; __call__ is called when the function is called, and should carry out the pre-function decorator logic, run the function, and carry out the post-function decorator logic.

Note

MyPlotSpec’s decorator classes manage_kwargs, manage_output, and debug_arguments may be used to wrap either functions or methods. This is enabled by restricting the arguments of their wrapped_function to *args and **kwargs, and accessing any arguments needed by the decorator using kwargs.pop() or kwargs.get(). If a method is wrapped, the first argument is the host object of the method (self), shifting the positions of other named arguments.

manage_defaults_presets

class myplotspec.manage_defaults_presets.manage_defaults_presets(verbose=1, debug=0)

Bases: object

Decorator to manage the passage of defaults and available presets to a method.

This decorator is a partner to manage_kwargs, desiged to allows its use for methods of objects containg central defaults and available_presets attributes. It obtains available defaults and presets for the wrapped method from their central location in the host object, and passes on those applicable to the wrapped method. manage_kwargs then selects arguments to pass from among the provided defaults, available and selected presets, YAML file, and arguments provided at call time.

Defaults are accessed from the host object’s instance (or class) variable self.defaults, and may be a dict, a path to a YAML file, or a YAML string. Outer level (of indentation or keys) provides function names, and inner level provides default arguments to each function:

defaults = """
    method_1:
        method_1_arg_1: 1000
        method_1_arg_2: abcd
    method_2
        method_2_arg_1: 2000
        method_2_arg_2: efgh
    ...
"""

Presets are accessed from the host objects’s instance (or class) variable self.available_presets, in the same formats as self.defaults. Presets contain an outer level of keys providing the names of available presets:

available_presets = """
    preset_1:
        method_1:
            method_1_arg_1: 1001
            method_1_arg_2: abcde
        method_2
            method_2_arg_1: 2001
            method_2_arg_2: efghi
    preset_2:
        method_1:
            method_1_arg_1: 1002
            method_1_arg_2: abcdef
        method_2
            method_2_arg_1: 2002
        method_2_arg_2: efghij
"""

When this decorator is used to wrap a method of a class, it adds to the arguments being passed defaults, containing the defaults specified for the method, and available_presets, containing only the presets applicable to the method:

@manage_defaults_presets()
def method_1(*args, **kwargs):
    print(kwargs)
    ...

{
    'defaults': {
        'method_1_argument_1': 1000,
        'method_1_argument_2': 'asdf'
    },
    'presets': {
        'preset_1': {
            'method_1_argument_1': 1001,
            'method_1_argument_2': 'asde'
        },
        'preset_1': {
            'method_1_argument_1': 1002,
            'method_1_argument_2': 'asdef'
        }
    },
    ...
}
verbose

int

Level of verbose output

debug

int

Level of debug output

Stores arguments provided at decoration.

Parameters:
  • verbose (int) – Level of verbose output
  • debug (int) – Level of debug output
__call__(method)

Wraps method.

Parameters:method (method) – method to wrap
Returns:(method) – Wrapped method

manage_kwargs

class myplotspec.manage_kwargs.manage_kwargs(verbose=0, debug=0)

Bases: object

Decorator to manage the passage of keyword arguments to a function or method.

Accumulates keyword arguments from several sources, in order of increasing priority:

  1. Defaults

Obtained from the argument defaults, which may be a dict, a path to a YAML file, or a YAML string:

my_function(
    defaults = {
        'fig_width':  5.0
        'fig_height': 5.0
    },
    ...
)
  1. Presets

Available presets are obtained from the argument available_presets, which may be a dict, a path to a YAML file, or a YAML string. Selected presets are obtained from the argument presets, which may be a string or list of strings in order of increasing priority:

my_function(
    presets = 'letter',
    available_presets = {
        'letter': {
            'fig_width':   8.5
            'fig_height': 11.0
        },
        'legal': {
            'fig_width':   8.5
            'fig_height': 14.0
        }
    },
    ...
)
  1. YAML file

YAML file is obtained from the keyword argument yaml_spec, which may be a dict, a path to a YAML file, or a YAML string. Selected keys within the YAML file from which to load arguments are obtained from the argument yaml_keys, which is a list of lists in order of increasing priority:

my_function(
    yaml_spec = {
        'figures': {
            'all': {
                'fig_width':  11.0,
                'fig_height': 17.0,
                'outfile':    'plot.pdf'
            },
            '0': {
                'fig_width':  12.0
            }
        }
    },
    yaml_keys = [['figures', 'all'], ['figures', '0']],
    ...
)

If yaml_keys is omitted, the complete yaml file will be used.

  1. Function call

Arguments provided at function call:

my_function(
    fig_width  = 6.0,
    fig_height = 6.0,
    ...
)

All of the above will override defaults provided in the function declaration itself.

verbose

int

Level of verbose output

debug

int

Level of debug output

Stores arguments provided at decoration.

Parameters:
  • verbose (int) – Level of verbose output
  • debug (int) – Level of debug output
__call__(function)

Wraps function or method.

Parameters:function (function) – Function or method to wrap
Returns:(function) – Wrapped function or method

manage_output

class myplotspec.manage_output.manage_output

Bases: object

Decorator to manage the output of matplotlib figures.

Saves figure returned by wrapped function to a file named outfile; passing additional keyword arguments savefig_kw to Figure.savefig(). For pdf output, additional argument outfiles may be provided; containing a dictionary whose keys are the paths to output pdf files, and whose values are open PdfPages objects representing those files. The purpose of this is to allow figures output from multiple calls to the wrapped function to be output to sequential pages of the same pdf file. Typically outfiles will be initialized before calling this wrapped function; and once calls to the function is complete the PdfPages.close() method of each outfile in outfiles is called.

__call__(function)

Wraps function or method.

Parameters:function (function) – Function or method to wrap
Returns:(function) – Wrapped function or method