|
|
Documentation
Module interface
- with_wrap(wrap, func [, func] ... [, instances=ITERABLE])
Wraps the new-style (generator) wrap around all
funcs. Returns the number of the wrap over a function (if
only one function was wrapped), or a list of numbers of the wraps over
the functions (if multiple functions were wrapped).
- without_wrap(wrap_or_wrapid, func)
Removes the new-style wrap around the func function. Returns the
removed wrap.
- disable_wrap(func, wrap_id)
Disables the
wrap with number wrap_id over the function
func. Disabled wraps are omitted when func is
called.
- enable_wrap(func, wrap_id)
Enables the
wrap with number wrap_id over the function
func.
- wrap_is_enabled(func, wrap_id)
Returns 1
if the wrap with number wrap_id over the function
func is enabled, otherwise 0.
- peel_around(func) (Will be deprecated.)
Removes the topmost wrap over the function func. Returns the
wrap.
- wrap_around(method, wrap [, instances]) (Will
be deprecated.)
Wraps an old-style wrap around
a method. Returns the number of the wrap over the method.
- wrap_around_re(class, regexp, wrap)
Wraps
wrap around all methods whose names match to regexp.
More detailed specification can be found in aspects.py. Try:
>>> import aspects
>>> help(aspects)
Wrap interface
If a function (or a method) f is wrapped in a wrap
using with_wrap, the function f will be replaced
by a "middleman" function in the dictionary of its module (or
its class). The middleman knows both function f and the
wrap. Due to the replacement, the middleman will be invoked instead
of f in the future when module.f is
called.
When the middleman is invoked, it has two options. It either
- creates a new instance of the wrap generator by calling it with
the arguments with which the middleman was called, or
- continues the execution of an existing wrap generator by
sending it the call arguments.
Indeed, the middleman and the wrap run as coroutines, which
were made possible by enhanced
generators in Python 2.5.
When the wrap is running, the middleman waits for it to
yield. The future behaviour depends on the object that the wrap
yields. The possibilities are
| Yielded object | Future action |
|---|
proceed class
rv = yield aspects.proceed |
the wrapped function f is called with the arguments with
which the middleman was called. If an exception is raised from
f, the middleman will pass it to the wrap. The return value
of f will be sent to the wrap. If the wrap does not yield
anything after proceed, the same return value will be returned by the
middleman. |
proceed object
rv = yield aspects.proceed(x,y) |
otherwise the same as above, but the function f is called
with the arguments that were given to the constructor of the proceed
object. |
return_stop class
yield aspects.return_stop |
the middleman returns the value that was returned by the last call
of f. The execution of the wrap generator is stopped: when
the middleman is called next time, the wrap will be restarted. |
return_stop object
yield
aspects.return_stop(42) | the middleman returns the value
given as the argument to the constructor of return_stop. The execution
of the wrap is stopped. |
return_cont class
args, kwargs = yield aspects.return_cont |
the middleman returns the value that was returned by the last call
of f. The execution of the wrap will be continued. When the
middleman is called next time, the same wrap generator instance will
be sent the new call arguments. |
return_cont object
args, kwargs = yield
aspects.return_cont(42) | otherwise same as above, but
the middleman returns the value given as the argument to the
constructor of return_cont. |
get_wrapped class
fun = yield aspects.get_wrapped |
the middleman sends function f to the wrap. Note that
f may be the original function or the middleman of a lower
wrap. |
|
