From: Mike Bayer Date: Thu, 17 Oct 2019 19:04:47 +0000 (-0400) Subject: fix func docs X-Git-Tag: rel_1_3_11~35 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=c35573cbebfe8b16b71feb04702c7123d2530e13;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git fix func docs sphinx is not generating the docs for func. cross-copy __doc__ and also add more links. Fixes: #4922 Change-Id: I5512111d726b6fcf9821be730c9e29adc73c95cb (cherry picked from commit e45878bf4f9cdfb714dce8b2a4d705178947674d) --- diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index d9a0dfd308..9fd46aaca7 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -1360,6 +1360,17 @@ don't get the parenthesis added after them, such as CURRENT_TIMESTAMP: >>> print(func.current_timestamp()) CURRENT_TIMESTAMP +A function, like any other column expression, has a type, which indicates the +type of expression as well as how SQLAlchemy will interpret result columns +that are returned from this expression. The default type used for an +arbitrary function name derived from :attr:`.func` is simply a "null" datatype. +However, in order for the column expression generated by the function to +have type-specific operator behavior as well as result-set behaviors, such +as date and numeric coercions, the type may need to be specified explicitly:: + + >>> stmt = select([func.date(some_table.c.date_string, type_=Date)]) + + Functions are most typically used in the columns clause of a select statement, and can also be labeled as well as given a type. Labeling a function is recommended so that the result can be targeted in a result row based on a diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 5153cc6f1a..ce3d575f57 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -116,6 +116,8 @@ class FunctionElement(Executable, ColumnElement, FromClause): .. seealso:: + :ref:`coretutorial_functions` - in the Core tutorial + :class:`.Function` - named SQL function. :data:`.func` - namespace which produces registered or ad-hoc @@ -131,7 +133,20 @@ class FunctionElement(Executable, ColumnElement, FromClause): _has_args = False def __init__(self, *clauses, **kwargs): - """Construct a :class:`.FunctionElement`. + r"""Construct a :class:`.FunctionElement`. + + :param \*clauses: list of column expressions that form the arguments + of the SQL function call. + + :param \**kwargs: additional kwargs are typically consumed by + subclasses. + + .. seealso:: + + :data:`.func` + + :class:`.Function` + """ args = [_literal_as_binds(c, self.name) for c in clauses] self._has_args = self._has_args or bool(args) @@ -466,7 +481,80 @@ class FunctionAsBinary(BinaryExpression): class _FunctionGenerator(object): - """Generate :class:`.Function` objects based on getattr calls.""" + """Generate SQL function expressions. + + :data:`.func` is a special object instance which generates SQL + functions based on name-based attributes, e.g.:: + + >>> print(func.count(1)) + count(:param_1) + + The returned object is an instance of :class:`.Function`, and is a + column-oriented SQL element like any other, and is used in that way:: + + >>> print(select([func.count(table.c.id)])) + SELECT count(sometable.id) FROM sometable + + 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:: + + >>> 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) + + 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 + wrapped inside of a SELECT statement first:: + + print(connection.execute(func.current_timestamp()).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. + + 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`. + + .. note:: + + The :data:`.func` construct has only limited support for calling + standalone "stored procedures", especially those with special + parameterization concerns. + + See the section :ref:`stored_procedures` for details on how to use + the DBAPI-level ``callproc()`` method for fully traditional stored + procedures. + + .. seealso:: + + :ref:`coretutorial_functions` - in the Core Tutorial + + :class:`.Function` + + """ def __init__(self, **opts): self.__names = [] @@ -514,86 +602,37 @@ class _FunctionGenerator(object): func = _FunctionGenerator() -"""Generate SQL function expressions. - - :data:`.func` is a special object instance which generates SQL - functions based on name-based attributes, e.g.:: - - >>> print(func.count(1)) - count(:param_1) - - The element is a column-oriented SQL element like any other, and is - used in that way:: - - >>> print(select([func.count(table.c.id)])) - SELECT count(sometable.id) FROM sometable - - 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:: - - >>> 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) +func.__doc__ = _FunctionGenerator.__doc__ - 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: +modifier = _FunctionGenerator(group=False) - >>> 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) - 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 - wrapped inside of a SELECT statement first:: +class Function(FunctionElement): + r"""Describe a named SQL function. - print(connection.execute(func.current_timestamp()).scalar()) + The :class:`.Function` object is typically generated from the + :data:`.func` generation object. - 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. - 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`. + :param \*clauses: list of column expressions that form the arguments + of the SQL function call. - .. note:: + :param type_: optional :class:`.TypeEngine` datatype object that will be + used as the return value of the column expression generated by this + function call. - The :data:`.func` construct has only limited support for calling - standalone "stored procedures", especially those with special - parameterization concerns. - - See the section :ref:`stored_procedures` for details on how to use - the DBAPI-level ``callproc()`` method for fully traditional stored - procedures. - -""" - -modifier = _FunctionGenerator(group=False) + :param packagenames: a string which indicates package prefix names + to be prepended to the function name when the SQL is generated. + The :data:`.func` generator creates these when it is called using + dotted format, e.g.:: + func.mypackage.some_function(col1, col2) -class Function(FunctionElement): - """Describe a named SQL function. - - See the superclass :class:`.FunctionElement` for a description - of public methods. .. seealso:: + :ref:`coretutorial_functions` + :data:`.func` - namespace which produces registered or ad-hoc :class:`.Function` instances.