Add links to with_only_columns to Select.column, append_column

Provide a brief example for these two methods
indicating that typically a table-bound (or other selectable)
column is appended here, then link to with_only_columns
documentation which has in-depth guidelines already including
that one should not append columns from the current select to itself.

Change-Id: I0742405a7f3c41450d337b9c633519d9cc101dfb
Fixes: #3987

1 files changed, 16 insertions, 19 deletions

diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 9db1e0844..a6ed6b0ce 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3026,6 +3026,14 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
         """return a new select() construct with the given column expression
             added to its columns clause.
 
+            E.g.::
+
+                my_select = my_select.column(table.c.new_column)
+
+            See the documentation for :meth:`.Select.with_only_columns`
+            for guidelines on adding /replacing the columns of a
+            :class:`.Select` object.
+
         """
         self.append_column(column)
 
@@ -3066,25 +3074,6 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
         r"""Return a new :func:`.select` construct with its columns
         clause replaced with the given columns.
 
-        .. versionchanged:: 0.7.3
-            Due to a bug fix, this method has a slight
-            behavioral change as of version 0.7.3.
-            Prior to version 0.7.3, the FROM clause of
-            a :func:`.select` was calculated upfront and as new columns
-            were added; in 0.7.3 and later it's calculated
-            at compile time, fixing an issue regarding late binding
-            of columns to parent tables.  This changes the behavior of
-            :meth:`.Select.with_only_columns` in that FROM clauses no
-            longer represented in the new list are dropped,
-            but this behavior is more consistent in
-            that the FROM clauses are consistently derived from the
-            current columns clause.  The original intent of this method
-            is to allow trimming of the existing columns list to be fewer
-            columns than originally present; the use case of replacing
-            the columns list with an entirely different one hadn't
-            been anticipated until 0.7.3 was released; the usage
-            guidelines below illustrate how this should be done.
-
         This method is exactly equivalent to as if the original
         :func:`.select` had been called with the given columns
         clause.   I.e. a statement::
@@ -3351,10 +3340,18 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
         """append the given column expression to the columns clause of this
         select() construct.
 
+        E.g.::
+
+            my_select.append_column(some_table.c.new_column)
+
         This is an **in-place** mutation method; the
         :meth:`~.Select.column` method is preferred, as it provides standard
         :term:`method chaining`.
 
+        See the documentation for :meth:`.Select.with_only_columns`
+        for guidelines on adding /replacing the columns of a
+        :class:`.Select` object.
+
         """
         self._reset_exported()
         column = _interpret_as_column_or_from(column)