- add doc to schema docs linking to declarative usage of __table__

- add more examples to __table__ such as that asked on a recent
stackoverflow question.

diff --git a/doc/build/core/schema.rst b/doc/build/core/schema.rst
index 58105f16098696ca5e55faf22bb226080da4f75c..dc1011bc15543b85d15a4177427700933ea7e21d 100644 (file)
--- a/doc/build/core/schema.rst
+++ b/doc/build/core/schema.rst
@@ -1062,6 +1062,19 @@ MySQL.
         CONSTRAINT check1  CHECK (col2 > col3 + 5)
     ){stop}
 
+Setting up Constraints when using the Declarative ORM Extension
+----------------------------------------------------------------
+
+The :class:`.Table` is the SQLAlchemy Core construct that allows one to define
+table metadata, which among other things can be used by the SQLAlchemy ORM
+as a target to map a class.  The :ref:`Declarative <declarative_toplevel>`
+extension allows the :class:`.Table` object to be created automatically, given 
+the contents of the table primarily as a mapping of :class:`.Column` objects.
+
+To apply table-level constraint objects such as :class:`.ForeignKeyConstraint`
+to a table defined using Declarative, use the ``__table_args__`` attribute, 
+described at :ref:`declarative_table_args`.
+
 Constraints API
 ---------------
 .. autoclass:: Constraint

diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index 27d05733b793407b15581b5b37ad8422c900e18e..8c26edf5cdceaedcebeffeede19bd19e658a4538 100755 (executable)
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -247,6 +247,8 @@ of the ``User`` class::
             where(Address.user_id==User.id)
     ) 
 
+.. _declarative_table_args:
+
 Table Configuration
 ===================
 
@@ -318,6 +320,39 @@ Some configuration schemes may find it more appropriate to use ``__table__``,
 such as those which already take advantage of the data-driven nature of 
 :class:`.Table` to customize and/or automate schema definition. 
 
+Note that when the ``__table__`` approach is used, the object is immediately
+usable as a plain :class:`.Table` within the class declaration body itself,
+as a Python class is only another syntactical block.  Below this is illustrated
+by using the ``id`` column in the ``primaryjoin`` condition of a :func:`.relationship`::
+
+    class MyClass(Base):
+        __table__ = Table('my_table', Base.metadata,
+            Column('id', Integer, primary_key=True),
+            Column('name', String(50))
+        )
+
+        widgets = relationship(Widget, 
+                    primaryjoin=Widget.myclass_id==__table__.c.id)
+
+Similarly, mapped attributes which refer to ``__table__`` can be placed inline, 
+as below where we assign the ``name`` column to the attribute ``_name``, generating
+a synonym for ``name``::
+
+    from sqlalchemy.ext.declarative import synonym_for
+    
+    class MyClass(Base):
+        __table__ = Table('my_table', Base.metadata,
+            Column('id', Integer, primary_key=True),
+            Column('name', String(50))
+        )
+
+        _name = __table__.c.name
+
+        @synonym_for("_name")
+        def name(self):
+            return "Name: %s" % _name
+
+        
 Mapper Configuration
 ====================