Package: prioritized_methods
This module provides four decorators:prioritized_whenprioritized_aroundprioritized_beforeprioritized_afterThese behave like theirpeak.rulescounterparts except that they accept an
optionalprioargument which can be used to provide a comparable object
(usually an integer) that will be used to disambiguate
situations in which more than rule applies to the given arguments and no rule
is more specific than another. That is, situations in which anpeak.rules.AmbiguousMethodswould have been raised.This is useful for libraries which want to be extensible via generic functions
but want their users to easily override a method without figuring out how to
write a more specific rule or when it is not feasible.For example, TurboJson provides ajsonifyfunction that looks like this:>>> def jsonify(obj):
...     "jsonify an object"And extends it so it can handle SqlAlchemy mapped classes in a way
similar to this one:>>> from peak.rules import when

>>> def jsonify_sa(obj):
...     print "You're a SA object and I'm going to jsonify you!"

>>> when(jsonify, "hasattr(obj, 'c')")(jsonify_sa) # doctest: +ELLIPSIS
<function jsonify_sa at ...>

>>> class Person(object):
...     def __init__(self):
...         self.c = "im a stub"

>>> jsonify(Person())
You're a SA object and I'm going to jsonify you!So far so good, however, when a user of the library wants to override the built
in implementation it can become quite hard since they have to write a more
specific rule which can be tedious, for example:hasattr(self, 'c') and isinstance(obj, Person)Notice thehasattrtest, even thoughisinstance(obj, Person)implies it,
just to make it more specific than the built in, this gets more cumbersome the
more complicated the expression becomes.Else this is what happens:>>> def jsonify_Person(obj):
...     print "No way, I'm going to jsonify you!"

>>> when(jsonify, (Person,))(jsonify_Person) # doctest: +ELLIPSIS
<function jsonify_Person at ...>

>>> try:
...     jsonify(Person())
... except AmbiguousMethods:
...     print "I told you, gfs can sometimes be a pain"
I told you, gfs can sometimes be a painTo remedy this situationprioritized_whencan be used to provide an
implementation that will override the one declared withwhen:>>> def jsonify_Person2(obj):
...     print "No way, I'm going to jsonify you!"

>>> prioritized_when(jsonify, (Person,))(jsonify_Person2) # doctest: +ELLIPSIS
<function jsonify_Person2 at ...>

>>> jsonify(Person())
No way, I'm going to jsonify you!Notice that we didn’t need aprioargument. This is because methods
decorated withprioritized_whenalways override those that have been
decorated withpeak.rules.when.Methods decorated withprioritized_whencan also override other methods
that have been decorated by the same decorator using theprioparameter,
the one which compares greater wins, if both are equalAmbiguousMethodswill be raised as usual.>>> def jsonify_Person3(obj):
...     print "Don't be so smart, I am, my prio is higher!">>> prioritized_when(jsonify, (Person,), prio=1)(jsonify_Person3) # doctest: +ELLIPSIS
<function jsonify_Person3 at ...>>>> jsonify(Person())
Don't be so smart, I am, my prio is higher!For convenience, agenericdecorator is provided too which behaves
likepeak.rules.dispatch.genericexcept that thewhen,…,``after``
decorators that will be bound as attributes of the decorated function will be
prioritized:>>> @generic
... def f(n): pass

>>> f(5)
Traceback (most recent call last):
    ...
NoApplicableMethods: ((5,), {})Add a default rule:>>> @f.when()
... def default_f(n):
...     return n
>>> f(5)
5Add a default rule that overrides the former:>>> @f.when(prio=1)
... def new_default_f(n):
...     return n+1
>>> f(5)
6