- repair doctest for SQL expression tutorial

- remove most use of "whereclause" and "from_obj", not done yet,
part of [ticket:2679]
- add links to method chained versions for all Select.append_XYZ()
calls
- add "method chaining" and "generative" to glossary

1 files changed, 35 insertions, 1 deletions

diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 41eaace71..df3d5fb7e 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -4914,6 +4914,10 @@ class SelectBase(Executable, FromClause):
 
         The criterion will be appended to any pre-existing ORDER BY criterion.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.SelectBase.order_by` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         if len(clauses) == 1 and clauses[0] is None:
             self._order_by_clause = ClauseList()
@@ -4927,6 +4931,10 @@ class SelectBase(Executable, FromClause):
 
         The criterion will be appended to any pre-existing GROUP BY criterion.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.SelectBase.group_by` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         if len(clauses) == 1 and clauses[0] is None:
             self._group_by_clause = ClauseList()
@@ -5682,7 +5690,13 @@ class Select(HasPrefixes, SelectBase):
 
     def append_correlation(self, fromclause):
         """append the given correlation expression to this select()
-        construct."""
+        construct.
+
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.correlate` method is preferred, as it provides standard
+        :term:`method chaining`.
+
+        """
 
         self._auto_correlate = False
         self._correlate = set(self._correlate).union(
@@ -5692,6 +5706,10 @@ class Select(HasPrefixes, SelectBase):
         """append the given column expression to the columns clause of this
         select() construct.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.column` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         self._reset_exported()
         column = _interpret_as_column_or_from(column)
@@ -5705,6 +5723,10 @@ class Select(HasPrefixes, SelectBase):
         """append the given columns clause prefix expression to this select()
         construct.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.prefix_with` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         clause = _literal_as_text(clause)
         self._prefixes = self._prefixes + (clause,)
@@ -5715,6 +5737,10 @@ class Select(HasPrefixes, SelectBase):
 
         The expression will be joined to existing WHERE criterion via AND.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.where` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         self._reset_exported()
         whereclause = _literal_as_text(whereclause)
@@ -5730,6 +5756,10 @@ class Select(HasPrefixes, SelectBase):
 
         The expression will be joined to existing HAVING criterion via AND.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.having` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         if self._having is not None:
             self._having = and_(self._having, _literal_as_text(having))
@@ -5740,6 +5770,10 @@ class Select(HasPrefixes, SelectBase):
         """append the given FromClause expression to this select() construct's
         FROM clause.
 
+        This is an **in-place** mutation method; the
+        :meth:`~.Select.select_from` method is preferred, as it provides standard
+        :term:`method chaining`.
+
         """
         self._reset_exported()
         fromclause = _interpret_as_from(fromclause)