[SQL-CVS] r2165 - SQLObject/docs

[<sub...@co...>]

Author: novalis
Date: 2006-12-28 13:55:44 -0700 (Thu, 28 Dec 2006)
New Revision: 2165

Added:
   SQLObject/docs/Versioning.txt
Log:
fixed code samples

Added: SQLObject/docs/Versioning.txt
===================================================================
--- SQLObject/docs/Versioning.txt	                        (rev 0)
+++ SQLObject/docs/Versioning.txt	2006-12-28 20:55:44 UTC (rev 2165)
@@ -0,0 +1,81 @@
+:Author: David Turner, The Open Planning Project
+
+Versioning
+-----------
+
+Why
+~~~
+
+You have a table where rows can be altered, such as a table of wiki
+pages.  You want to retain a history of changes for auditing, backup,
+or tracking purposes.  
+
+You could write a decorator that stores old versions and manage all
+access to this object through it.  Or you could take advantage of the
+event system in SQLObject 0.8+ and just catch row accesses to the
+object.  SQLObject's versioning module does this for you.  And it even
+works with inheritance!
+
+How
+~~~
+
+Here's how to set it up::
+
+    class MyClass(SQLObject):
+        name = StringCol()
+        versions = Versioning()
+
+To use it, just create an instance as usual::
+
+    mc = MyClass(name='fleem')
+
+Then make some changes and check out the results::
+
+    mc.set(name='morx')
+    assert mc.versions[0].name == 'fleem'
+
+You can also restore to a previous version::
+
+    mc.versions[0].restore()
+    assert mc.name == "fleem"
+
+Inheritance
+~~~~~~~~~~~
+
+There are three ways versioning can be used with inheritance:
+
+1. Parent versioned, children unversioned::
+
+     class Base(InheritableSQLObject):
+         name = StringCol()
+         versions = Versioning()
+
+     class Child(Base):
+         toy = StringCol()
+
+In this case, when changes are made to an instance of Base, new
+versions are created.  But when changes are made to an instance of
+Child, no new versions are created.  
+
+2. Children versioned, parents unversioned.
+
+In this case, when changes are made to an instance of Child, new
+versions are created.  But when changes are made to an instance of
+Base, no new versions are created.  The version data for Child
+contains all of the columns from child and from base, so that a full
+restore is possible.
+
+3. Both children and parents versioned.  
+
+In this case, changes to either Child or Base instances create new
+versions, but in different tables.  Child versions still contain all
+Base data, and a change to a Child only creates a new Child version, not 
+a new Base version.
+
+Version Tables
+~~~~~~~~~~~~~~
+
+Versions are stored in a special table which is created when the table
+for a versioned class is created.  Version tables are not altered when
+the main table is altered, so if you add a column to your main class,
+you will need to manually add the column to your version table.