From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 28 Jan 2012 22:41:10 +0000 (-0500)
Subject: declarative reflection example
X-Git-Tag: rel_0_7_5~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=84cb539e5f1a0ed3626f8bc0cb42cf5493634786;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

declarative reflection example
---

diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst
index 20f74937fd..bd7fc5a943 100644
--- a/doc/build/orm/examples.rst
+++ b/doc/build/orm/examples.rst
@@ -44,6 +44,14 @@ Location: /examples/beaker_caching/
 
 .. automodule:: beaker_caching
 
+.. _examples_declarative_reflection:
+
+Declarative Reflection
+----------------------
+
+Location: /examples/declarative_reflection
+
+.. automodule:: declarative_reflection
 
 Directed Graphs
 ---------------
diff --git a/examples/declarative_reflection/__init__.py b/examples/declarative_reflection/__init__.py
index 3c6be72889..cadd6ab241 100644
--- a/examples/declarative_reflection/__init__.py
+++ b/examples/declarative_reflection/__init__.py
@@ -18,7 +18,7 @@ classes to override reflected columns.
 
 Usage example::
 
-    Base= declarative_base(cls=DeclarativeReflectedBase)
+    Base = declarative_base(cls=DeclarativeReflectedBase)
 
     class Foo(Base):
         __tablename__ = 'foo'
@@ -26,6 +26,10 @@ Usage example::
 
     class Bar(Base):
         __tablename__ = 'bar'
+
+        # illustrate overriding of "bar.foo_id" to have 
+        # a foreign key constraint otherwise not
+        # reflected, such as when using MySQL
         foo_id = Column(Integer, ForeignKey('foo.id'))
 
     Base.prepare(e)
diff --git a/examples/declarative_reflection/declarative_reflection.py b/examples/declarative_reflection/declarative_reflection.py
index 88f191b3cf..52e6ca65bd 100644
--- a/examples/declarative_reflection/declarative_reflection.py
+++ b/examples/declarative_reflection/declarative_reflection.py
@@ -41,6 +41,10 @@ if __name__ == '__main__':
 
     class Bar(Base):
         __tablename__ = 'bar'
+
+        # illustrate overriding of "bar.foo_id" to have 
+        # a foreign key constraint otherwise not
+        # reflected, such as when using MySQL
         foo_id = Column(Integer, ForeignKey('foo.id'))
 
     e = create_engine('sqlite://', echo=True)
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index bd655a7213..891130a48d 100755
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -264,7 +264,7 @@ to a table::
 ``__table__`` provides a more focused point of control for establishing
 table metadata, while still getting most of the benefits of using declarative.
 An application that uses reflection might want to load table metadata elsewhere
-and simply pass it to declarative classes::
+and pass it to declarative classes::
 
     from sqlalchemy.ext.declarative import declarative_base
 
@@ -313,6 +313,39 @@ a synonym for ``name``::
         def name(self):
             return "Name: %s" % _name
 
+Using Reflection with Declarative
+=================================
+
+It's easy to set up a :class:`.Table` that uses ``autoload=True``
+in conjunction with a mapped class::
+
+    class MyClass(Base):
+        __table__ = Table('mytable', Base.metadata, 
+                        autoload=True, autoload_with=some_engine)
+
+However, one improvement that can be made here is to not 
+require the :class:`.Engine` to be available when classes are 
+being first declared.   To achieve this, use the example
+described at :ref:`examples_declarative_reflection` to build a 
+declarative base that sets up mappings only after a special 
+``prepare(engine)`` step is called::
+
+    Base = declarative_base(cls=DeclarativeReflectedBase)
+
+    class Foo(Base):
+        __tablename__ = 'foo'
+        bars = relationship("Bar")
+
+    class Bar(Base):
+        __tablename__ = 'bar'
+
+        # illustrate overriding of "bar.foo_id" to have 
+        # a foreign key constraint otherwise not
+        # reflected, such as when using MySQL
+        foo_id = Column(Integer, ForeignKey('foo.id'))
+
+    Base.prepare(e)
+
         
 Mapper Configuration
 ====================