[Checkins] SVN: hurry.custom/trunk/src/hurry/custom/ Provide a general update mechanism for databases. It's nicer for UI

[Martijn Faassen]

Log message for revision 99728:
  Provide a general update mechanism for databases. It's nicer for UI
  builders if such exists.
  

Changed:
  U   hurry.custom/trunk/src/hurry/custom/README.txt
  U   hurry.custom/trunk/src/hurry/custom/core.py
  U   hurry.custom/trunk/src/hurry/custom/interfaces.py

-=-
Modified: hurry.custom/trunk/src/hurry/custom/README.txt
===================================================================
--- hurry.custom/trunk/src/hurry/custom/README.txt	2009-05-04 17:13:23 UTC (rev 99727)
+++ hurry.custom/trunk/src/hurry/custom/README.txt	2009-05-04 17:13:53 UTC (rev 99728)
@@ -167,6 +167,13 @@
 Customization database
 ----------------------
 
+So far all our work was done in the root (filesystem) database. We can
+get it now::
+
+  >>> from zope import component
+  >>> from hurry.custom.interfaces import ITemplateDatabase
+  >>> root_db = component.getUtility(ITemplateDatabase, name='templates')
+
 Let's now register a customization database for our collection, in a
 particular site. This means in such a site, the new customized
 template database will be used (with a fallback on the original one if
@@ -180,7 +187,6 @@
 ``templates``. For the purposes of testing we will use an in-memory
 database::
 
-  >>> from hurry.custom.interfaces import ITemplateDatabase
   >>> mem_db = custom.InMemoryTemplateDatabase('templates', 'Templates')
   >>> sm1 = site1.getSiteManager()
   >>> sm1.registerUtility(mem_db, provided=ITemplateDatabase, 
@@ -204,19 +210,31 @@
 Now that we have a locally set up customization database, we can
 customize the ``test1.st`` template. 
 
-In this customization we change 'Bye' to 'Goodbye'. For now, ``hurry.custom``
-does not yet specify a database-agnostic update mechanism, so 
-we will use the update mechanism that is particular to the in-memory
-database::
+In this customization we change 'Bye' to 'Goodbye'::
 
   >>> source = template.source
   >>> source = source.replace('Bye', 'Goodbye')
+
+We now need to update the database so that it has this customized
+version of the template. We do this by calling the ``update`` method
+on the database with the template id and the new source.
+
+This update operation is not supported on the default filesystem
+database::
+
+   >>> root_db.update('test1.st', source)
+   Traceback (most recent call last):
+     ...
+   NotSupported: Cannot update templates in FilesystemTemplateDatabase.
+
+It is supported on the site-local in-memory database we've just
+installed though::
+
   >>> mem_db.update('test1.st', source)
 
-Another database might have an entirely different storage and update
-mechanism; this is just an example. All you need to do to hook in your
-own database is to implement the ``ITemplateDatabase`` interface and
-register it (either globally or locally in a site).
+All you need to do to hook in your own database is to implement the
+``ITemplateDatabase`` interface and register it (either globally or
+locally in a site).
 
 Let's see whether we get the customized template now::
 

Modified: hurry.custom/trunk/src/hurry/custom/core.py
===================================================================
--- hurry.custom/trunk/src/hurry/custom/core.py	2009-05-04 17:13:23 UTC (rev 99727)
+++ hurry.custom/trunk/src/hurry/custom/core.py	2009-05-04 17:13:53 UTC (rev 99728)
@@ -2,6 +2,7 @@
 from datetime import datetime
 from zope.interface import implements
 from zope import component
+from hurry.custom.interfaces import NotSupported
 from hurry.custom.interfaces import (
     ITemplate, IManagedTemplate, ITemplateDatabase, IDataLanguage,
     ISampleExtension)
@@ -67,7 +68,7 @@
         if mtime > self._last_updated:
             self._last_updated = mtime
             self.load()
-    
+
     @property
     def source(self):
         self.check()
@@ -131,6 +132,10 @@
             result[name] = parse(data)
         return result
 
+    def update(self, template_id, source):
+        raise NotSupported(
+            "Cannot update templates in FilesystemTemplateDatabase.")
+
 class InMemoryTemplateSource(object):
     def __init__(self, source):
         self.source = source

Modified: hurry.custom/trunk/src/hurry/custom/interfaces.py
===================================================================
--- hurry.custom/trunk/src/hurry/custom/interfaces.py	2009-05-04 17:13:23 UTC (rev 99727)
+++ hurry.custom/trunk/src/hurry/custom/interfaces.py	2009-05-04 17:13:53 UTC (rev 99728)
@@ -99,7 +99,7 @@
     def load():
         """Load the template from the filesystem.
         """
-
+    
     def samples():
         """Get samples.
 
@@ -109,12 +109,25 @@
         values are the actual template-language native data structures.
         """
 
+class NotSupported(Exception):
+    pass
+
 class ITemplateDatabase(Interface):
     """A per-collection template database.
     """
     id = Attribute("The id of the collection")
     title = Attribute("The title of the collection")
-    
+
+    def update(template_id, source):
+        """Update the source for a given template.
+
+        Updates the source and modification time for the template with
+        that id.
+
+        If this operation is not supported, a NotSupported error is
+        raised.
+        """
+
     def get_source(template_id):
         """Get the source of a given template.