pytilities.aop.advisor

class pytilities.aop.advisor.Advisor

Something that can advise objects, also manages all aspects.

Advice can be given to any non-builtin object. Advice is called before calling the original function/descriptor; it can modify return value, arguments, call the original function, or not, ... See the user guide on how to write advice functions.

There are two types of advice to be given:

  • class advice
  • instance advice

Class advice is advice given to class objects. It is executed for both classes and instances of those classes.

Instance advice is advice given to instance objects. It is executed only for instances.

Instance advice always wraps class advice; i.e. upon call, instance advice is processed first.

A special kind of advice exists that allows you to advise any member of a class. This advice is called * advice, it exists for class and instance advice. It requires the advised object has AOPMeta as its metaclass. You can give * advice by specifying ‘*’ as the member to advise.

No advice, not even * advice, can advice private/protected members. Members are considered private/protected if their name begins with a single ‘_’, but isn’t special. You can, however, advice some special attributes that are not in advisor.unadvisables.

Advice can be given separately to gets, sets, dels and calls of a member. Call advice is applied to any function returned by a get of the member it was given to. Note that the returned function needn’t even be actual part of the object’s dict.

Advice is given with aspects. An aspect is a collection of advice to member mappings, it can be (un)applied to an object. The order in which aspects are applied to an object is important. Aspects last applied to an object will have their advice called first. Think of it as wrapping all previous advice with new advice. In fact, you’d best not even care about previously given advice. If previous advice doesn’t break the interface, information is hidden well enough not to think about other advice, and by doing so reduce coupling.

Note on static methods: with a class A, an instance a and a static method h; A.h() is not necessarily the same as a.h() as a.h() might be given instance advice. (this may be non-intuitive, but the converse was near impossible to implement)

_Advisor__get_advice(obj, member, access)

Get iter of advice for member of obj.

Parameters:
  • obj (class or instance) – the object to advise
  • member (_AOPDescriptor) – member of the object
  • access (‘__get__’, ‘__set__’, ‘__delete__’ or ‘__call__’) – the type of access being done
Returns:

advice funcs, the left is the most outer advice (i.e. the first advice to call, the last advice given, with class advice preceding instance advice)

Return type:

iter(advice...)

_Advisor__place_descriptors(obj, members)

places aop descriptors on given members of obj

_Advisor__proceed(obj, member, advised, access, advices, index, args, kwargs)

advised: the function that’s being advised, will be called on proceed access: type of access required: get, set, del, call advices: list of advice: [[advice, generator], ...] index: currend advice in advices args: a list of positional args kwargs: a dictionary of keyword args

__init__()
apply(aspect, obj, members)

Apply an aspect to an object.

If the aspect was already applied, this call does nothing.

Note to user: use aspect.apply(obj) instead

Parameters:
  • aspect (Aspect) – the aspect to apply
  • obj (class or instance) – the object to advise
  • members (set of str) – members that are advised by the aspect
is_advisable(name)

See if an attribute with name name is advisable.

is_applied(aspect, obj)

Get if this aspect is currently applied to an object.

Note to user: use aspect.is_applied(obj) instead

Parameters:
  • obj (class or instance) – the object to advise
Returns:

True if advice is currently applied to obj, False otherwise

process_call(obj, member, advised, access, args, kwargs)

Process a get/set/del/regular call to an attribute.

Class and instance advice will be applied to the call.

Internal function.

Parameters:
  • obj (class, instance) – the object to advise
  • member (str) – member name of the object
  • access (‘__get__’, ‘__set__’, ‘__delete__’ or ‘__call__’) – the type of access being done
  • args – positional args of the call. Must include the self param, if any
  • kwargs – keyword args of the call
  • function – when access is __call__, this function will be used as the advised object to call on most inner proceed.
Returns:

the value that should be returned to the caller

unapply(aspect, obj)

Unapply an aspect of an object.

If the aspect wasn’t applied, do nothing.

Note to user: use aspect.unapply(obj) instead

Parameters:
  • aspect (Aspect) – the aspect to apply
  • obj (class or instance) – the object to advise
unapply_all(obj)

Unapply all advice given to an object.

aspect.unapply(obj) is called for any aspect applied to this object. You should call this from your advised object’s dtor or del handler.

Parameters:
  • obj (class or instance) – the object to advise
__weakref__

list of weak references to the object (if defined)

unadvisables

Names of attributes that cannot be advised

Previous topic

pytilities.aop.functions

Next topic

pytilities.aop.aopmeta

This Page