ComposingHierarchies


1 Introduction

The purpose of this page is to give a quick overview of how to compose component hierarchies using the PEAK framework, using working code. I have inlined comments in the code example, so hopefully, it will be self explanatory.

2 Code

Here's the code example that I came up with while working out how to compose hierarchies, and "aquire" objects from parent components in PEAK. It requires the current CVS version of PEAK (0.5a3).

    1 #file components1.py
    2 from peak.api import *
    3 
    4 SPAM_PROPERTY = PropertyName("simplecmpApp.spam")
    5 COLOR_PROPERTY = PropertyName("simplecmpApp.color")
    6 EGGS_PROPERTY = PropertyName("simplecmpApp.eggs")
    7 
    8 
    9 #------------------------------------------------------------
   10 class ISpam(protocols.Interface):
   11     """Spam interface"""
   12     def spam():
   13         """provide spam"""
   14 
   15 class Spam(binding.Component):
   16     protocols.advise(instancesProvide=[ISpam])
   17     def spam(self):
   18         return "spam"
   19 
   20 #------------------------------------------------------------
   21 class IEggs(protocols.Interface):
   22     """Eggs interface"""
   23     def eggs():
   24         """provide eggs"""
   25 
   26 class Eggs(binding.Component):
   27     protocols.advise(instancesProvide=[IEggs])
   28     def eggs(self):
   29         return "eggs"
   30 
   31 class OtherEggs(binding.Component):
   32     protocols.advise(instancesProvide=[IEggs])
   33     def eggs(self):
   34         return "othereggs"
   35 
   36 
   37 #------------------------------------------------------------
   38 class GrandChildCmp(binding.Component):
   39     #acquired from SimpleCmp
   40     gcSpam = binding.Obtain(SPAM_PROPERTY)
   41     gcColor = binding.Obtain(COLOR_PROPERTY)
   42     gcEggs = binding.Obtain(EGGS_PROPERTY)
   43     #acquired from ChildCmp
   44     gcOtherEggs = binding.Obtain(IEggs)
   45     #acquired from SimpleCmp
   46     gcStr = binding.Obtain("sc_string")
   47 
   48 class ChildCmp(binding.Component):
   49     #acquired from SimpleCmp
   50     cSpam = binding.Obtain(ISpam)
   51     cStr = binding.Obtain("sc_string")
   52     #overrides IEggs provided by SimpleCmp
   53     cEggs = binding.Obtain(IEggs)
   54     __eggs = binding.Make(OtherEggs, offerAs=[IEggs])
   55 
   56     #make a GrandChild child of this component
   57     grandChild = binding.Make(GrandChildCmp)
   58 
   59 class SimpleCmp(binding.Component):
   60     #simple component variable. Child components can look up directly by name
   61     sc_string = "simple-c!"
   62     #__eggs and __spam are registered as Interfaces and properties
   63     #They can be bound either using binding.Obtain(<InterfaceName>)
   64     #or binding.Obtain(PropertyName(<property.name>))
   65     __eggs = binding.Make(Eggs, offerAs=[IEggs, EGGS_PROPERTY])
   66     __spam = binding.Make(Spam, offerAs=[ISpam, SPAM_PROPERTY])
   67     #__color is a Constant bound to a property
   68     __color = binding.Make(lambda:"red", offerAs=[COLOR_PROPERTY])
   69 
   70     #make a ChildCmp child of this component
   71     child = binding.Make(ChildCmp)
   72 
   73 #------------------------------------------------------------
   74 if __name__ == "__main__":
   75 
   76     sc = SimpleCmp()
   77     c = sc.child
   78     gc = c.grandChild
   79 
   80 
   81     print "c.eggs: ",c.cEggs.eggs()
   82     print "c.spam: ",c.cSpam.spam()
   83     print "c.cStr: ",c.cStr
   84     print "gc.spam: ",gc.gcSpam.spam()
   85     print "gc.eggs: ",gc.gcEggs.eggs()
   86     print "gcOther.eggs: ",gc.gcOtherEggs.eggs()
   87     print "gc.myColor: ",gc.gcColor
   88     print "gc.gcStr: ",gc.gcStr
   89     print "done"

3 Running the example

Running this example should produce output similar to below:
[joel@banzai playground1]$ python components1.py 
c.eggs:  othereggs 
c.spam:  spam 
c.cStr:  simple-c! 
gc.spam:  spam 
gc.eggs:  eggs 
gcOther.eggs:  othereggs 
gc.myColor:  red 
gc.gcStr:  simple-c! 
done 

--Joel Boehland

4 Discussion

So, it seems to me:

    1 class SimpleCmp(binding.Component):
    2     __eggs = binding.Make(Eggs, offerAs=[IEggs, EGGS_PROPERTY])

This means: "When you make a ?SimpleCmp, it has within it a variable __eggs. __eggs is an Eggs. When someone asks for the ?SimpleCmp's IEggs interface, patch it through to my internal __eggs. And when they ask for the ?SimpleCmp's EGGS_PROPERTY, also patch them through to my internal __eggs."

It also seems that: If a component has another component within it, that if the child component requests an interface, it firsts check locally for it, and if it's not found locally, it checks it's parent for it. And if not there, still higher up the chain (grandparent.)

Am I understanding right?

Next, I naturally wonder: "What for? What kinds of things do you get from this?" I'm not saying there isn't, I'm just not used to thinking this way. I'd like to get excited about it, by understanding what it can do for me.

-- ?LionKimbro 2005-04-17 14:58:41

I think it is done to have a flexible InversionOfControl mechanism. That is the wiring between elements is made "magicaly". It's very flexible since you can change a piece with another without worrying to change the code of objects using it or an object doesn't have to know which object uses it.

-- AlexG 2005-05-12 15:30:00