plumber 1.2

An alternative to mixin-based extension of classes.

Interaction: finalize, plumbing declaration and base classes

In code:

>>> from plumber import finalize

>>> class Behavior1(Behavior):
...     N = finalize('Behavior1')
...

>>> class Behavior2(Behavior):
...     M = finalize('Behavior2')

>>> class Base(object):
...     K = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2
...     L = 'Plumbing'

>>> for x in ['K', 'L', 'M', 'N']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Base
L from Plumbing
M from Behavior2
N from Behavior1

summary:

• K-Q: attributes defined by behaviors, plumbing class and base classes
• f: finalize declaration
• x: declaration on plumbing class or base class
• ?: base class declaration is irrelevant
• Y: chosen end point
• collision: indicates an invalid combination, that raises a PlumbingCollision

collisions:

>>> class Behavior1(Behavior):
...     O = finalize(False)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1
...     O = True
Traceback (most recent call last):
  ...
PlumbingCollision:
    Plumbing class
  with:
    <finalize 'O' of <class 'Behavior1'> payload=False>

>>> class Behavior2(Behavior):
...     P = finalize(False)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior2
...     P = True
Traceback (most recent call last):
  ...
PlumbingCollision:
    Plumbing class
  with:
    <finalize 'P' of <class 'Behavior2'> payload=False>

>>> class Behavior1(Behavior):
...     Q = finalize(False)

>>> class Behavior2(Behavior):
...     Q = finalize(True)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2
Traceback (most recent call last):
  ...
PlumbingCollision:
    <finalize 'Q' of <class 'Behavior1'> payload=False>
  with:
    <finalize 'Q' of <class 'Behavior2'> payload=True>

Interaction: override, plumbing declaration and base classes

in code:

>>> from plumber import override

>>> class Behavior1(Behavior):
...     K = override('Behavior1')
...     M = override('Behavior1')

>>> class Behavior2(Behavior):
...     K = override('Behavior2')
...     L = override('Behavior2')
...     M = override('Behavior2')

>>> class Base(object):
...     K = 'Base'
...     L = 'Base'
...     M = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2
...     K = 'Plumbing'

>>> for x in ['K', 'L', 'M']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Plumbing
L from Behavior2
M from Behavior1

summary:

• K-M: attributes defined by behaviors, plumbing class and base classes
• e: override declaration
• x: declaration on plumbing class or base class
• ?: base class declaration is irrelevant
• Y: chosen end point

Interaction: default, plumbing declaration and base class

in code:

>>> class Behavior1(Behavior):
...     N = default('Behavior1')

>>> class Behavior2(Behavior):
...     K = default('Behavior2')
...     L = default('Behavior2')
...     M = default('Behavior2')
...     N = default('Behavior2')

>>> class Base(object):
...     K = 'Base'
...     L = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2
...     L = 'Plumbing'

>>> for x in ['K', 'L', 'M', 'N']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Base
L from Plumbing
M from Behavior2
N from Behavior1

summary:

• K-N: attributes defined by behaviors, plumbing class and base classes
• d = default declaration
• x = declaration on plumbing class or base class
• ? = base class declaration is irrelevant
• Y = chosen end point

Interaction: finalize wins over override

in code:

>>> class Behavior1(Behavior):
...     K = override('Behavior1')
...     L = finalize('Behavior1')

>>> class Behavior2(Behavior):
...     K = finalize('Behavior2')
...     L = override('Behavior2')

>>> class Base(object):
...     K = 'Base'
...     L = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2

>>> for x in ['K', 'L']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Behavior2
L from Behavior1

summary:

• K-L: attributes defined by behaviors, plumbing class and base classes
• e = override declaration
• f = finalize declaration
• ? = base class declaration is irrelevant
• Y = chosen end point

Interaction: finalize wins over default:

in code:

>>> class Behavior1(Behavior):
...     K = default('Behavior1')
...     L = finalize('Behavior1')

>>> class Behavior2(Behavior):
...     K = finalize('Behavior2')
...     L = default('Behavior2')

>>> class Base(object):
...     K = 'Base'
...     L = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2

>>> for x in ['K', 'L']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Behavior2
L from Behavior1

summary:

• K-L: attributes defined by behaviors, plumbing class and base classes
• d = default declaration
• f = finalize declaration
• ? = base class declaration is irrelevant
• Y = chosen end point

Interaction: override wins over default

in code:

>>> class Behavior1(Behavior):
...     K = default('Behavior1')
...     L = override('Behavior1')

>>> class Behavior2(Behavior):
...     K = override('Behavior2')
...     L = default('Behavior2')

>>> class Base(object):
...     K = 'Base'
...     L = 'Base'

>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2

>>> for x in ['K', 'L']:
...     print "%s from %s" % (x, getattr(Plumbing, x))
K from Behavior2
L from Behavior1

summary:

• K-L: attributes defined by behaviors, plumbing class and base classes
• d = default declaration
• e = override declaration
• ? = base class declaration is irrelevant
• Y = chosen end point

Subclassing Behaviors

in code:

>>> class Behavior1(Behavior):
...     J = default('Behavior1')
...     K = default('Behavior1')
...     M = override('Behavior1')

>>> class Behavior2(Behavior1):
...     J = default('Behavior2') # overrides ``J`` of ``Behavior1``
...     L = default('Behavior2')
...     M = default('Behavior2') # this one wins, even if ``M`` on
...                              # superclass is ``override`` instruction.
...                              # due to ordinary inheritance behavior.

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior2

>>> plb = Plumbing()
>>> plb.J
'Behavior2'

>>> plb.K
'Behavior1'

>>> plb.L
'Behavior2'

>>> plb.M
'Behavior2'

Plumbing Pipelines in general

Elements for plumbing pipelines are declared with the plumb and plumbifexists decorators:

plumb

Marks a method to be used as behavior of a plumbing pipeline. The signature of such a plumbing method is def foo(_next, self, *args, **kw). Via _next it is passed the next plumbing method to be called. self is an instance of the plumbing class, not the behavior.

plumbifexists

Like plumb, but only used if an endpoint exists.

The user of a plumbing class does not know which _next to pass. Therefore, after the pipelines are built, an entrance method is generated for each pipe, that wraps the first plumbing method passing it the correct _next. Each _next method is an entrance to the rest of the pipeline.

The pipelines are build in behavior order, skipping behaviors that do not define a pipeline element with the same attribute name:

+---+-----------+-----------+-----------+----------+
|   | Behavior1 | Behavior2 | Behavior3 | ENDPOINT |
+---+-----------+-----------+-----------+----------+
|   |      --------------------------------->      |
| E |     x     |           |           |    x     |
| N |      <---------------------------------      |
+ T +-----------+-----------+-----------+----------+
| R |      ----------> --------------------->      |
| A |     y     |     y     |           |    y     |
| N |      <---------- <---------------------      |
+ C +-----------+-----------+-----------+----------+
| E |           |           |      --------->      |
| S |           |           |     z     |    z     |
|   |           |           |      <---------      |
+---+-----------+-----------+-----------+----------+

Method pipelines

Two plumbing behaviors and a dict as base class. Behavior1 lowercases keys before passing them on, Behavior2 multiplies results before returning them:

>>> from plumber import plumb

>>> class Behavior1(Behavior):
...     @plumb
...     def __getitem__(_next, self, key):
...         print "Behavior1 start"
...         key = key.lower()
...         ret = _next(self, key)
...         print "Behavior1 stop"
...         return ret

>>> class Behavior2(Behavior):
...     @plumb
...     def __getitem__(_next, self, key):
...         print "Behavior2 start"
...         ret = 2 * _next(self, key)
...         print "Behavior2 stop"
...         return ret

>>> Base = dict
>>> class Plumbing(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2

>>> plb = Plumbing()
>>> plb['abc'] = 6
>>> plb['AbC']
Behavior1 start
Behavior2 start
Behavior2 stop
Behavior1 stop
12

Plumbing pipelines need endpoints. If no endpoint is available an AttributeError is raised:

>>> class Behavior1(Behavior):
...     @plumb
...     def foo(_next, self):
...         pass

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1
Traceback (most recent call last):
  ...
AttributeError: type object 'Plumbing' has no attribute 'foo'

If no endpoint is available and a behavior does not care about that, plumbifexists can be used to only plumb if an endpoint is available:

>>> from plumber import plumbifexists

>>> class Behavior1(Behavior):
...     @plumbifexists
...     def foo(_next, self):
...         pass
...
...     @plumbifexists
...     def bar(_next, self):
...         return 2 * _next(self)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1
...
...     def bar(self):
...         return 6

>>> hasattr(Plumbing, 'foo')
False
>>> Plumbing().bar()
12

This enables one implementation of a certain behaviour, e.g. sending events for dictionaries, to be used for readwrite dictionaries that implement __getitem__ and __setitem__ and readonly dictionaries, that only implement __getitem__ but no __setitem__.

Property pipelines

Plumbing of read only properties:

>>> class Behavior1(Behavior):
...     @plumb
...     @property
...     def foo(_next, self):
...         return 2 * _next(self)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1
...
...     @property
...     def foo(self):
...         return 3

>>> plb = Plumbing()
>>> plb.foo
6

It is possible to extend a property with so far unset getter/setter/deleter:

>>> class Behavior1(Behavior):
...     @plumb
...     @property
...     def foo(_next, self):
...         return 2 * _next(self)

>>> class Behavior2(Behavior):
...     def set_foo(self, value):
...         self._foo = value
...     foo = plumb(property(
...         None,
...         override(set_foo),
...         ))

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2
...
...     @property
...     def foo(self):
...         return self._foo

>>> plb = Plumbing()
>>> plb.foo = 4
>>> plb.foo
8

Subclassing Behaviors

Other than stage 1 instructions, which extend a class with properties and functions and thus override each other by the rules of ordinary subclassing, pipeline instructions are aggregated:

>>> class Behavior1(Behavior):
...
...     @plumb
...     def foo(_next, self):
...         return 'Behavior1 ' + _next(self)
...
...     @plumb
...     def bar(_next, self):
...         return 'Behavior1 ' + _next(self)

>>> class Behavior2(Behavior1):
...
...     @plumb
...     def foo(_next, self):
...         return 'Behavior2 ' + _next(self)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior2
...
...     def foo(self):
...         return 'foo'
...
...     def bar(self):
...         return 'bar'

>>> plb = Plumbing()
>>> plb.foo()
'Behavior2 Behavior1 foo'

>>> plb.bar()
'Behavior1 bar'

Mixing methods and properties within the same pipeline is not possible

Within a pipeline all elements need to be of the same type, it is not possible to mix properties with methods:

>>> class Behavior1(Behavior):
...     @plumb
...     def foo(_next, self):
...         return _next(self)

>>> class Plumbing(object):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1
...
...     @property
...     def foo(self):
...         return 5
Traceback (most recent call last):
  ...
PlumbingCollision:
    <plumb 'foo' of <class 'Behavior1'> payload=<function foo at 0x...>>
  with:
    <class 'Plumbing'>

docstrings of classes, methods and properties

Normal docstrings of the plumbing declaration and the behavior classes, plumbed methods and plumbed properties are joined by newlines starting with the plumbing declaration and followed by the behaviors in reverse order:

>>> class P1(Behavior):
...     """P1
...     """
...     @plumb
...     def foo(self):
...         """P1.foo
...         """
...     bar = plumb(property(None, None, None, "P1.bar"))

>>> class P2(Behavior):
...     @override
...     def foo(self):
...         """P2.foo
...         """
...     bar = plumb(property(None, None, None, "P2.bar"))

>>> class Plumbing(object):
...     """Plumbing
...     """
...     __metaclass__ = plumber
...     __plumbing__ = P1, P2
...     bar = property(None, None, None, "Plumbing.bar")

>>> print Plumbing.__doc__
Plumbing
<BLANKLINE>
P1
<BLANKLINE>

>>> print Plumbing.foo.__doc__
P2.foo
<BLANKLINE>
P1.foo
<BLANKLINE>

>>> print Plumbing.bar.__doc__
Plumbing.bar
<BLANKLINE>
P2.bar
<BLANKLINE>
P1.bar

The accumulation of docstrings is an experimental feature and will probably change.

zope.interface (if available)

The plumber does not depend on zope.interface but is aware of it. That means it will try to import it and if available will check plumbing behaviors for implemented interfaces and will make the plumbing implement them, too:

>>> from zope.interface import Interface
>>> from zope.interface import implementer

A class with an interface that will serve as base class of a plumbing:

>>> class IBase(Interface):
...     pass

>>> @implementer(IBase)
... class Base(object):
...     pass

>>> IBase.implementedBy(Base)
True

Two behaviors with corresponding interfaces, one with a base class that also implements an interface:

>>> class IBehavior1(Interface):
...     pass

>>> @implementer(IBehavior1)
... class Behavior1(Behavior):
...     blub = 1

>>> class IBehavior2Base(Interface):
...     pass

>>> @implementer(IBehavior2Base)
... class Behavior2Base(Behavior):
...     pass

>>> class IBehavior2(Interface):
...     pass

>>> @implementer(IBehavior2)
... class Behavior2(Behavior2Base):
...     pass

>>> IBehavior1.implementedBy(Behavior1)
True

>>> IBehavior2Base.implementedBy(Behavior2Base)
True

>>> IBehavior2Base.implementedBy(Behavior2)
True

>>> IBehavior2.implementedBy(Behavior2)
True

A plumbing based on Base using Behavior1 and Behavior2 and implementing IPlumbingClass:

>>> class IPlumbingClass(Interface):
...     pass

>>> @implementer(IPlumbingClass)
... class PlumbingClass(Base):
...     __metaclass__ = plumber
...     __plumbing__ = Behavior1, Behavior2

The directly declared and inherited interfaces are implemented:

>>> IPlumbingClass.implementedBy(PlumbingClass)
True

>>> IBase.implementedBy(PlumbingClass)
True

The interfaces implemented by the Behaviors are also implemented:

>>> IBehavior1.implementedBy(PlumbingClass)
True

>>> IBehavior2.implementedBy(PlumbingClass)
True

>>> IBehavior2Base.implementedBy(PlumbingClass)
True

An instance of the class provides the interfaces:

>>> plumbing = PlumbingClass()

>>> IPlumbingClass.providedBy(plumbing)
True

>>> IBase.providedBy(plumbing)
True

>>> IBehavior1.providedBy(plumbing)
True

>>> IBehavior2.providedBy(plumbing)
True

>>> IBehavior2Base.providedBy(plumbing)
True