metawrap.metawrap module

The module metawrap provides support decorating functions and classes.

Overview

The module metawrap extends wrapping abilities found in functools. In particular, it is ensured all wrapped functions contain an attribute __wrapped__, which points back to the original function before the wrapper was applied. Also, the ability to wrap classes with a decorator to apply a metaclass or series of ``metaclass``es is provided. Making it much easier to transform classes without mucking in their internals.

API

metawrap.metawrap.class_decorate_all_methods(*decorators)

Returns a decorator that decorates a class such that all its methods are decorated by the decorators provided.

Parameters:*decorators (tuple) – decorators to decorate all methods with. Returns:a decorator for the class. Return type:(decorator)

metawrap.metawrap.class_decorate_methods(**method_decorators)

Returns a decorator that decorates a class such that specified methods are decorated by the decorators provided.

Parameters:**method_decorators (tuple) – method names with a single decorator or a list of decorators. Returns:a decorator for the class. Return type:(decorator)

metawrap.metawrap.class_static_variables(**kwargs)

Returns a decorator that decorates a class such that it has the given static variables set.

Parameters:**kwargs (tuple) – keyword args will be set to the value provided. Returns:a decorator for the class. Return type:(decorator)

metawrap.metawrap.identity_wrapper(a_callable)

Trivially wraps a given callable without doing anything else to it.

Parameters:a_callable (callable) – the callable that is being wrapped. Returns:a wrapped callable. Return type:(callable)

metawrap.metawrap.metaclass(meta)

Returns a decorator that decorates a class such that the given metaclass is applied.

Note

Decorator will add the __metaclass__ attribute so the last metaclass applied is known. Also, decorator will add the __wrapped__ attribute so that the unwrapped class can be retrieved.

Parameters:meta (metaclass) – metaclass to apply to a given class. Returns:a decorator for the class. Return type:(decorator)

metawrap.metawrap.metaclasses(*metas)

Returns a decorator that decorates a class such that the given metaclasses are applied.

Note

Shorthand for repeated application of metaclass.

Parameters:*metas (metaclasses) – metaclasses to apply to a given class. Returns:a decorator for the class. Return type:(decorator)

metawrap.metawrap.repack_call_args(a_callable, *args, **kwargs)

Reorganizes args and kwargs to match the given callables signature.

Parameters:

• a_callable (callable) – some callable.
• *args (callable) – positional arguments for the callable.
• **kwargs (callable) – keyword arguments for the callable.

Returns:

all arguments as passed as position

arguments, all default arguments and all arguments passed as keyword arguments.

Return type:

args (tuple)

metawrap.metawrap.static_variables(**kwargs)

Returns a decorator that decorates a callable such that it has the given static variables set.

Parameters:*kwargs (tuple) – keyword args will be set to the value provided. Returns:a decorator for the callable. Return type:(decorator)

metawrap.metawrap.tied_call_args(a_callable, *args, **kwargs)

Ties all the args to their respective variable names.

Parameters:

• a_callable (callable) – some callable.
• *args (callable) – positional arguments for the callable.
• **kwargs (callable) – keyword arguments for the callable.

Returns:

ordered dictionary of arguments name and

their values, all variadic position arguments, all variadic keyword arguments.

Return type:

args (tuple)

metawrap.metawrap.unwrap(a_callable)

Returns the underlying function that was wrapped.

Parameters:a_callable (callable) – some wrapped (or not) callable. Returns:the callable that is no longer wrapped. Return type:(callable)

metawrap.metawrap.update_wrapper(wrapper, wrapped, assigned=('__module__', '__name__', '__doc__'), updated=('__dict__', ))

Extends functools.update_wrapper to ensure that it stores the wrapped function in the attribute __wrapped__.

Parameters:

• wrapper (callable) – the replacement callable.
• wrapped (callable) – the callable that is being wrapped.
• assigned (tuple) – is a tuple naming the attributes assigned directly from the wrapped function to the wrapper function (defaults to functools.WRAPPER_ASSIGNMENTS)
• updated (tuple) – is a tuple naming the attributes of the wrapper that are updated with the corresponding attribute from the wrapped function (defaults to functools.WRAPPER_UPDATES)

Returns:

the wrapped callable.

Return type:

(callable)

metawrap.metawrap.with_setup_state(setup=None, teardown=None)

Adds setup and teardown callable to a function s.t. they can mutate it.

Based on with_setup from nose. This goes a bit further than nose does and provides a mechanism for the setup and teardown functions to change the callable in question. In other words, variables generated in setup can be stored in the functions globals and then cleaned up and removed in teardown. The final result of using this function should be a function equivalent to one generated by with_setup.

Parameters:

• setup (callable) – A callable that takes the decorated function as an argument. This sets up the function before execution.
• teardown (callable) – A callable that takes the decorated function as an argument. This cleans up the function after execution.

Returns:

Does the actual decoration.

Return type:

callable

metawrap.metawrap.with_setup_state_handler(a_callable)

A final wrapper for with_setup_state.

This calls setup and teardown before and after if defined. When used as a decorator, this should come after all setup and teardown calls.

Parameters:a_callable (callable) – A callable to run setup and teardown on. Returns:The wrapped function. Return type:callable

metawrap.metawrap.wraps(wrapped, assigned=('__module__', '__name__', '__doc__'), updated=('__dict__', ))

Builds on functools.wraps to ensure that it stores the wrapped function in the attribute __wrapped__.

Parameters:

• wrapped (callable) – the callable that is being wrapped.
• assigned (tuple) – is a tuple naming the attributes assigned directly from the wrapped function to the wrapper function (defaults to functools.WRAPPER_ASSIGNMENTS)
• updated (tuple) – is a tuple naming the attributes of the wrapper that are updated with the corresponding attribute from the wrapped function (defaults to functools.WRAPPER_UPDATES)

Returns:

a decorator for callable, which will

contain wrapped.

Return type:

(callable)