- mega example cleanup

- added READMEs to all examples in each __init__.py and added to sphinx documentation
- added versioning example
- removed vertical/vertical.py, the dictlikes are more straightforward

3 files changed, 479 insertions, 0 deletions

diff --git a/examples/versioning/__init__.py b/examples/versioning/__init__.py
new file mode 100644
index 000000000..f0e1cf543
--- /dev/null
+++ b/examples/versioning/__init__.py
@@ -0,0 +1,67 @@
+"""
+Illustrates an extension which creates version tables for entities and stores records for each change.  The same idea as Elixir's versioned extension, but more efficient (uses attribute API to get history) and handles class inheritance.  The given extensions generate an anonymous "history" class which represents historical versions of the target object.   
+
+Usage is illustrated via a unit test module ``test_versioning.py``, which can be run via nose::
+
+    nosetests -w examples/versioning/
+
+A fragment of example usage, using declarative::
+
+    from history_meta import VersionedMeta, VersionedListener
+
+    Base = declarative_base(metaclass=VersionedMeta, bind=engine)
+    Session = sessionmaker(extension=VersionedListener())
+
+    class SomeClass(Base):
+        __tablename__ = 'sometable'
+    
+        id = Column(Integer, primary_key=True)
+        name = Column(String(50))
+    
+        def __eq__(self, other):
+            assert type(other) is SomeClass and other.id == self.id
+        
+    sess = Session()
+    sc = SomeClass(name='sc1')
+    sess.add(sc)
+    sess.commit()
+
+    sc.name = 'sc1modified'
+    sess.commit()
+
+    assert sc.version == 2
+
+    SomeClassHistory = SomeClass.__history_mapper__.class_
+
+    assert sess.query(SomeClassHistory).\\
+                filter(SomeClassHistory.version == 1).\\
+                all() \\
+                == [SomeClassHistory(version=1, name='sc1')]
+
+To apply ``VersionedMeta`` to a subset of classes (probably more typical), the metaclass can be applied on a per-class basis::
+
+    from history_meta import VersionedMeta, VersionedListener
+
+    Base = declarative_base(bind=engine)
+
+    class SomeClass(Base):
+        __tablename__ = 'sometable'
+
+        # ...
+
+    class SomeVersionedClass(Base):
+        __metaclass__ = VersionedMeta
+        __tablename__ = 'someothertable'
+
+        # ...
+
+The ``VersionedMeta`` is a declarative metaclass - to use the extension with plain mappers, the ``_history_mapper`` function can be applied::
+
+    from history_meta import _history_mapper
+
+    m = mapper(SomeClass, sometable)
+    _history_mapper(m)
+
+    SomeHistoryClass = SomeClass.__history_mapper__.class_
+
+"""
\ No newline at end of file
diff --git a/examples/versioning/history_meta.py b/examples/versioning/history_meta.py
new file mode 100644
index 000000000..8a916791c
--- /dev/null
+++ b/examples/versioning/history_meta.py
@@ -0,0 +1,164 @@
+from sqlalchemy.ext.declarative import DeclarativeMeta
+from sqlalchemy.orm import mapper, class_mapper, attributes, object_mapper
+from sqlalchemy.orm.exc import UnmappedClassError, UnmappedColumnError
+from sqlalchemy import Table, Column, ForeignKeyConstraint, Integer
+from sqlalchemy.orm.interfaces import SessionExtension
+
+def col_references_table(col, table):
+    for fk in col.foreign_keys:
+        if fk.references(table):
+            return True
+    return False
+
+def _history_mapper(local_mapper):
+    cls = local_mapper.class_
+
+    # SLIGHT SQLA HACK #1 - set the "active_history" flag
+    # on on column-mapped attributes so that the old version
+    # of the info is always loaded (currently sets it on all attributes)
+    for prop in local_mapper.iterate_properties:
+        getattr(local_mapper.class_, prop.key).impl.active_history = True
+    
+    super_mapper = local_mapper.inherits
+    super_history_mapper = getattr(cls, '__history_mapper__', None)
+    
+    polymorphic_on = None
+    super_fks = []
+    if not super_mapper or local_mapper.local_table is not super_mapper.local_table:
+        cols = []
+        for column in local_mapper.local_table.c:
+            if column.name == 'version':
+                continue
+                
+            col = column.copy()
+
+            if super_mapper and col_references_table(column, super_mapper.local_table):
+                super_fks.append((col.key, list(super_history_mapper.base_mapper.local_table.primary_key)[0]))
+
+            cols.append(col)
+            
+            if column is local_mapper.polymorphic_on:
+                polymorphic_on = col
+        
+        if super_mapper:
+            super_fks.append(('version', super_history_mapper.base_mapper.local_table.c.version))
+            cols.append(Column('version', Integer, primary_key=True))
+        else:
+            cols.append(Column('version', Integer, primary_key=True))
+        
+        if super_fks:
+            cols.append(ForeignKeyConstraint(*zip(*super_fks)))
+
+        table = Table(local_mapper.local_table.name + '_history', local_mapper.local_table.metadata,
+           *cols
+        )
+    else:
+        # single table inheritance.  take any additional columns that may have
+        # been added and add them to the history table.
+        for column in local_mapper.local_table.c:
+            if column.key not in super_history_mapper.local_table.c:
+                col = column.copy()
+                super_history_mapper.local_table.append_column(col)
+        table = None
+        
+    if super_history_mapper:
+        bases = (super_history_mapper.class_,)
+    else:
+        bases = local_mapper.base_mapper.class_.__bases__
+    versioned_cls = type.__new__(type, "%sHistory" % cls.__name__, bases, {})
+    
+    m = mapper(
+            versioned_cls, 
+            table, 
+            inherits=super_history_mapper, 
+            polymorphic_on=polymorphic_on,
+            polymorphic_identity=local_mapper.polymorphic_identity
+            )
+    cls.__history_mapper__ = m
+    
+    if not super_history_mapper:
+        cls.version = Column('version', Integer, default=1, nullable=False)
+    
+    
+class VersionedMeta(DeclarativeMeta):
+    def __init__(cls, classname, bases, dict_):
+        DeclarativeMeta.__init__(cls, classname, bases, dict_)
+
+        try:
+            mapper = class_mapper(cls)
+            _history_mapper(mapper)
+        except UnmappedClassError:
+            pass
+
+
+def versioned_objects(iter):
+    for obj in iter:
+        if hasattr(obj, '__history_mapper__'):
+            yield obj
+
+def create_version(obj, session, deleted = False):
+    obj_mapper = object_mapper(obj)
+    history_mapper = obj.__history_mapper__
+    history_cls = history_mapper.class_
+    
+    obj_state = attributes.instance_state(obj)
+    
+    attr = {}
+
+    obj_changed = False
+    
+    for om, hm in zip(obj_mapper.iterate_to_root(), history_mapper.iterate_to_root()):
+        if hm.single:
+            continue
+    
+        for hist_col in hm.local_table.c:
+            if hist_col.key == 'version':
+                continue
+                
+            obj_col = om.local_table.c[hist_col.key]
+
+            # SLIGHT SQLA HACK #3 - get the value of the
+            # attribute based on the MapperProperty related to the
+            # mapped column.  this will allow usage of MapperProperties
+            # that have a different keyname than that of the mapped column.
+            try:
+                prop = obj_mapper._get_col_to_prop(obj_col)
+            except UnmappedColumnError:
+                # in the case of single table inheritance, there may be 
+                # columns on the mapped table intended for the subclass only.
+                # the "unmapped" status of the subclass column on the 
+                # base class is a feature of the declarative module as of sqla 0.5.2.
+                continue
+                
+            # expired object attributes and also deferred cols might not be in the
+            # dict.  force it to load no matter what by using getattr().
+            if prop.key not in obj_state.dict:
+                getattr(obj, prop.key)
+
+            a, u, d = attributes.get_history(obj, prop.key)
+
+            if d:
+                attr[hist_col.key] = d[0]
+                obj_changed = True
+            elif u:
+                attr[hist_col.key] = u[0]
+            else:
+                raise Exception("TODO: what makes us arrive here ?")
+                
+    if not obj_changed and not deleted:            
+        return
+
+    attr['version'] = obj.version
+    hist = history_cls()
+    for key, value in attr.iteritems():
+        setattr(hist, key, value)
+    session.add(hist)
+    obj.version += 1
+    
+class VersionedListener(SessionExtension):
+    def before_flush(self, session, flush_context, instances):
+        for obj in versioned_objects(session.dirty):
+            create_version(obj, session)
+        for obj in versioned_objects(session.deleted):
+            create_version(obj, session, deleted = True)
+            
diff --git a/examples/versioning/test_versioning.py b/examples/versioning/test_versioning.py
new file mode 100644
index 000000000..1a72a0659
--- /dev/null
+++ b/examples/versioning/test_versioning.py
@@ -0,0 +1,248 @@
+from sqlalchemy.ext.declarative import declarative_base
+from history_meta import VersionedMeta, VersionedListener
+from sqlalchemy import create_engine, Column, Integer, String, ForeignKey
+from sqlalchemy.orm import clear_mappers, compile_mappers, sessionmaker, deferred
+from sqlalchemy.test.testing import TestBase, eq_
+from sqlalchemy.test.entities import ComparableEntity
+
+def setup():
+    global engine
+    engine = create_engine('sqlite://', echo=True)
+    
+class TestVersioning(TestBase):
+    def setup(self):
+        global Base, Session
+        Base = declarative_base(metaclass=VersionedMeta, bind=engine)
+        Session = sessionmaker(extension=VersionedListener())
+        
+    def teardown(self):
+        clear_mappers()
+        Base.metadata.drop_all()
+    
+    def create_tables(self):
+        Base.metadata.create_all()
+        
+    def test_plain(self):
+        class SomeClass(Base, ComparableEntity):
+            __tablename__ = 'sometable'
+            
+            id = Column(Integer, primary_key=True)
+            name = Column(String(50))
+        
+        self.create_tables()
+        sess = Session()
+        sc = SomeClass(name='sc1')
+        sess.add(sc)
+        sess.commit()
+        
+        sc.name = 'sc1modified'
+        sess.commit()
+        
+        assert sc.version == 2
+        
+        SomeClassHistory = SomeClass.__history_mapper__.class_
+        
+        eq_(
+            sess.query(SomeClassHistory).filter(SomeClassHistory.version == 1).all(),
+            [SomeClassHistory(version=1, name='sc1')]
+        )
+
+        sc.name = 'sc1modified2'
+
+        eq_(
+            sess.query(SomeClassHistory).order_by(SomeClassHistory.version).all(),
+            [
+                SomeClassHistory(version=1, name='sc1'),
+                SomeClassHistory(version=2, name='sc1modified')
+            ]
+        )
+
+        assert sc.version == 3
+        
+        sess.commit()
+
+        sc.name = 'temp'
+        sc.name = 'sc1modified2'
+
+        sess.commit()
+
+        eq_(
+            sess.query(SomeClassHistory).order_by(SomeClassHistory.version).all(),
+            [
+                SomeClassHistory(version=1, name='sc1'),
+                SomeClassHistory(version=2, name='sc1modified')
+            ]
+        )
+        
+        sess.delete(sc)
+        sess.commit()
+
+        eq_(
+            sess.query(SomeClassHistory).order_by(SomeClassHistory.version).all(),
+            [
+                SomeClassHistory(version=1, name='sc1'),
+                SomeClassHistory(version=2, name='sc1modified'),
+                SomeClassHistory(version=3, name='sc1modified2')
+            ]
+        )
+
+
+
+
+    def test_deferred(self):
+        """test versioning of unloaded, deferred columns."""
+        
+        class SomeClass(Base, ComparableEntity):
+            __tablename__ = 'sometable'
+
+            id = Column(Integer, primary_key=True)
+            name = Column(String(50))
+            data = deferred(Column(String(25)))
+            
+        self.create_tables()
+        sess = Session()
+        sc = SomeClass(name='sc1', data='somedata')
+        sess.add(sc)
+        sess.commit()
+        sess.close()
+        
+        sc = sess.query(SomeClass).first()
+        assert 'data' not in sc.__dict__
+        
+        sc.name = 'sc1modified'
+        sess.commit()
+
+        assert sc.version == 2
+
+        SomeClassHistory = SomeClass.__history_mapper__.class_
+
+        eq_(
+            sess.query(SomeClassHistory).filter(SomeClassHistory.version == 1).all(),
+            [SomeClassHistory(version=1, name='sc1', data='somedata')]
+        )
+        
+        
+    def test_joined_inheritance(self):
+        class BaseClass(Base, ComparableEntity):
+            __tablename__ = 'basetable'
+
+            id = Column(Integer, primary_key=True)
+            name = Column(String(50))
+            type = Column(String(20))
+            
+            __mapper_args__ = {'polymorphic_on':type, 'polymorphic_identity':'base'}
+            
+        class SubClassSeparatePk(BaseClass):
+            __tablename__ = 'subtable1'
+
+            id = Column(Integer, primary_key=True)
+            base_id = Column(Integer, ForeignKey('basetable.id'))
+            subdata1 = Column(String(50))
+
+            __mapper_args__ = {'polymorphic_identity':'sep'}
+
+        class SubClassSamePk(BaseClass):
+            __tablename__ = 'subtable2'
+
+            id = Column(Integer, ForeignKey('basetable.id'), primary_key=True)
+            subdata2 = Column(String(50))
+
+            __mapper_args__ = {'polymorphic_identity':'same'}
+
+        self.create_tables()
+        sess = Session()
+
+        sep1 = SubClassSeparatePk(name='sep1', subdata1='sep1subdata')
+        base1 = BaseClass(name='base1')
+        same1 = SubClassSamePk(name='same1', subdata2='same1subdata')
+        sess.add_all([sep1, base1, same1])
+        sess.commit()
+        
+        base1.name = 'base1mod'
+        same1.subdata2 = 'same1subdatamod'
+        sep1.name ='sep1mod'
+        sess.commit()
+
+        BaseClassHistory = BaseClass.__history_mapper__.class_
+        SubClassSeparatePkHistory = SubClassSeparatePk.__history_mapper__.class_
+        SubClassSamePkHistory = SubClassSamePk.__history_mapper__.class_
+        eq_(
+            sess.query(BaseClassHistory).order_by(BaseClassHistory.id).all(),
+            [
+                SubClassSeparatePkHistory(id=1, name=u'sep1', type=u'sep', version=1), 
+                BaseClassHistory(id=2, name=u'base1', type=u'base', version=1), 
+                SubClassSamePkHistory(id=3, name=u'same1', type=u'same', version=1)            
+            ]
+        )
+        
+        same1.subdata2 = 'same1subdatamod2'
+
+        eq_(
+            sess.query(BaseClassHistory).order_by(BaseClassHistory.id, BaseClassHistory.version).all(),
+            [
+                SubClassSeparatePkHistory(id=1, name=u'sep1', type=u'sep', version=1), 
+                BaseClassHistory(id=2, name=u'base1', type=u'base', version=1), 
+                SubClassSamePkHistory(id=3, name=u'same1', type=u'same', version=1), 
+                SubClassSamePkHistory(id=3, name=u'same1', type=u'same', version=2)            
+            ]
+        )
+
+        base1.name = 'base1mod2'
+        eq_(
+            sess.query(BaseClassHistory).order_by(BaseClassHistory.id, BaseClassHistory.version).all(),
+            [
+                SubClassSeparatePkHistory(id=1, name=u'sep1', type=u'sep', version=1), 
+                BaseClassHistory(id=2, name=u'base1', type=u'base', version=1), 
+                BaseClassHistory(id=2, name=u'base1mod', type=u'base', version=2), 
+                SubClassSamePkHistory(id=3, name=u'same1', type=u'same', version=1), 
+                SubClassSamePkHistory(id=3, name=u'same1', type=u'same', version=2)            
+            ]
+        )
+
+    def test_single_inheritance(self):
+        class BaseClass(Base, ComparableEntity):
+            __tablename__ = 'basetable'
+
+            id = Column(Integer, primary_key=True)
+            name = Column(String(50))
+            type = Column(String(50))
+            __mapper_args__ = {'polymorphic_on':type, 'polymorphic_identity':'base'}
+            
+        class SubClass(BaseClass):
+
+            subname = Column(String(50))
+            __mapper_args__ = {'polymorphic_identity':'sub'}
+
+        self.create_tables()
+        sess = Session()
+
+        b1 = BaseClass(name='b1')
+        sc = SubClass(name='s1', subname='sc1')
+        
+        sess.add_all([b1, sc])
+        
+        sess.commit()
+        
+        b1.name='b1modified'
+
+        BaseClassHistory = BaseClass.__history_mapper__.class_
+        SubClassHistory = SubClass.__history_mapper__.class_
+        
+        eq_(
+            sess.query(BaseClassHistory).order_by(BaseClassHistory.id, BaseClassHistory.version).all(),
+            [BaseClassHistory(id=1, name=u'b1', type=u'base', version=1)]
+        )
+        
+        sc.name ='s1modified'
+        b1.name='b1modified2'
+
+        eq_(
+            sess.query(BaseClassHistory).order_by(BaseClassHistory.id, BaseClassHistory.version).all(),
+            [
+                BaseClassHistory(id=1, name=u'b1', type=u'base', version=1),
+                BaseClassHistory(id=1, name=u'b1modified', type=u'base', version=2),
+                SubClassHistory(id=2, name=u's1', type=u'sub', version=1)
+            ]
+        )
+        
+