From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Mon, 1 Jul 2019 17:09:44 +0000 (-0400)
Subject: A few doc tweaks for alias / order_by / group_by
X-Git-Tag: rel_1_4_0b1~816
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3b60ccaed4844d25617221c853b3e46a78fd7974;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

A few doc tweaks for alias / order_by / group_by

Change-Id: Ib3b46b45735529d68ebfb3784de4de5d2d0f4abc
---

diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst
index 4409996bdf..d48a3beb99 100644
--- a/doc/build/core/tutorial.rst
+++ b/doc/build/core/tutorial.rst
@@ -1083,6 +1083,7 @@ by a column name that appears more than once:
 
 
 
+.. _core_tutorial_aliases:
 
 Using Aliases
 =============
@@ -1800,6 +1801,8 @@ specified to :meth:`.Select.correlate_except`.
     :meth:`.Select.lateral`
 
 
+.. _core_tutorial_ordering:
+
 Ordering, Grouping, Limiting, Offset...ing...
 ---------------------------------------------
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index fbc33ea9b9..e38de66e0d 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -383,12 +383,18 @@ class FromClause(roles.FromClauseRole, Selectable):
     def alias(self, name=None, flat=False):
         """return an alias of this :class:`.FromClause`.
 
-        This is shorthand for calling::
+        E.g.::
+
+            a2 = some_table.alias('a2')
 
-            from sqlalchemy import alias
-            a = alias(self, name=name)
+        The above code creates an :class:`.Alias` object which can be used
+        as a FROM clause in any SELECT statement.
 
-        See :func:`~.expression.alias` for details.
+        .. seealso::
+
+            :ref:`core_tutorial_aliases`
+
+            :func:`~.expression.alias`
 
         """
 
@@ -1140,6 +1146,8 @@ class Join(roles.AnonymizedFromClauseRole, FromClause):
 
         .. seealso::
 
+            :ref:`core_tutorial_aliases`
+
             :func:`~.expression.alias`
 
         """
@@ -1225,7 +1233,10 @@ class Alias(roles.AnonymizedFromClauseRole, FromClause):
 
         Similar functionality is available via the
         :meth:`~.FromClause.alias` method
-        available on all :class:`.FromClause` subclasses.
+        available on all :class:`.FromClause` subclasses.   In terms of a
+        SELECT object as generated from the :func:`.select` function, the
+        :meth:`.SelectBase.alias` method returns an :class:`.Alias` or
+        similar object which represents a named, parenthesized subquery.
 
         When an :class:`.Alias` is created from a :class:`.Table` object,
         this has the effect of the table being rendered
@@ -1530,6 +1541,18 @@ class CTE(Generative, HasSuffixes, Alias):
                 col._make_proxy(self)
 
     def alias(self, name=None, flat=False):
+        """Return an :class:`.Alias` of this :class:`.CTE`.
+
+        This method is a CTE-specific specialization of the
+        :class:`.FromClause.alias` method.
+
+        .. seealso::
+
+            :ref:`core_tutorial_aliases`
+
+            :func:`~.expression.alias`
+
+        """
         return CTE._construct(
             self.element,
             name=name,
@@ -2428,11 +2451,19 @@ class GenerativeSelect(SelectBase):
 
     @_generative
     def order_by(self, *clauses):
-        """return a new selectable with the given list of ORDER BY
+        r"""return a new selectable with the given list of ORDER BY
         criterion applied.
 
-        The criterion will be appended to any pre-existing ORDER BY
-        criterion.
+        e.g.::
+
+            stmt = select([table]).order_by(table.c.id, table.c.name)
+
+        :param \*order_by: a series of :class:`.ColumnElement` constructs
+         which will be used to generate an ORDER BY clause.
+
+        .. seealso::
+
+            :ref:`core_tutorial_ordering`
 
         """
 
@@ -2440,11 +2471,20 @@ class GenerativeSelect(SelectBase):
 
     @_generative
     def group_by(self, *clauses):
-        """return a new selectable with the given list of GROUP BY
+        r"""return a new selectable with the given list of GROUP BY
         criterion applied.
 
-        The criterion will be appended to any pre-existing GROUP BY
-        criterion.
+        e.g.::
+
+            stmt = select([table.c.name, func.max(table.c.stat)]).\
+            group_by(table.c.name)
+
+        :param \*group_by: a series of :class:`.ColumnElement` constructs
+         which will be used to generate an GROUP BY clause.
+
+        .. seealso::
+
+            :ref:`core_tutorial_ordering`
 
         """
 
@@ -2459,6 +2499,10 @@ class GenerativeSelect(SelectBase):
         :meth:`~.GenerativeSelect.order_by` method is preferred, as it
         provides standard :term:`method chaining`.
 
+        .. seealso::
+
+            :meth:`.GenerativeSelect.order_by`
+
         """
         if len(clauses) == 1 and clauses[0] is None:
             self._order_by_clause = ClauseList()
@@ -2478,6 +2522,10 @@ class GenerativeSelect(SelectBase):
         :meth:`~.GenerativeSelect.group_by` method is preferred, as it
         provides standard :term:`method chaining`.
 
+        .. seealso::
+
+            :meth:`.GenerativeSelect.group_by`
+
         """
         if len(clauses) == 1 and clauses[0] is None:
             self._group_by_clause = ClauseList()