declarative reflection example

4 files changed, 51 insertions, 2 deletions

diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst
index 20f74937f..bd7fc5a94 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 3c6be7288..cadd6ab24 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 88f191b3c..52e6ca65b 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 bd655a721..891130a48 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
 ====================