- 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

4 files changed, 257 insertions, 0 deletions

diff --git a/examples/inheritance/__init__.py b/examples/inheritance/__init__.py
new file mode 100644
index 000000000..a3b85460c
--- /dev/null
+++ b/examples/inheritance/__init__.py
@@ -0,0 +1,4 @@
+"""
+Working examples of single-table, joined-table, and concrete-table inheritance as described in :ref:`datamapping_inheritance`.
+
+"""
\ No newline at end of file
diff --git a/examples/inheritance/concrete.py b/examples/inheritance/concrete.py
new file mode 100644
index 000000000..c50513b55
--- /dev/null
+++ b/examples/inheritance/concrete.py
@@ -0,0 +1,66 @@
+from sqlalchemy import create_engine, MetaData, Table, Column, Integer, String
+from sqlalchemy.orm import mapper, create_session, polymorphic_union
+
+metadata = MetaData()
+
+managers_table = Table('managers', metadata, 
+    Column('employee_id', Integer, primary_key=True),
+    Column('name', String(50)),
+    Column('manager_data', String(40))
+)
+
+engineers_table = Table('engineers', metadata, 
+    Column('employee_id', Integer, primary_key=True),
+    Column('name', String(50)),
+    Column('engineer_info', String(40))
+)
+
+engine = create_engine('sqlite:///', echo=True)
+metadata.create_all(engine)
+
+
+class Employee(object):
+    def __init__(self, name):
+        self.name = name
+    def __repr__(self):
+        return self.__class__.__name__ + " " + self.name
+        
+class Manager(Employee):
+    def __init__(self, name, manager_data):
+        self.name = name
+        self.manager_data = manager_data
+    def __repr__(self):
+        return self.__class__.__name__ + " " + self.name + " " +  self.manager_data
+    
+class Engineer(Employee):
+    def __init__(self, name, engineer_info):
+        self.name = name
+        self.engineer_info = engineer_info
+    def __repr__(self):
+        return self.__class__.__name__ + " " + self.name + " " +  self.engineer_info
+
+
+pjoin = polymorphic_union({
+    'manager':managers_table,
+    'engineer':engineers_table
+}, 'type', 'pjoin')
+
+employee_mapper = mapper(Employee, pjoin, polymorphic_on=pjoin.c.type)
+manager_mapper = mapper(Manager, managers_table, inherits=employee_mapper, concrete=True, polymorphic_identity='manager')
+engineer_mapper = mapper(Engineer, engineers_table, inherits=employee_mapper, concrete=True, polymorphic_identity='engineer')
+
+
+session = create_session(bind=engine)
+
+m1 = Manager("pointy haired boss", "manager1")
+e1 = Engineer("wally", "engineer1")
+e2 = Engineer("dilbert", "engineer2")
+
+session.add(m1)
+session.add(e1)
+session.add(e2)
+session.flush()
+
+employees = session.query(Employee)
+print [e for e in employees]
+
diff --git a/examples/inheritance/polymorph.py b/examples/inheritance/polymorph.py
new file mode 100644
index 000000000..4cf13985b
--- /dev/null
+++ b/examples/inheritance/polymorph.py
@@ -0,0 +1,101 @@
+from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
+from sqlalchemy.orm import mapper, relation, create_session
+import sets
+
+# this example illustrates a polymorphic load of two classes
+
+metadata = MetaData('sqlite://')
+metadata.bind.echo = True
+
+# a table to store companies
+companies = Table('companies', metadata, 
+   Column('company_id', Integer, primary_key=True),
+   Column('name', String(50)))
+
+# we will define an inheritance relationship between the table "people" and "engineers",
+# and a second inheritance relationship between the table "people" and "managers"
+people = Table('people', metadata, 
+   Column('person_id', Integer, primary_key=True),
+   Column('company_id', Integer, ForeignKey('companies.company_id')),
+   Column('name', String(50)),
+   Column('type', String(30)))
+   
+engineers = Table('engineers', metadata, 
+   Column('person_id', Integer, ForeignKey('people.person_id'), primary_key=True),
+   Column('status', String(30)),
+   Column('engineer_name', String(50)),
+   Column('primary_language', String(50)),
+  )
+   
+managers = Table('managers', metadata, 
+   Column('person_id', Integer, ForeignKey('people.person_id'), primary_key=True),
+   Column('status', String(30)),
+   Column('manager_name', String(50))
+   )
+   
+metadata.create_all()
+
+# create our classes.  The Engineer and Manager classes extend from Person.
+class Person(object):
+    def __init__(self, **kwargs):
+        for key, value in kwargs.iteritems():
+            setattr(self, key, value)
+    def __repr__(self):
+        return "Ordinary person %s" % self.name
+class Engineer(Person):
+    def __repr__(self):
+        return "Engineer %s, status %s, engineer_name %s, primary_language %s" % (self.name, self.status, self.engineer_name, self.primary_language)
+class Manager(Person):
+    def __repr__(self):
+        return "Manager %s, status %s, manager_name %s" % (self.name, self.status, self.manager_name)
+class Company(object):
+    def __init__(self, **kwargs):
+        for key, value in kwargs.iteritems():
+            setattr(self, key, value)
+    def __repr__(self):
+        return "Company %s" % self.name
+
+
+person_mapper = mapper(Person, people, polymorphic_on=people.c.type, polymorphic_identity='person')
+mapper(Engineer, engineers, inherits=person_mapper, polymorphic_identity='engineer')
+mapper(Manager, managers, inherits=person_mapper, polymorphic_identity='manager')
+
+mapper(Company, companies, properties={
+    'employees': relation(Person, lazy=False, backref='company', cascade="all, delete-orphan")
+})
+
+session = create_session()
+c = Company(name='company1')
+c.employees.append(Manager(name='pointy haired boss', status='AAB', manager_name='manager1'))
+c.employees.append(Engineer(name='dilbert', status='BBA', engineer_name='engineer1', primary_language='java'))
+c.employees.append(Person(name='joesmith', status='HHH'))
+c.employees.append(Engineer(name='wally', status='CGG', engineer_name='engineer2', primary_language='python'))
+c.employees.append(Manager(name='jsmith', status='ABA', manager_name='manager2'))
+session.add(c)
+
+session.flush()
+session.expunge_all()
+
+c = session.query(Company).get(1)
+for e in c.employees:
+    print e, e._sa_instance_state.key, e.company
+assert sets.Set([e.name for e in c.employees]) == sets.Set(['pointy haired boss', 'dilbert', 'joesmith', 'wally', 'jsmith'])
+print "\n"
+
+dilbert = session.query(Person).filter_by(name='dilbert').one()
+dilbert2 = session.query(Engineer).filter_by(name='dilbert').one()
+assert dilbert is dilbert2
+
+dilbert.engineer_name = 'hes dibert!'
+
+session.flush()
+session.expunge_all()
+
+c = session.query(Company).get(1)
+for e in c.employees:
+    print e
+
+session.delete(c)
+session.flush()
+
+metadata.drop_all()
diff --git a/examples/inheritance/single.py b/examples/inheritance/single.py
new file mode 100644
index 000000000..00feaefe8
--- /dev/null
+++ b/examples/inheritance/single.py
@@ -0,0 +1,86 @@
+from sqlalchemy import MetaData, Table, Column, Integer, String, ForeignKey
+from sqlalchemy.orm import mapper, relation, create_session
+
+metadata = MetaData('sqlite://')
+metadata.bind.echo = 'debug'
+
+# a table to store companies
+companies = Table('companies', metadata, 
+   Column('company_id', Integer, primary_key=True),
+   Column('name', String(50)))
+
+employees_table = Table('employees', metadata, 
+    Column('employee_id', Integer, primary_key=True),
+    Column('company_id', Integer, ForeignKey('companies.company_id')),
+    Column('name', String(50)),
+    Column('type', String(20)),
+    Column('status', String(20)),
+    Column('engineer_name', String(50)),
+    Column('primary_language', String(50)),
+    Column('manager_name', String(50))
+)
+
+metadata.create_all()
+
+class Person(object):
+    def __init__(self, **kwargs):
+        for key, value in kwargs.iteritems():
+            setattr(self, key, value)
+    def __repr__(self):
+        return "Ordinary person %s" % self.name
+class Engineer(Person):
+    def __repr__(self):
+        return "Engineer %s, status %s, engineer_name %s, primary_language %s" % (self.name, self.status, self.engineer_name, self.primary_language)
+class Manager(Person):
+    def __repr__(self):
+        return "Manager %s, status %s, manager_name %s" % (self.name, self.status, self.manager_name)
+class Company(object):
+    def __init__(self, **kwargs):
+        for key, value in kwargs.iteritems():
+            setattr(self, key, value)
+    def __repr__(self):
+        return "Company %s" % self.name
+
+person_mapper = mapper(Person, employees_table, polymorphic_on=employees_table.c.type, polymorphic_identity='person')
+manager_mapper = mapper(Manager, inherits=person_mapper, polymorphic_identity='manager')
+engineer_mapper = mapper(Engineer, inherits=person_mapper, polymorphic_identity='engineer')
+
+mapper(Company, companies, properties={
+    'employees': relation(Person, lazy=True, backref='company')
+})
+
+session = create_session()
+c = Company(name='company1')
+c.employees.append(Manager(name='pointy haired boss', status='AAB', manager_name='manager1'))
+c.employees.append(Engineer(name='dilbert', status='BBA', engineer_name='engineer1', primary_language='java'))
+c.employees.append(Person(name='joesmith', status='HHH'))
+c.employees.append(Engineer(name='wally', status='CGG', engineer_name='engineer2', primary_language='python'))
+c.employees.append(Manager(name='jsmith', status='ABA', manager_name='manager2'))
+session.add(c)
+session.flush()
+
+session.expunge_all()
+
+c = session.query(Company).get(1)
+for e in c.employees:
+    print e, e.company
+
+print "\n"
+
+dilbert = session.query(Person).filter_by(name='dilbert').one()
+dilbert2 = session.query(Engineer).filter_by(name='dilbert').one()
+assert dilbert is dilbert2
+
+dilbert.engineer_name = 'hes dibert!'
+
+session.flush()
+session.expunge_all()
+
+c = session.query(Company).get(1)
+for e in c.employees:
+    print e
+
+session.delete(c)
+session.flush()
+
+metadata.drop_all()