Commits

Mike Bayer committed c8ef2fe

- [feature] The cast() and extract() constructs
will now be produced via the func.* accessor
as well, as users naturally try to access these
names from func.* they might as well do
what's expected, even though the returned
object is not a FunctionElement.
[ticket:2562]

Comments (0)

Files changed (4)

     name different from the identified name
     in func.*.
 
+  - [feature] The cast() and extract() constructs
+    will now be produced via the func.* accessor
+    as well, as users naturally try to access these
+    names from func.* they might as well do
+    what's expected, even though the returned
+    object is not a FunctionElement.
+    [ticket:2562]
+
   - [changed] Most classes in expression.sql
     are no longer preceded with an underscore,
     i.e. Label, SelectBase, Generative, CompareMixin.

lib/sqlalchemy/sql/expression.py

 func = _FunctionGenerator()
 """Generate SQL function expressions.
 
-   ``func`` is a special object instance which generates SQL
+   :data:`.func` is a special object instance which generates SQL
    functions based on name-based attributes, e.g.::
 
         >>> print func.count(1)
         >>> print select([func.count(table.c.id)])
         SELECT count(sometable.id) FROM sometable
 
-   Any name can be given to ``func``. If the function name is unknown to
+   Any name can be given to :data:`.func`. If the function name is unknown to
    SQLAlchemy, it will be rendered exactly as is. For common SQL functions
    which SQLAlchemy is aware of, the name may be interpreted as a *generic
    function* which will be compiled appropriately to the target database::
         ... func.my_string(u'there', type_=Unicode)
         my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)
 
-   The object returned by a ``func`` call is an instance of :class:`.Function`.
+   The object returned by a :data:`.func` call is usually an instance of
+   :class:`.Function`.
    This object meets the "column" interface, including comparison and labeling
    functions.  The object can also be passed the :meth:`~.Connectable.execute`
    method of a :class:`.Connection` or :class:`.Engine`, where it will be
 
         print connection.execute(func.current_timestamp()).scalar()
 
-   A function can also be "bound" to a :class:`.Engine` or :class:`.Connection`
-   using the ``bind`` keyword argument, providing an execute() as well
-   as a scalar() method::
-
-        myfunc = func.current_timestamp(bind=some_engine)
-        print myfunc.scalar()
+   In a few exception cases, the :data:`.func` accessor
+   will redirect a name to a built-in expression such as :func:`.cast`
+   or :func:`.extract`, as these names have well-known meaning
+   but are not exactly the same as "functions" from a SQLAlchemy
+   perspective.
+
+   .. versionadded:: 0.8 :data:`.func` can return non-function expression
+      constructs for common quasi-functional names like :func:`.cast`
+      and :func:`.extract`.
 
    Functions which are interpreted as "generic" functions know how to
    calculate their return type automatically. For a listing of known generic

lib/sqlalchemy/sql/functions.py

 
 from .. import types as sqltypes, schema
 from .expression import (
-    ClauseList, Function, _literal_as_binds, literal_column, _type_from_args
+    ClauseList, Function, _literal_as_binds, literal_column, _type_from_args,
+    cast, extract
     )
 from . import operators
 from .visitors import VisitableType
 
 _registry = util.defaultdict(dict)
 
+def register_function(identifier, fn, package="_default"):
+    """Associate a callable with a particular func. name.
+
+    This is normally called by _GenericMeta, but is also
+    available by itself so that a non-Function construct
+    can be associated with the :data:`.func` accessor (i.e.
+    CAST, EXTRACT).
+
+    """
+    reg = _registry[package]
+    reg[identifier] = fn
+
+
 class _GenericMeta(VisitableType):
     def __init__(cls, clsname, bases, clsdict):
         cls.name = name = clsdict.get('name', clsname)
         # legacy
         if '__return_type__' in clsdict:
             cls.type = clsdict['__return_type__']
-        reg = _registry[package]
-        reg[identifier] = cls
+        register_function(identifier, cls, package)
         super(_GenericMeta, cls).__init__(clsname, bases, clsdict)
 
 class GenericFunction(Function):
             kwargs.pop("type_", None) or getattr(self, 'type', None))
 
 
+register_function("cast", cast)
+register_function("extract", extract)
+
 class next_value(GenericFunction):
     """Represent the 'next value', given a :class:`.Sequence`
     as it's single argument.

test/sql/test_functions.py

             "WHERE users.id BETWEEN c1.z AND c2.z",
             checkparams={'y_1': 45, 'x_1': 17, 'y_2': 12, 'x_2': 5})
 
+    def test_non_functions(self):
+        expr = func.cast("foo", Integer)
+        self.assert_compile(expr, "CAST(:param_1 AS INTEGER)")
+
+        expr = func.extract("year", datetime.date(2010, 12, 5))
+        self.assert_compile(expr, "EXTRACT(year FROM :param_1)")
 
 class ExecuteTest(fixtures.TestBase):
     @engines.close_first