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.
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::
+ 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.
- myfunc = func.current_timestamp(bind=some_engine)
- print myfunc.scalar()
+ .. 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
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.
"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
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
