declarative reflection example

diff --git a/doc/build/orm/examples.rst b/doc/build/orm/examples.rst
index 20f74937fd9ffbefc09abff75bd4b9d7903a2f31..bd7fc5a943878cf40e766db412a72184eb95c582 100644 (file)
--- 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 3c6be72889ad60978c6f284736ef84d23e8f9616..cadd6ab241b1bc3abe561593646db3301ea276ba 100644 (file)
--- 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 88f191b3cf4cc86e774fd8a18e5ab57f70980e92..52e6ca65bd35cd26866e5e27cdfabc50f0e82c67 100644 (file)
--- 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 bd655a721355761c05bda51a771f946ae0c743ff..891130a48d5e6505b12b6b635fb52d40862d0ce5 100755 (executable)
--- 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
 ====================