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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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__', ))[source]¶ 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)[source]¶ Adds setup and teardown callable to a function s.t. they can mutate it.
Based on
with_setup
fromnose
. This goes a bit further thannose
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 bywith_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)[source]¶ A final wrapper for
with_setup_state
.This calls
setup
andteardown
before and after if defined. When used as a decorator, this should come after allsetup
andteardown
calls.Parameters: a_callable (callable) – A callable to run setup
andteardown
on.Returns: The wrapped function. Return type: callable
-
metawrap.metawrap.
wraps
(wrapped, assigned=('__module__', '__name__', '__doc__'), updated=('__dict__', ))[source]¶ 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)