From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 29 Dec 2011 16:27:50 +0000 (-0500)
Subject: document that strings are accepted with declarative/secondary
X-Git-Tag: rel_0_7_5~72
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ae53c42d3c6748a15cbd0b5b1b5d90d59bf9d3ca;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

document that strings are accepted with declarative/secondary
---

diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index 6bfd01edd8..c2ab62487f 100644
--- a/doc/build/orm/relationships.rst
+++ b/doc/build/orm/relationships.rst
@@ -174,6 +174,16 @@ is complete::
                         secondary=lambda: association_table, 
                         backref="parents")
 
+With the declarative extension in use, the traditional "string name of the table"
+is accepted as well, matching the name of the table as stored in ``Base.metadata.tables``::
+
+    class Parent(Base):
+        __tablename__ = 'left'
+        id = Column(Integer, primary_key=True)
+        children = relationship("Child", 
+                        secondary="association", 
+                        backref="parents")
+
 .. _association_pattern:
 
 Association Object
diff --git a/lib/sqlalchemy/ext/declarative.py b/lib/sqlalchemy/ext/declarative.py
index dc84c5dfb6..46d267faae 100755
--- a/lib/sqlalchemy/ext/declarative.py
+++ b/lib/sqlalchemy/ext/declarative.py
@@ -185,6 +185,15 @@ the :class:`.MetaData` object used by the declarative base::
         id = Column(Integer, primary_key=True)
         keywords = relationship("Keyword", secondary=keywords)
 
+Like other :func:`.relationship` arguments, a string is accepted as well, 
+passing the string name of the table as defined in the ``Base.metadata.tables``
+collection::
+
+    class Author(Base):
+        __tablename__ = 'authors'
+        id = Column(Integer, primary_key=True)
+        keywords = relationship("Keyword", secondary="keywords")
+
 As with traditional mapping, its generally not a good idea to use 
 a :class:`.Table` as the "secondary" argument which is also mapped to
 a class, unless the :class:`.relationship` is declared with ``viewonly=True``.