document that strings are accepted with declarative/secondary

diff --git a/doc/build/orm/relationships.rst b/doc/build/orm/relationships.rst
index 6bfd01edd856f4ea10461af861725f7d11e2ccb6..c2ab62487f7fedb82d4ccc0cf083c3c4ce16e24a 100644 (file)
--- 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 dc84c5dfb6356d9428880a8e37834517af976ab4..46d267faae12f3837364434ba3a014d1f319a233 100755 (executable)
--- 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``.