2
Name: prioritized-methods
3
Version: 0.2.2dev-20110830
4
Summary: An extension to PEAK-Rules to prioritize methods in order to to avoid AmbiguousMethods situations
6
Author: Alberto Valverde Gonzalez
7
Author-email: alberto@toscat.net
9
Download-URL: http://toscawidgets.org/download
10
Description: This module provides four decorators:
14
``prioritized_around``
16
``prioritized_before``
20
These behave like their ``peak.rules`` counterparts except that they accept an
21
optional ``prio`` argument which can be used to provide a comparable object
22
(usually an integer) that will be used to disambiguate
23
situations in which more than rule applies to the given arguments and no rule
24
is more specific than another. That is, situations in which an
25
``peak.rules.AmbiguousMethods`` would have been raised.
27
This is useful for libraries which want to be extensible via generic functions
28
but want their users to easily override a method without figuring out how to
29
write a more specific rule or when it is not feasible.
31
For example, TurboJson provides a ``jsonify`` function that looks like this::
34
... "jsonify an object"
37
And extends it so it can handle SqlAlchemy mapped classes in a way
41
>>> from peak.rules import when
43
>>> def jsonify_sa(obj):
44
... print "You're a SA object and I'm going to jsonify you!"
46
>>> when(jsonify, "hasattr(obj, 'c')")(jsonify_sa) # doctest: +ELLIPSIS
47
<function jsonify_sa at ...>
49
>>> class Person(object):
50
... def __init__(self):
51
... self.c = "im a stub"
54
You're a SA object and I'm going to jsonify you!
56
So far so good, however, when a user of the library wants to override the built
57
in implementation it can become quite hard since they have to write a more
58
specific rule which can be tedious, for example::
60
hasattr(self, 'c') and isinstance(obj, Person)
62
Notice the ``hasattr`` test, even though ``isinstance(obj, Person)`` implies it,
63
just to make it more specific than the built in, this gets more cumbersome the
64
more complicated the expression becomes.
66
Else this is what happens::
68
>>> def jsonify_Person(obj):
69
... print "No way, I'm going to jsonify you!"
71
>>> when(jsonify, (Person,))(jsonify_Person) # doctest: +ELLIPSIS
72
<function jsonify_Person at ...>
76
... except AmbiguousMethods:
77
... print "I told you, gfs can sometimes be a pain"
78
I told you, gfs can sometimes be a pain
81
To remedy this situation ``prioritized_when`` can be used to provide an
82
implementation that will override the one declared with ``when``::
84
>>> def jsonify_Person2(obj):
85
... print "No way, I'm going to jsonify you!"
87
>>> prioritized_when(jsonify, (Person,))(jsonify_Person2) # doctest: +ELLIPSIS
88
<function jsonify_Person2 at ...>
91
No way, I'm going to jsonify you!
93
Notice that we didn't need a ``prio`` argument. This is because methods
94
decorated with ``prioritized_when`` always override those that have been
95
decorated with ``peak.rules.when``.
97
Methods decorated with ``prioritized_when`` can also override other methods
98
that have been decorated by the same decorator using the ``prio`` parameter,
99
the one which compares greater wins, if both are equal
100
``AmbiguousMethods`` will be raised as usual.
102
>>> def jsonify_Person3(obj):
103
... print "Don't be so smart, I am, my prio is higher!"
105
>>> prioritized_when(jsonify, (Person,), prio=1)(jsonify_Person3) # doctest: +ELLIPSIS
106
<function jsonify_Person3 at ...>
108
>>> jsonify(Person())
109
Don't be so smart, I am, my prio is higher!
111
For convenience, a ``generic`` decorator is provided too which behaves
112
like ``peak.rules.dispatch.generic`` except that the ``when``,...,``after``
113
decorators that will be bound as attributes of the decorated function will be
120
Traceback (most recent call last):
122
NoApplicableMethods: ((5,), {})
127
... def default_f(n):
132
Add a default rule that overrides the former::
135
... def new_default_f(n):
140
Keywords: PEAK rules generic functions dispatch