From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 26 Sep 2011 21:32:47 +0000 (-0400)
Subject: improved docs on select_from() [ticket:2274]
X-Git-Tag: rel_0_6_9~25
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1175704535584d4c6899076b868ac4d5b9589c47;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

improved docs on select_from() [ticket:2274]
---

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 8df45d1580..b7cfe9f04d 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -3135,8 +3135,9 @@ class _Exists(_UnaryExpression):
         return e
 
     def select_from(self, clause):
-        """return a new exists() construct with the given expression set as
-        its FROM clause.
+        """return a new :class:`._Exists` construct, applying the given expression
+        to the :meth:`.Select.select_from` method of the select statement
+        contained.
 
         """
         e = self._clone()
@@ -4311,10 +4312,18 @@ class Select(_SelectBaseMixin, FromClause):
 
     @_generative
     def select_from(self, fromclause):
-        """return a new select() construct with the given FROM expression
-        applied to its list of FROM objects.
+        """return a new :class:`.Select` construct with the given FROM expression
+        merged into its list of FROM objects.
+        
+        The "from" list is a unique set on the identity of each element,
+        so adding an already present :class:`.Table` or other selectable
+        will have no effect.   Passing a :class:`.Join` that refers
+        to an already present :class:`.Table` or other selectable will have 
+        the effect of concealing the presence of that selectable as 
+        an individual element in the rendered FROM list, instead rendering it into a
+        JOIN clause.
 
-         """
+        """
         fromclause = _literal_as_text(fromclause)
         self._froms = self._froms.union([fromclause])