From e80eac22a8669ada5ffaabbcfa8a991eee140697 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Wed, 9 Feb 2011 16:30:49 -0500 Subject: - figured out the ::autodata directive, can move the docstring for expression.func into the .py module - added a note about logging only being checked on new connections, as one user had this issue awhile back, and I suspect it for a current ML user issue --- lib/sqlalchemy/sql/expression.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'lib/sqlalchemy/sql') diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py index 3bc056fae..04ca147bb 100644 --- a/lib/sqlalchemy/sql/expression.py +++ b/lib/sqlalchemy/sql/expression.py @@ -1025,6 +1025,41 @@ class _FunctionGenerator(object): # "func" global - i.e. func.count() func = _FunctionGenerator() +"""Generate SQL function expressions. + + ``func`` is a special object instance which generates SQL functions based on name-based attributes, e.g.:: + + >>> print func.count(1) + count(:param_1) + + Any name can be given to `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:: + + >>> print func.current_timestamp() + CURRENT_TIMESTAMP + + To call functions which are present in dot-separated packages, specify them in the same manner:: + + >>> print func.stats.yield_curve(5, 10) + stats.yield_curve(:yield_curve_1, :yield_curve_2) + + SQLAlchemy can be made aware of the return type of functions to enable + type-specific lexical and result-based behavior. For example, to ensure + that a string-based function returns a Unicode value and is similarly + treated as a string in expressions, specify + :class:`~sqlalchemy.types.Unicode` as the type: + + >>> print func.my_string(u'hi', type_=Unicode) + ' ' + \ + ... func.my_string(u'there', type_=Unicode) + my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3) + + Functions which are interpreted as "generic" functions know how to + calculate their return type automatically. For a listing of known generic + functions, see :ref:`generic_functions`. + +""" # "modifier" global - i.e. modifier.distinct # TODO: use UnaryExpression for this instead ? -- cgit v1.2.1