- 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

doc/build/core/engines.rst

@@ -314,3 +314,14 @@ or :class:`~sqlalchemy.pool.Pool` defaults to using a truncated hex identifier
 string. To set this to a specific name, use the "logging_name" and
 "pool_logging_name" keyword arguments with :func:`sqlalchemy.create_engine`.
 
+.. note::
+    The SQLAlchemy :class:`.Engine` conserves Python function call overhead
+    by only emitting log statements when the current logging level is detected
+    as ``logging.INFO`` or ``logging.DEBUG``.  It only checks this level when 
+    a new connection is procured from the connection pool.  Therefore when 
+    changing the logging configuration for an already-running application, any
+    :class:`.Connection` that's currently active, or more commonly a
+    :class:`~.orm.session.Session` object that's active in a transaction, won't log any
+    SQL according to the new configuration until a new :class:`.Connection` 
+    is procured (in the case of :class:`~.orm.session.Session`, this is 
+    after the current transaction ends and a new one begins).

doc/build/core/expression_api.rst

@@ -45,41 +45,7 @@ The expression package uses functions to construct SQL expressions.  The return
 
 .. autofunction:: extract
 
-.. attribute:: func
-
-   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`.
+.. autodata:: func
 
 .. autofunction:: insert
 

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 ?