>>> from peak.rules.core import implies

>>> implies(int, object)
True
>>> implies(object, int)
False

>>> implies(int, str)
False

>>> implies(int, int)
True

>>> implies( (int,str), (object,object) )
True

>>> implies( (object,int), (object,str) )
False

>>> implies( (int,int), (object,) )
True

>>> implies( (int,), (object,object) )
False

>>> class X: pass

>>> implies(X, object)
True

>>> from types import InstanceType
>>> implies(X, InstanceType)
True

istype() objects

Type or class objects are used to represent "this class or a subclass", but istype() objects are used to represent either "this exact type" (using istype(aType, True)), or "anything but this exact type" (istype(aType, False)). So their implication rules are different.

Internally, PEAK-Rules uses istype objects to represent a call signature being matched, because the argument being tested is of some exact type. Then, any rule signatures that are implied by the calling signature are considered "applicable".

So, istype(aType, True) (the default) must always imply the same type or class, or any parent class thereof:

>>> from peak.rules import istype

>>> implies(istype(int), int)
True
>>> implies(istype(int), object)
True
>>> implies(istype(X), InstanceType)
True
>>> implies(istype(X), object)
True

But not the other way around:

>>> implies(int, istype(int))
False
>>> implies(object, istype(int))
False
>>> implies(InstanceType, istype(X))
False
>>> implies(object, istype(X))
False

An exact type will also imply any exclusion of a different exact type:

>>> implies(istype(int), istype(str, False))
True

In other words, if type(x) is int, that implies type(x) is not str. But of course, that doesn't work they other way around:

>>> implies(istype(str, False), istype(int))
False

These implication rules are sufficient to bootstrap the basic types-only rules engine; additional rules for istype behavior are explained in Criteria.txt to show intersection of criteria such as istype, and other more-advanced criteria manipulation used in the full predicate rules engine.

Method

The default action type (for rules with no specified action type) is Method. A Method combines a body, a signature, a definition-order serial number, and an optional "chained" action that it can fall back to. All of these values are optional, except for the body:

>>> from peak.rules.core import Method, overrides

>>> def dummy(*args, **kw):
...     print "called with", args, kw

>>> meth = Method.make(dummy, (object,), 1)
>>> meth
Method(<...dummy...>, (<type 'object'>,), 1, None)

Calling a Method invokes the wrapped body:

>>> meth(1,2,x=3)
called with (1, 2) {'x': 3}

One Method overrides another if and only if its signature implies the other's:

>>> overrides(Method.make(dummy,(int,int)), Method.make(dummy,(object,object)))
True

>>> overrides(Method.make(dummy,(object,object)), Method.make(dummy,(int,int)))
False

When a method overrides another, you get the overriding method:

>>> meth.override(Method.make(dummy))
Method(<...dummy...>, (<type 'object'>,), 1, None)

Unless the overriding method's body is a function whose first parameter is named next_method, in which case a chain of methods is created via the "tail" of a copy of the overriding method:

>>> def overriding_fn(next_method, etc):
...     print "calling", next_method
...     return next_method(etc)

>>> chain = Method.make(overriding_fn).override(Method.make(dummy))
>>> chain
Method(<...overriding_fn...>, (), 0, Method(<...dummy...>, (), 0, None))

The resulting chain is a callable Method, and the next_method is passed in to the first function of the chain:

>>> chain(42)
calling <function dummy at...>
called with (42,) {}

Around

Around methods are identical to normal Method objects, except that whenever an Around method and a regular Method are combined, the Around method overrides the regular one. This forces all the regular methods to be further down the chain than all of the "around" methods.

>>> from peak.rules.core import Around

>>> combine_actions(Method.make(dummy), Around(overriding_fn))
Around(<...overriding_fn...>, (), 0, Method(<...dummy...>, (), 0, None))

You will normally only want to use Around methods with functions that have a next_method parameter, since their purpose is to wrap "around" the calling of lower-precedence methods. If you don't do this, then the method chain will always end at that Around instance:

>>> combine_actions(Method.make(overriding_fn), Around(dummy))
Around(<...dummy...>, (), 0, None)

NoApplicableMethods

The simplest possible action type is NoApplicableMethods, meaning that there is no applicable action. When it's overridden by another method, it will of course get chained to the other method's tail (if appropriate).

>>> from peak.rules import NoApplicableMethods
>>> naf = NoApplicableMethods()
>>> meth = Method.make(overriding_fn)

>>> combine_actions(naf, meth)
Method(<...overriding_fn...>, (), 0, NoApplicableMethods())

>>> combine_actions(meth, naf)
Method(<...overriding_fn...>, (), 0, NoApplicableMethods())

Calling a NoApplicableMethods raises it, displaying the arguments it was called with:

>>> naf(1,2,x="y")
Traceback (most recent call last):
  ...
NoApplicableMethods: ((1, 2), {'x': 'y'})

Before, After, and MethodList

MethodList actions differ from normal method chain actions in a number of ways:

• In case of ambiguity, they are ordered according to the sequence they were given in the underlying rule set.
• They do not need to inspect or call a next_method(); the next method is always called automatically.

The Before and After action types are both MethodList subclasses. Before actions are invoked before their tail action, and After actions are invoked afterward:

>>> from peak.rules.core import Before, After

>>> def primary(*args,**kw):
...     print "primary method called"
...     return 99

>>> b = Before.make(dummy).override(Method.make(primary))
>>> a = After.make(dummy).override(Method.make(primary))

>>> b(23)
called with (23,) {}
primary method called
99

>>> a(42)
primary method called
called with (42,) {}
99

Notice that to create a MethodList with only one method, you must use the make() classmethod. Method also has this classmethod, but it has the same signature as the main constructor. The main constructor for MethodList has a different signature for its internal use.

The combination of before, after, primary, and around methods is as shown:

>>> b = Before.make(dummy)
>>> a = After.make(dummy)
>>> p = Method.make(primary)
>>> o = Around.make(overriding_fn)
>>> combine_actions(b, combine_actions(a, combine_actions(p, o)))(17)
calling <function before_template at ...>
called with (17,) {}
primary method called
called with (17,) {}
99

Around methods take precedence over all other method types, so the around method's tail is a Before that wraps the After that wraps the primary method.

Within a MethodList, methods are ordered by signature implication first, and then by definition order within groups of ambiguous signatures:

>>> b1 = Before.make("b1", (), 1)
>>> b2 = Before.make("b2", (), 2)
>>> b3 = Before.make("b3", (int,), 3)

>>> combine_actions(b2, b3).sorted()
[((<type 'int'>,), 'b3'), ((), 'b2')]

>>> combine_actions(b2, b1).sorted()
[((), 'b1'), ((), 'b2')]

>>> combine_actions(b3, combine_actions(b1,b2)).sorted()
[((<type 'int'>,), 'b3'), ((), 'b1'), ((), 'b2')]

After methods sort the opposite way:

>>> a1 = After.make("a1", (), 1)
>>> a2 = After.make("a2", (), 2)
>>> a3 = After.make("a3", (int,), 3)

>>> combine_actions(a2, a3).sorted()
[((), 'a2'), ((<type 'int'>,), 'a3')]

>>> combine_actions(a2, a1).sorted()
[((), 'a2'), ((), 'a1')]

>>> combine_actions(a3, combine_actions(a1,a2)).sorted()
[((), 'a2'), ((), 'a1'), ((<type 'int'>,), 'a3')]

And lower-precedence duplicate bodies are automatically eliminated from the results:

>>> combine_actions(a1,a1).sorted()
[((), 'a1')]

>>> combine_actions(b1,b1).sorted()
[((), 'b1')]

>>> combine_actions(b1, Before.make("b1", (int,), 1)).sorted()
[((<type 'int'>,), 'b1')]

AmbiguousMethods

When you combine actions whose signatures are ambiguous (i.e. identical, overlapping, or mutually exclusive), you end up with an AmbiguousMethods object containing the ambiguous methods:

>>> am = combine_actions(meth, meth)
>>> am
AmbiguousMethods([Method(...), Method(...)])

Ambiguous methods can be overridden by an action that would override all of the ambiguous actions:

>>> m1 = Method.make(dummy, (int,))
>>> combine_actions(am, m1) is m1
True
>>> combine_actions(m1, am) is m1
True

And if appropriate, the AmbiguousMethods will end up chained to the overriding method:

>>> m2 = Method.make(overriding_fn, (str,))
>>> combine_actions(am, m2)
Method(<...overriding_fn...>, (<type 'str'>,), 0, AmbiguousMethods(...))

>>> combine_actions(m2, am)
Method(<...overriding_fn...>, (<type 'str'>,), 0, AmbiguousMethods(...))

Ambiguous methods override and ignore anything that would be overridden by any of their members:

>>> am = combine_actions(m1, m1)
>>> combine_actions(am, meth) is am
True
>>> combine_actions(meth, am) is am
True

But anything that overlaps just results in a bigger AmbiguousMethods:

>>> combine_actions(m2,am)
AmbiguousMethods([Method(...), Method(...), Method(...)])

>>> combine_actions(am,m2)
AmbiguousMethods([Method(...), Method(...), Method(...)])

And invoking an AmbiguousMethods instance just outputs diagnostic info:

>>> am(1,2,x="y")
Traceback (most recent call last):
  ...
AmbiguousMethods: ([Method(...), Method(...)], (1, 2), {'x': 'y'})

Custom Method Types and Compilation

Custom method types can be defined by subclassing Method, and used as a generic function's default method type by setting the functions' rules' default_actiontype:

>>> class MyMethod(Method):
...     def __call__(self, *args, **kw):
...         print "calling!"
...         return self.body(*args, **kw)

>>> from peak.rules import when, abstract
>>> from peak.rules.core import rules_for 

>>> tmp = lambda foo: 42

>>> def func_with(mtype):
...     abstract()
...     def f(foo): """dummy"""
...     rules_for(f).default_actiontype = mtype
...     when(f, (object,))(tmp)
...     return f

>>> f = func_with(MyMethod)

>>> f(1)
calling!
42

The compile_method(action, engine) function takes a method and a dispatch engine, and returns a compiled version of the action:

>>> from peak.rules.core import compile_method, Dispatching
>>> engine = Dispatching(f).engine

>>> compile_method(Method(tmp, ()), engine) is tmp
True

However, for our newly defined method type, there is no compilation:

>>> m = MyMethod(tmp, ())
>>> compile_method(m, engine) is tmp
False

>>> compile_method(m, engine) is m
True

This is because our method type redefined __call__() but did not include its own compiled() method.

The compiled() method of a Method subclass takes an Engine as its argument, and should return a callable to be used in place of directly calling the method itself. It should pass any objects it plans to call (e.g. its tail or individual submethods) through compile_method(ob, engine), in order to ensure that those objects are also compiled:

>>> class MyMethod2(Method):
...     def compiled(self, engine):
...         print "compiling"
...         return compile_method(self.body, engine)

>>> m = MyMethod2(tmp)
>>> compile_method(m, engine) is tmp
compiling
True

As you can see, compile_method() invokes our new compiled() method, which ends up returning the original function. And, if we don't define a __call__() method of our own, we end up inheriting one from Method that compiles the method and invokes it for us:

>>> m(1)
compiling
42

However, if we use this method type in a generic function, then the generic function will cache the compiled version of its methods so they don't have to be compiled every time they're called:

>>> f = func_with(MyMethod2)

>>> f(1)
compiling
42

>>> f(1)
42

(Note: what caching is done, and when the cache is reset is heavily dependent on the specific dispatching engine in use; it can also be the case that a similar-looking method object will be compiled more than once, because in each case it has a different tail or match signature.)

Now, Method subclasses do NOT inherit their compiled() method from their base classes, unless they are also inheriting __call__. This prevents you from ending up with strangely-broken code in the event you redefine __call__(), but forget to redefine compiled():

>>> class MyMethod3(MyMethod2):
...     def __call__(self, *args, **kw):
...         print "calling!"
...         return self.body(*args, **kw)

>>> f = func_with(MyMethod3)

>>> f(1)
calling!
42

>>> f(1)
calling!
42

As you can see, the new subclass works, but doesn't get compiled. So, you can do your initial debugging and development without compilation by defining __call__(), and then switch over to compiled() once you're happy with your prototype.

Now, let's define a method type that works like MyMethod3, but is compiled using a template:

>>> class NoisyMethod(Method):
...     def compiled(self, engine):
...         print "compiling"
...         body = compile_method(self.body, engine)
...         return engine.apply_template(noisy_template, body)

So far, it looks a little like our earlier compilation. We compile the body like before, but then, what's that apply_template stuff?

The apply_template() method of engine objects takes a "template" function and one or more arguments representing values that need to be accessible in our compiled function. Let's go ahead and define noisy_template now:

>>> def noisy_template(__func, __body):
...     return """
...         print "calling!"
...         return __body($args)
...     """

Template functions are defined using the conventions of DecoratorTools's @template_function decorator, only without the decorator. The first positional argument is the generic function the compiled method is being used with, and any others are up to you.

Any use of $args is replaced with the correct calling signature for invoking a method of the corresponding generic function, and you must name all of your arguments and local variables such that they won't conflict with any actual argument names. (In practice, this means you want to use __-prefixed names, which is why we're defining the template outside the class, to prevent Python from mangling our parameter names and messing up the template.)

Note, too, that all the other caveats regarding @template_function functions apply, including the fact that the function cannot actually use any of its arguments (or any variables from its containing scope) to determine the return string -- it must simply return a constant string. (It can, however, refer to globals in its defining module, as long as they're not shadowed by the generic function's argument names.)

Okay, let's see our new method type in action:

>>> f = func_with(NoisyMethod)

>>> f(1)
compiling
calling!
42

>>> f(1)
calling!
42

As you can see, the method is still compiled just once, but still prints "calling!" every time it's invoked, as the compiled form of the method is a purpose-built wrapper function.

To save time and memory, the engine.apply_template() tries to memoize calls so that it will return the same function, given the same inputs, so long as the function still exists:

>>> from peak.rules import value
>>> m = NoisyMethod((), value(42))

>>> m1 = compile_method(m)
compiling

>>> m2 = compile_method(m)
compiling

>>> m1 is m2
True

This will only work, however, if all the arguments passed to apply_template are usable as dictionary keys. So, it's best to use tuples instead of lists, frozensets instead of sets, etc. (Also, this means you can't pass in keyword arguments.)

Defining Method Precedence

You can define one method type's precedence relative to another using the >> operator (which always returns its right-side operand):

>>> NoisyMethod >> Method
<class 'peak.rules.core.Method'>

You can also chain >> operators to define overall method precedence between multiple types, e.g.:

>>> Around >> NoisyMethod >> Method
<class 'peak.rules.core.Method'>

As long as you don't try to introduce a precedence cycle:

>>> NoisyMethod >> MyMethod2 >> Around
Traceback (most recent call last):
  ...
TypeError: <class 'peak.rules.core.Around'> already overrides <class 'MyMethod2'>