tighten this up

doc/build/core/expression_api.rst

@@ -200,6 +200,10 @@ Classes
    :members:
    :show-inheritance:
 
+.. autoclass:: UnaryExpression
+   :members:
+   :show-inheritance:
+
 .. autoclass:: Update
   :members:
   :show-inheritance:

doc/build/core/types.rst

@@ -661,23 +661,50 @@ we create a :class:`.Integer` subclass which overrides the :meth:`.ColumnOperato
 
 The above configuration creates a new class ``MyInt``, which
 establishes the :attr:`.TypeEngine.comparator_factory` attribute as
-referring to a new class, subclassing the ``Comparator`` class
+referring to a new class, subclassing the :class:`.TypeEngine.Comparator` class
 associated with the :class:`.Integer` type.
 
+Usage::
+
+    >>> sometable = Table("sometable", metadata, Column("data", MyInt))
+    >>> print sometable.c.data + 5
+    sometable.data goofy :data_1
+
 The implementation for :meth:`.ColumnOperators.__add__` is consulted
-by an owning SQL expression, by instantiating the ``Comparator`` with
+by an owning SQL expression, by instantiating the :class:`.TypeEngine.Comparator` with
 itself as as the ``expr`` attribute.   The mechanics of the expression
 system are such that operations continue recursively until an
 expression object produces a new SQL expression construct. Above, we
 could just as well have said ``self.expr.op("goofy")(other)`` instead
 of ``self.op("goofy")(other)``.
 
-New methods added to a ``Comparator`` are exposed on an owning SQL expression
-using a ``__getattr__`` scheme.  For example, to add an implementation of the
-Postgresql factorial operator::
+New methods added to a :class:`.TypeEngine.Comparator` are exposed on an
+owning SQL expression
+using a ``__getattr__`` scheme, which exposes methods added to
+:class:`.TypeEngine.Comparator` onto the owning :class:`.ColumnElement`.
+For example, to add a ``log()`` function
+to integers::
+
+    from sqlalchemy import Integer, func
+
+    class MyInt(Integer):
+        class comparator_factory(Integer.Comparator):
+            def log(self, other):
+                return func.log(self, other)
+
+Using the above type::
+
+    >>> print sometable.c.data.log(5)
+    log(:log_1, :log_2)
+
+
+Unary operations
+are also possible.  For example, to add an implementation of the
+Postgresql factorial operator, we combine the :class:`.UnaryExpression` construct
+along with a :class:`.custom_op` to produce the factorial expression::
 
     from sqlalchemy import Integer
-    from sqlalchemy.sql import UnaryExpression
+    from sqlalchemy.sql.expression import UnaryExpression
     from sqlalchemy.sql import operators
 
     class MyInteger(Integer):
@@ -687,6 +714,16 @@ Postgresql factorial operator::
                             modifier=operators.custom_op("!"),
                             type_=MyInteger)
 
+Using the above type::
+
+    >>> from sqlalchemy.sql import column
+    >>> print column('x', MyInteger).factorial()
+    x !
+
+See also:
+
+:attr:`.TypeEngine.comparator_factory`
+
 .. versionadded:: 0.8  The expression system was enhanced to support
   customization of operators on a per-type level.
 

doc/build/index.rst

@@ -84,6 +84,7 @@ are documented here.  In contrast to the ORM's domain-centric mode of usage, the
   :ref:`SQL Standard Types <types_sqlstandard>` |
   :ref:`Vendor Specific Types <types_vendor>` |
   :ref:`Building Custom Types <types_custom>` |
+  :ref:`Defining New Operators <types_operators>` |
   :ref:`API <types_api>`
 
 * **Extending the Core:**
@@ -94,7 +95,6 @@ are documented here.  In contrast to the ORM's domain-centric mode of usage, the
 
 * **Other:**
   :doc:`Runtime Inspection API <core/inspection>` |
-  :doc:`Serializing Expressions <core/serializer>` |
   :doc:`core/interfaces` |
   :doc:`core/exceptions`
 

lib/sqlalchemy/sql/expression.py

@@ -2141,21 +2141,21 @@ class _DefaultColumnComparator(operators.ColumnOperators):
 
 
 class ColumnElement(ClauseElement, ColumnOperators):
-    """Represent an element that is usable within the "column clause" portion
-    of a ``SELECT`` statement.
+    """Represent a column-oriented SQL expression suitable for usage in the
+    "columns" clause, WHERE clause etc. of a statement.
 
     While the most familiar kind of :class:`.ColumnElement` is the
     :class:`.Column` object, :class:`.ColumnElement` serves as the basis
     for any unit that may be present in a SQL expression, including
-    the columns associated with tables, aliases, and
-    subqueries, expressions, function calls, SQL keywords such as
-    ``NULL``, literals, etc.  :class:`.ColumnElement` is the ultimate base
-    class for all such elements.
+    the expressions themselves, SQL functions, bound parameters,
+    literal expressions, keywords such as ``NULL``, etc.  :class:`.ColumnElement`
+    is the ultimate base class for all such elements.
 
-    A :class:`.ColumnElement` provides the ability to generate new :class:`.ClauseElement`
+    A :class:`.ColumnElement` provides the ability to generate new
+    :class:`.ColumnElement`
     objects using Python expressions.  This means that Python operators
     such as ``==``, ``!=`` and ``<`` are overloaded to mimic SQL operations,
-    and allow the construction of :class:`.ColumnElement` constructs which
+    and allow the instantiation of further :class:`.ColumnElement` instances which
     are composed from other, more fundamental :class:`.ColumnElement`
     objects.  For example, two :class:`.ColumnClause` objects can be added
     together with the addition operator ``+`` to produce

lib/sqlalchemy/types.py

@@ -74,56 +74,7 @@ class TypeEngine(AbstractType):
 
     Rudimentary usage of this hook is allowed through simple subclassing
     of existing types, or alternatively by using :class:`.TypeDecorator`.
-    E.g. to overload the ``+`` operator on :class:`.Integer`::
-
-        from sqlalchemy import Integer
-
-        class MyInt(Integer):
-            class comparator_factory(Integer.Comparator):
-                def __add__(self, other):
-                    return self.op("goofy")(other)
-
-    Usage::
-
-        >>> sometable = Table("sometable", metadata, Column("data", MyInt))
-        >>> print sometable.c.data + 5
-        sometable.data goofy :data_1
-
-    New comparison methods and operations applied to :class:`.TypeEngine.Comparator`
-    are made available on parent SQL constructs using a ``__getattr__()`` scheme::
-
-        from sqlalchemy import Integer, func
-
-        class MyInt(Integer):
-            class comparator_factory(Integer.Comparator):
-                def log(self, other):
-                    return func.log(self, other)
-
-    E.g.::
-
-        >>> print sometable.c.data.log(5)
-        log(:log_1, :log_2)
-
-    The :class:`.TypeEngine` associated with a particular :class:`.ColumnElement`
-    is propagated during expression construction to the containing elements
-    according to simple "adaptation" rules.   An example of an "adaptation"
-    would be adding two integers leads to a "binary" expression that is also
-    of type integer::
-
-        >>> from sqlalchemy.sql import column
-        >>> from sqlalchemy.types import Integer
-        >>> c1 = column('c1', Integer)
-        >>> c2 = column('c2', Integer)
-        >>> c1.type
-        Integer()
-        >>> (c1 + c2).type
-        Integer()
-
-    If the two columns above were compared using a boolean operator,
-    the resulting type would instead be :class:`.Boolean`::
-
-        >>> (c1 == c2).type
-        Boolean()
+    See the documentation section :ref:`types_operators` for examples.
 
     .. versionadded:: 0.8  The expression system was enhanced to support
       customization of operators on a per-type level.