From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 1 Jul 2011 21:09:57 +0000 (-0400)
Subject: - add doc to schema docs linking to declarative usage of __table__
X-Git-Tag: rel_0_7_2~37
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ed633ffce1c88d323c85fdea8c564035a271e6bb;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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 58105f1609..dc1011bc15 100644
--- 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 27d05733b7..8c26edf5cd 100755
--- 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
 ====================