The patterns module

The patterns module contains modules pertaining to implementing common design patterns.

The Borg class

class pyamp.patterns.Borg(*args, **kwargs)

The Borg class implements the Borg design pattern which provides a singleton like pattern for Python.

A Borg object can be accessed by calling the getInstance() function. This functions returns an instance of the Borg class which stores its state between successive calls to get the Borg object.

Instances of the Borg class can implement the init() function which is called when the Borg class is first created and initialized. This allows the concrete Borg classes to set up the initial state for their object.

Example:

class Example(Borg):
    def init(self, *args, **kwargs):
        self.x = kwargs['x']

class First:
    def __init__(self):
        # An example of passing a value to the Borg instance
        b = Example(x=200)
        print "First, b.x:", b.x

class Second:
    def __init__(self):
        # Optionally could use Borg.getInstance()
        b = Example.getInstance()
        print "Second, b.x:", b.x
        b.x = 500

if __name__ == '__main__':
    First()
    Second()

    b = Example.getInstance()
    print "Third, b.x:", b.x

    # Prints:
    #    First, b.x: 200
    #    Second, b.x: 200
    #    Third, b.x: 500

• args – The arguments
• kwargs – The keyword arguments

classmethod getInstance()

Get an instance of the Borg object.

getPrivateAttr(name, default=None)

Return the value of a private class attribute.

• name – The name of the private attribute
• default – The value returned if the attribute does not exist

init(*args, **kwargs)

This function is called the first time the class is initialized, and should be overridden by concrete subclasses.

• args – The arguments
• kwargs – The keyword arguments

setPrivateAttr(name, value)

Set the value of a private class attribute.

• name – The name of the private attribute
• value – The value to set the attribute to

The Enum class

class pyamp.patterns.Enum

The Enum class provides the ability to create a class which acts as an enumeration. Class properties can be set as the enumeration values, and a dictionary of the entire enumeration keys and values can be retrieved.

Example:

class Test(Enum):
    Prop1 = "This is a string property"
    Prop2 = 123
    Another = True
    AnyIdName = {"test": 0}
    ListId = [1, 2, 3, 4]

Calling Test.get(), returns:

{ "Prop1": "This is a string property",
  "Prop2": 123,
  "Another": True,
  "AnyIdName": {"test": 0},
  "ListId": [1, 2, 3, 4]
}

Create an Enum.

classmethod get()

Get the list of configured enumeration values.

Decorators

The following describes various functions that can be used to decorate functions to perform particular tasks.

The listProperty decorator

pyamp.patterns.listProperty(propName, values)

The listProperty function returns a decorator that appends a list of values (to the property with the given name) to a function’s attributes.

Example:

@listProperty("test", [1, "two", 3])
def example(self):
    pass

@listProperty("prop", [1])
@listProperty("prop", ["another property"])
@listProperty("prop", [True])
def example2(self):
    pass

# Prints: [1, "two", 3]
print example.test

# Prints: [1, "another property", True]
print example2.prop

• propName – The name of the property to set on the decorated function
• values – The value, or list of values, to append

Interfaces

The Interface class

class pyamp.patterns.Interface

The Interface class provides to ability to identify specific class functions to be ‘interface’ functions.

This class contains a class property called InterfaceProperty which defines the name of the property used to identify interface functions.

This class provides a interface() function which uses the InterfaceProperty property to create an implementation specific decorator which can be used to decorate functions that should identified as interface functions.

Example:

class Example(Interface):
    InterfaceProperty = "ExampleInterfaceProperty"

    @Example.interface
    def testPrint(self, message):
        print "Message:", message

This the above example the testPrint() function has been decorated and is thus an interface function.

connect(parent)

Connect to a parent’s interface methods.

Note: This should be overriden by concrete Interfaces

• parent – The parent interface object

getInterfaceFunctions()

Get a dictionary of the interface function names mapped to the actual functions.

classmethod interface(function)

A decorator for functions to make them interface functions for this Interface instance.

• function – The function to decorate

classmethod isInterface(obj)

Determine if the given object is an instance of the interface.

• obj – The object

The PassThrough class

class pyamp.patterns.PassThrough

The PassThrough Interface provides the ability for a child PassThrough object to connect functions of the same name to the parent’s Interface functions.

When a child class connects to the parent’s interface functions, all calls to the child’s interface functions are instead redirected to the parent’s functions of the same name.

Example:

class Parent(PassThrough):
    @PassThrough.interface
    def testPrint(self, message):
        print "Parent message:", message

class Child(PassThrough):
    pass

parent = Parent()
child = Child()
child.connect(parent)

# Prints:
#    "Parent message:", this is a message
child.testPrint("this is a message")

connect(parent)

Connect the child to the parent’s interface functions.

• parent – The parent Interface