From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 9 Nov 2010 17:09:41 +0000 (-0500)
Subject: add a note to use column_property with declarative map to a join
X-Git-Tag: rel_0_7b1~280
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1ce6b7c9b54d9a46994162f1d38e88335c93ec6c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

add a note to use column_property with declarative map to a join
---

diff --git a/doc/build/orm/mapper_config.rst b/doc/build/orm/mapper_config.rst
index 15377436fa..0c8bb0c43d 100644
--- a/doc/build/orm/mapper_config.rst
+++ b/doc/build/orm/mapper_config.rst
@@ -570,6 +570,7 @@ passed in to a mapper as the table.
 
 .. sourcecode:: python+sql
 
+    from sqlalchemy.orm import mapper
     from sqlalchemy.sql import join
     
     class AddressUser(object):
@@ -584,11 +585,31 @@ passed in to a mapper as the table.
         'user_id': [users_table.c.user_id, addresses_table.c.user_id]
     })
 
-A second example:
+Note that the list of columns is equivalent to the usage of :func:`.column_property`
+with multiple columns::
 
-.. sourcecode:: python+sql
+    from sqlalchemy.orm import mapper, column_property
+    
+    mapper(AddressUser, j, properties={
+        'user_id': column_property(users_table.c.user_id, addresses_table.c.user_id)
+    })
 
-    from sqlalchemy.sql import join
+The usage of :func:`.column_property` is required when using declarative to map 
+to multiple columns, since the declarative class parser won't recognize a plain 
+list of columns::
+
+    from sqlalchemy.ext.declarative import declarative_base
+    
+    Base = declarative_base()
+    
+    class AddressUser(Base):
+        __table__ = j
+        
+        user_id = column_property(users_table.c.user_id, addresses_table.c.user_id)
+
+A second example::
+
+        from sqlalchemy.sql import join
 
     # many-to-many join on an association table
     j = join(users_table, userkeywords,
@@ -611,6 +632,7 @@ mappers; these are aggregations of multiple columns into one mapper property,
 which instructs the mapper to keep both of those columns set at the same
 value.
 
+
 Mapping a Class against Arbitrary Selects
 ------------------------------------------