updates

1 files changed, 87 insertions, 52 deletions

diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 536058a50..2963ef1a5 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -46,7 +46,7 @@ def collate(expression, collation):
         operators.collate, type_=expr.type)
 
 def between(expr, lower_bound, upper_bound):
-    """Produce ``BETWEEN`` predicate clause.
+    """Produce a ``BETWEEN`` predicate clause.
 
     E.g.::
 
@@ -722,7 +722,7 @@ class ColumnElement(ClauseElement, operators.ColumnOperators):
 
 
 class BindParameter(ColumnElement):
-    """Represent a "bound expression" for usage in a SQL construct.
+    """Represent a "bound expression".
 
     :class:`.BindParameter` is invoked explicitly using the
     :func:`.bindparam` function, as in::
@@ -751,7 +751,7 @@ class BindParameter(ColumnElement):
                             isoutparam=False,
                             _compared_to_operator=None,
                             _compared_to_type=None):
-        """Produce a "bound expression" for usage in a SQL construct.
+        """Produce a "bound expression".
 
         The return value is an instance of :class:`.BindParameter`; this
         is a :class:`.ColumnElement` subclass which represents a so-called
@@ -1705,7 +1705,7 @@ class BooleanClauseList(ClauseList, ColumnElement):
 
     @classmethod
     def and_(cls, *clauses):
-        """Produce a conjunction of clauses joined by ``AND``.
+        """Produce a conjunction of expressions joined by ``AND``.
 
         E.g.::
 
@@ -1746,7 +1746,7 @@ class BooleanClauseList(ClauseList, ColumnElement):
 
     @classmethod
     def or_(cls, *clauses):
-        """Produce a conjunction of clauses joined by ``OR``.
+        """Produce a conjunction of expressions joined by ``OR``.
 
         E.g.::
 
@@ -1865,7 +1865,7 @@ class Case(ColumnElement):
     __visit_name__ = 'case'
 
     def __init__(self, whens, value=None, else_=None):
-        """Produce a ``CASE`` expression for usage in a SQL construct.
+        """Produce a ``CASE`` expression.
 
         The ``CASE`` construct in SQL is a conditional object that
         acts somewhat analogously to an "if/then" construct in other
@@ -2145,6 +2145,10 @@ class UnaryExpression(ColumnElement):
     (where it is called the 'operator') or right (where it is called the
     'modifier') of the column expression.
 
+    :class:`.UnaryExpression` is the basis for several unary operators
+    including those used by :func:`.desc`, :func:`.asc`, :func:`.distinct`,
+    :func:`.nullsfirst` and :func:`.nullslast`.
+
     """
     __visit_name__ = 'unary'
 
@@ -2238,7 +2242,7 @@ class UnaryExpression(ColumnElement):
 
     @classmethod
     def _create_desc(cls, column):
-        """Return a descending ``ORDER BY`` clause element.
+        """Produce a descending ``ORDER BY`` clause element.
 
         e.g.::
 
@@ -2276,7 +2280,7 @@ class UnaryExpression(ColumnElement):
 
     @classmethod
     def _create_asc(cls, column):
-        """Return an ascending ``ORDER BY`` clause element.
+        """Produce an ascending ``ORDER BY`` clause element.
 
         e.g.::
 
@@ -2715,7 +2719,20 @@ class Label(ColumnElement):
 
 
 class ColumnClause(Immutable, ColumnElement):
-    """Represents a generic column expression from any textual string.
+    """Represents a column expression from any textual string.
+
+    The :class:`.ColumnClause`, a lightweight analogue to the
+    :class:`.Column` class, is typically invoked using the
+    :func:`.column` function, as in::
+
+        from sqlalchemy.sql import column
+
+        id, name = column("id"), column("name")
+        stmt = select([id, name]).select_from("user")
+
+    The above statement would produce SQL like::
+
+        SELECT id, name FROM user
 
     :class:`.ColumnClause` is the immediate superclass of the schema-specific
     :class:`.Column` object.  While the :class:`.Column` class has all the
@@ -2726,58 +2743,74 @@ class ColumnClause(Immutable, ColumnElement):
     that :class:`.Column` does, so in that sense is a "lightweight" version
     of :class:`.Column`.
 
-    :class:`.ColumnClause` is constructed by itself typically via
-    the :func:`~.expression.column` function.  The datatype is optional.
-    It may be placed directly
-    into constructs such as :func:`.select` constructs::
+    Full details on :class:`.ColumnClause` usage is at :func:`.column`.
 
-        from sqlalchemy.sql import column, select
+    .. seealso::
 
-        c1, c2 = column("c1"), column("c2")
-        s = select([c1, c2]).where(c1==5)
+        :func:`.column`
 
-    There is also a variant on :func:`~.expression.column` known
-    as :func:`~.expression.literal_column` - the difference is that
-    in the latter case, the string value is assumed to be an exact
-    expression, rather than a column name, so that no quoting rules
-    or similar are applied::
+        :class:`.Column`
 
-        from sqlalchemy.sql import literal_column, select
+    """
+    __visit_name__ = 'column'
 
-        s = select([literal_column("5 + 7")])
+    onupdate = default = server_default = server_onupdate = None
 
-    :class:`.ColumnClause` can also be used in a table-like
-    fashion by combining the :func:`~.expression.column` function
-    with the :func:`~.expression.table` function, to produce
-    a "lightweight" form of table metadata::
+    _memoized_property = util.group_expirable_memoized_property()
 
-        from sqlalchemy.sql import table, column
+    def __init__(self, text, type_=None, is_literal=False, _selectable=None):
+        """Produce a :class:`.ColumnClause` object.
 
-        user = table("user",
-                column("id"),
-                column("name"),
-                column("description"),
-        )
+        The :class:`.ColumnClause` is a lightweight analogue to the
+        :class:`.Column` class.  The :func:`.column` function can
+        be invoked with just a name alone, as in::
 
-    The above construct can be created in an ad-hoc fashion and is
-    not associated with any :class:`.schema.MetaData`, unlike it's
-    more full fledged :class:`.schema.Table` counterpart.
+            from sqlalchemy.sql import column
 
-    .. seealso::
+            id, name = column("id"), column("name")
+            stmt = select([id, name]).select_from("user")
 
-        :class:`.Column`
+        The above statement would produce SQL like::
 
-        :ref:`metadata_toplevel`
+            SELECT id, name FROM user
 
-    """
-    __visit_name__ = 'column'
+        Once constructed, :func:`.column` may be used like any other SQL expression
+        element such as within :func:`.select` constructs::
 
-    onupdate = default = server_default = server_onupdate = None
+            from sqlalchemy.sql import column
 
-    _memoized_property = util.group_expirable_memoized_property()
+            id, name = column("id"), column("name")
+            stmt = select([id, name]).select_from("user")
 
-    def __init__(self, text, type_=None, is_literal=False, _selectable=None):
-        """Construct a :class:`.ColumnClause` object.
+        The text handled by :func:`.column` is assumed to be handled
+        like the name of a database column; if the string contains mixed case,
+        special characters, or matches a known reserved word on the target
+        backend, the column expression will render using the quoting
+        behavior determined by the backend.  To produce a textual SQL
+        expression that is rendered exactly without any quoting,
+        use :func:`.literal_column` instead, or pass ``True`` as the
+        value of :paramref:`.column.is_literal`.   Additionally, full SQL
+        statements are best handled using the :func:`.text` construct.
+
+        :func:`.column` can be used in a table-like
+        fashion by combining it with the :func:`.table` function
+        (which is the lightweight analogue to :class:`.Table`) to produce
+        a working table construct with minimal boilerplate::
+
+            from sqlalchemy.sql import table, column
+
+            user = table("user",
+                    column("id"),
+                    column("name"),
+                    column("description"),
+            )
+
+            stmt = select([user.c.description]).where(user.c.name == 'wendy')
+
+        A :func:`.column` / :func:`.table` construct like that illustrated
+        above can be created in an
+        ad-hoc fashion and is not associated with any :class:`.schema.MetaData`,
+        DDL, or events, unlike its :class:`.Table` counterpart.
 
         :param text: the text of the element.
 
@@ -2787,16 +2820,18 @@ class ColumnClause(Immutable, ColumnElement):
         :param is_literal: if True, the :class:`.ColumnClause` is assumed to
           be an exact expression that will be delivered to the output with no
           quoting rules applied regardless of case sensitive settings. the
-          :func:`literal_column()` function is usually used to create such a
-          :class:`.ColumnClause`.
+          :func:`.literal_column()` function essentially invokes :func:`.column`
+          while passing ``is_literal=True``.
+
+        .. seealso::
+
+            :class:`.Column`
 
-        :param text: the name of the column.  Quoting rules will be applied
-          to the clause like any other column name. For textual column constructs
-          that are not to be quoted, use the :func:`literal_column` function.
+            :func:`.literal_column`
 
-        :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` object
-          which will provide result-set translation for this column.
+            :func:`.text`
 
+            :ref:`metadata_toplevel`
 
         """