Merge lp:~thekorn/zeitgeist/zeitgeist-resonance_extensions into lp:zeitgeist/0.1

[Markus Korn]

[Markus Korn (thekorn)]

This branch fixes bug 483556 by adding a framework to load extensions to ZeitgeistEngine.
Extension methods are accessible as
  engine.extensions.some_method_name()
For now there is one such extension (RelevancyProvider) which is not loaded by default. See test/test-engine-extension.rst [0] for more information how this framework is working.

[0] http://bazaar.launchpad.net/~thekorn/zeitgeist/zeitgeist-resonance_extensions/annotate/head%3A/test/test-engine-extension.rst

=== added file '_zeitgeist/engine/extension.py'
--- _zeitgeist/engine/extension.py	1970-01-01 00:00:00 +0000
+++ _zeitgeist/engine/extension.py	2009-11-23 08:25:19 +0000
@@ -0,0 +1,82 @@
+# -.- coding: utf-8 -.-
+
+# Zeitgeist
+#
+# Copyright © 2009 Markus Korn <[e-mail]>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+class Extension(object):
+	""" Base class for all extensions
+	
+	Every extension has to define a list of accessible methods as
+	'PUBLIC_METHODS'. The constructor of an Extension object takes the
+	engine object it extends as the only argument
+	"""
+	PUBLIC_METHODS = None
+	
+	def __init__(self, engine):
+		self.engine = engine
+	
+	
+class ExtensionsCollection(object):
+	""" Collection to manage all extensions """
+	
+	def __init__(self, engine, defaults=None):
+		self.__extensions = dict()
+		self.__engine = engine
+		self.__methods = dict()
+		if defaults is not None:
+			for extension in defaults:
+				self.load(extension)
+				
+	def __repr__(self):
+		return "%s(%r)" %(self.__class__.__name__, sorted(self.__methods.keys()))
+			
+	def load(self, extension):
+		if not issubclass(extension, Extension):
+			raise TypeError(
+				"Unable to load %r, all extensions have to be subclasses of %r" %(extension, Extension)
+			)
+		if getattr(extension, "PUBLIC_METHODS", None) is None:
+			raise ValueError("Unable to load %r, this extension has not defined any methods" %extension)
+		obj = extension(self.__engine)
+		for method in obj.PUBLIC_METHODS:
+			self._register_method(method, getattr(obj, method))
+		self.__extensions[obj.__class__.__name__] = obj
+		
+	def unload(self, extension):
+		obj = self.__extensions[extension.__name__]
+		for method in obj.PUBLIC_METHODS:
+			del self.methods[method]
+		del self.__extensions[extension.__name__]
+		
+	def __len__(self):
+		return len(self.__extensions)
+		
+	@property
+	def methods(self):
+		return self.__methods
+		
+	def _register_method(self, name, method):
+		if name in self.methods:
+			raise ValueError("There is already an extension which provides a method called %r" %name)
+		self.methods[name] = method
+		
+	def __getattr__(self, name):
+		try:
+			return self.methods[name]
+		except KeyError:
+			raise AttributeError("%s instance has no attribute %r" %(self.__class__.__name__, name))
+	

=== modified file '_zeitgeist/engine/relevancy_provider.py'
--- _zeitgeist/engine/relevancy_provider.py	2009-11-16 22:05:31 +0000
+++ _zeitgeist/engine/relevancy_provider.py	2009-11-23 08:25:19 +0000
@@ -27,6 +27,8 @@
 from dbutils import *
 from __init__ import DB_PATH
 
+from extension import Extension
+
 class FocusSwitchRegister(object):
     
     def __init__(self, cursor):
@@ -235,3 +237,35 @@
         for row in self.cursor:
             apps.append(self.app_table.lookup_by_id(row[0]))
         return apps
+
+class RelevancyProvider(Extension):
+    PUBLIC_METHODS = [
+        "get_subject_focus_duration",
+        "get_actor_focus_duration",
+        "get_longest_used_actors",
+        "get_longest_used_subjects",
+        "register_focus"
+    ]
+    
+    def __init__(self, engine):
+        super(RelevancyProvider, self).__init__(engine)
+        self.focus_vertices = FocusSwitchRegister(self.engine._cursor)
+        self.focus_duration = FocusDurationRegister(self.engine._cursor)
+
+    def get_subject_focus_duration(self, subject, start, end):
+        return self.focus_duration.get_subject_focus_duration(subject, start, end)
+
+    def get_actor_focus_duration(self, actor, start, end):
+        return self.focus_duration.get_actor_focus_duration(actor, start, end)
+
+    def get_longest_used_actors(self, number, start, end):
+        return self.focus_duration.get_longest_used_actors(number, start, end)
+
+    def get_longest_used_subjects(self, number, start, end):
+        return self.focus_duration.get_longest_used_subjects(number, start, end)
+
+    def register_focus(self, actor, subject):
+        now = time.time()
+        self.focus_duration.focus_change(now, actor, subject)
+        self.focus_vertices.focus_change(now, actor, subject)
+    

=== modified file '_zeitgeist/engine/resonance_engine.py'
--- _zeitgeist/engine/resonance_engine.py	2009-11-19 14:22:14 +0000
+++ _zeitgeist/engine/resonance_engine.py	2009-11-23 08:25:19 +0000
@@ -30,13 +30,14 @@
 from xdg import BaseDirectory
 from xdg.DesktopEntry import DesktopEntry
 
+from extension import ExtensionsCollection
+
 from zeitgeist.datamodel import Subject as _Subject, Event as _Event
 from zeitgeist.datamodel import Interpretation, Manifestation, Mimetype, Category, StorageState, TimeRange
 import _zeitgeist.engine
 from _zeitgeist.engine.dbutils import *
 from _zeitgeist.engine.querymancer import *
 from _zeitgeist.lrucache import *
-from _zeitgeist.engine.relevancy_provider import FocusSwitchRegister, FocusDurationRegister
 
 logging.basicConfig(level=logging.DEBUG)
 log = logging.getLogger("zeitgeist.engine")
@@ -373,7 +374,6 @@
 		global _event
 		self._cursor = get_default_cursor()
 		
-		#Load extensions
 		# Find the last event id we used, and start generating
 		# new ids from that offset
 		row = _event.find("max(id)").fetchone()
@@ -381,9 +381,14 @@
 			self._last_event_id = row[0]
 		else:
 			self._last_event_id = 0
-	
-		self.focus_switch = FocusSwitchRegister(_cursor)
-		self.focus_duration = FocusDurationRegister(_cursor)
+			
+		#Load extensions
+		# right now we don't load any default extension
+		self.__extensions = ExtensionsCollection(self)
+			
+	@property
+	def extensions(self):
+		return self.__extensions
 		
 	def close(self):
 		global _cursor
@@ -603,23 +608,7 @@
 			ORDER BY timestamp DESC LIMIT 1
 			""", (actor,)).fetchone()
 		return query["timestamp"] if query else 0
-
-	def get_subject_focus_duration(self, subject, start, end):
-		return self.focus_duration.get_subject_focus_duration(subject, start, end)
-
-	def get_actor_focus_duration(self, actor, start, end):
-		return self.focus_duration.get_actor_focus_duration(actor, start, end)
-
-	def get_longest_used_actors(self, number, start, end):
-		return self.focus_duration.get_longest_used_actors(number, start, end)
-
-	def get_longest_used_subjects(self, number, start, end):
-		return self.focus_duration.get_longest_used_subjects(number, start, end)
-
-	def register_focus(self, actor, subject):
-		now = time.time()
-		self.focus_duration.focus_change(now, actor, subject)
-		self.focus_switch.focus_change(now, actor, subject)
+		
 
 class WhereClause:
 	

=== added file 'test/resonance-engine-extension-test.py'
--- test/resonance-engine-extension-test.py	1970-01-01 00:00:00 +0000
+++ test/resonance-engine-extension-test.py	2009-11-23 08:25:19 +0000
@@ -0,0 +1,39 @@
+#!/usr/bin/python
+# -.- coding: utf-8 -.-
+
+# Update python path to use local zeitgeist module
+import sys
+import os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from _zeitgeist.engine.resonance_engine import ZeitgeistEngine
+from _zeitgeist.engine.extension import Extension
+
+import unittest
+
+class _Extension1(Extension):
+	PUBLIC_METHODS = ["return_hallo", "return_engine"]
+		
+	def return_hallo(self):
+		return "Hallo"
+		
+	def return_boo(self):
+		return "boo"
+		
+	def return_engine(self):
+		return self.engine
+	
+
+class TestExtensions(unittest.TestCase):
+	
+	def testCreateEngine(self):
+		engine = ZeitgeistEngine()
+		self.assertEqual(len(engine.extensions), 0)
+		self.assertRaises(AttributeError, engine.extensions.__getattr__, "return_hallo")
+		engine.extensions.load(_Extension1)
+		self.assertEqual(engine.extensions.return_hallo(), "Hallo")
+		self.assertRaises(AttributeError, engine.extensions.__getattr__, "return_boo")
+		self.assertEqual(engine.extensions.return_engine(), engine)
+
+if __name__ == "__main__":
+	unittest.main()

=== modified file 'test/resonance-engine-test.py'
--- test/resonance-engine-test.py	2009-11-19 14:22:14 +0000
+++ test/resonance-engine-test.py	2009-11-23 08:25:19 +0000
@@ -9,6 +9,7 @@
 import _zeitgeist.engine
 from _zeitgeist.engine import create_engine
 from zeitgeist.datamodel import *
+from _zeitgeist.engine.relevancy_provider import RelevancyProvider
 from testutils import import_events
 
 import unittest
@@ -335,8 +336,12 @@
 		
 class ZeitgeistRelevancyProviderTest(_engineTestClass):
 	
+	def setUp(self):
+		super(ZeitgeistRelevancyProviderTest, self).setUp()
+		self.engine.extensions.load(RelevancyProvider)
+	
 	def testInsertFocusEvent(self):
-		self.engine.register_focus("boo","boo")
+		self.engine.extensions.register_focus("boo","boo")
 		#self.assertRaises(ValueError, self.engine.insert_events, [ev])
 
 if __name__ == "__main__":

=== added file 'test/test-engine-extension.rst'
--- test/test-engine-extension.rst	1970-01-01 00:00:00 +0000
+++ test/test-engine-extension.rst	2009-11-23 08:25:19 +0000
@@ -0,0 +1,104 @@
+How do extensions to the engine work?
+=====================================
+
+Extensions are objects which are maintained in external python modules
+with optional methods which are accessible from a ZeitgeistEngine object.
+There is only one extension right now called RelevancyProvider, which
+is not enable by default (for now).
+
+Per default there is no extension enabled
+
+    >>> from _zeitgeist.engine.resonance_engine import ZeitgeistEngine
+    >>> engine = ZeitgeistEngine()
+    >>> len(engine.extensions)
+    0
+    
+To create a new extension you have to subclass the Extension class and
+provide a list of accessible methods in PUBLIC_METHODS
+
+    >>> from _zeitgeist.engine.extension import Extension
+    >>> class SampleExtension(Extension):
+    ...     PUBLIC_METHODS = ["add_value", "get_engine"]
+    ...
+    ...     def __init__(self, engine):
+    ...         super(SampleExtension, self).__init__(engine)
+    ...         self.counter = 0
+    ...
+    ...     def add_value(self, value):
+    ...         self.counter += value
+    ...         return self.counter
+    ...
+    ...     def get_engine(self):
+    ...         return self.engine
+    ...
+    ...     def internal_method(self):
+    ...         return 0
+    ...
+    
+This example adds to new methods to the engine 'add_value' and 'get_engine'.
+On the other hand the method called 'internal_method' is not available as
+a method of the engine object. The constructor of an Extension object takes
+one parameter, the engine object. Per default this engine object is accessible
+as the 'engine' attribute of the extension object, like 'self.engine'.
+Now we have to load this extension to the engine
+
+    >>> engine.extensions.load(SampleExtension)
+    >>> len(engine.extensions)
+    1
+    >>> print engine.extensions
+    ExtensionsCollection(['add_value', 'get_engine'])
+    >>> sorted(engine.extensions.methods)
+    ['add_value', 'get_engine']
+    
+In the last line you can see all method which are added to the engine by
+an extension.
+This methods are now accessible like
+
+    >>> engine.extensions.add_value(5)
+    5
+    >>> engine.extensions.add_value(1)
+    6
+    >>> engine.extensions.get_engine() # doctest:+ELLIPSIS
+    <_zeitgeist.engine.resonance_engine.ZeitgeistEngine instance at 0x...>
+
+However, there is also a private method which is not accessible as a member
+of the engine
+
+    >>> engine.extensions.internal_method()
+    Traceback (most recent call last):
+      ...
+    AttributeError: ExtensionsCollection instance has no attribute 'internal_method'
+
+It is also possible to unload an extension
+
+    >>> engine.extensions.unload(SampleExtension)
+    >>> sorted(engine.extensions.methods)
+    []
+
+Now its methods are not accessible anymore
+
+    >>> engine.extensions.add_value(5)
+    Traceback (most recent call last):
+      ...
+    AttributeError: ExtensionsCollection instance has no attribute 'add_value'
+
+If you try to load an extension which is not a subclass if `Extension` a
+TypeError is raised
+
+    >>> engine.extensions.load(set) # doctest:+ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    TypeError: Unable to load <type 'set'>, all extensions have to be subclasses of <...Extension'>
+
+Also, if an extension does not define any public method a ValueErro is raised
+
+    >>> class FailExtension(Extension):
+    ...
+    ...     def get_boo(self):
+    ...         return "boo"
+    ...
+    >>> engine.extensions.load(FailExtension) # doctest:+ELLIPSIS
+    Traceback (most recent call last):
+      ...
+    ValueError: Unable to load <...FailExtension'>, this extension has not defined any methods
+