From b43695b23d08aeb1b8f56a490758a3a3f49712a7 Mon Sep 17 00:00:00 2001
From: Chris Jones <cmsj@tenshu.net>
Date: Fri, 9 Oct 2009 12:25:06 +0100
Subject: [PATCH] Flesh out the borg a little

---
 terminatorlib/borg.py | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

diff --git a/terminatorlib/borg.py b/terminatorlib/borg.py
index 6b65cd53..dc3d17bf 100755
--- a/terminatorlib/borg.py
+++ b/terminatorlib/borg.py
@@ -6,9 +6,38 @@
 
 # pylint: disable-msg=R0903
 class Borg:
-    """Definition of a class that can never be duplicated"""
+    """Definition of a class that can never be duplicated. Correct usage is
+    thus:
+        
+        from borg import Borg
+        class foo(Borg):
+            # All attributes on a borg class *must* = None
+            attribute = None
+
+            def __init__(self):
+                Borg.__init__(self)
+
+            def prepare_attributes(self):
+                if not self.attribute:
+                    self.attribute = []
+
+        bar = foo()
+        bar.prepare_attributes()
+    
+    The important thing to note is that all attributes of borg classes *must* be
+    declared as being None. If you attempt to use static class attributes you
+    will get unpredicted behaviour. Instead, prepare_attributes() must be called
+    which will then see the attributes in the shared state, and initialise them
+    if necessary."""
     __shared_state = {} 
+
     def __init__(self):
+        """Class initialiser. Overwrite our class dictionary with the shared
+        state. This makes us identical to every other instance of this class
+        type."""
         self.__dict__ = self.__shared_state
 
-# vim: set expandtab ts=4 sw=4:
+    def prepare_attributes(self):
+        """This should be used to prepare any attributes of the borg class."""
+        raise NotImplementedError('prepare_attributes')
+