pytilities.aop.advisor — Pytilities v1.0.0 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Pytilities v1.0.0 documentation »
- API documentation »
- pytilities »
- pytilities.aop »

# 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

### Navigation

- index
- modules |
- next |
- previous |
- Pytilities v1.0.0 documentation »
- API documentation »
- pytilities »
- pytilities.aop »