diff options
Diffstat (limited to 'lib/sqlalchemy/sql/functions.py')
| -rw-r--r-- | lib/sqlalchemy/sql/functions.py | 72 |
1 files changed, 52 insertions, 20 deletions
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 902811037..6ba873e7f 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -189,7 +189,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): construct, except no FROM clause is generated; the function is rendered in the similar way as a scalar subquery. - E.g.:: + E.g.: + + .. sourcecode:: pycon+sql >>> from sqlalchemy import func, select >>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key") @@ -214,7 +216,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): r"""Return a :class:`_sql.TableValuedAlias` representation of this :class:`_functions.FunctionElement` with table-valued expressions added. - e.g.:: + e.g.: + + .. sourcecode:: pycon+sql >>> fn = ( ... func.generate_series(1, 5). @@ -223,15 +227,17 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): >>> print(select(fn)) {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step - FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1 + FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop} >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2)) {printsql}SELECT anon_1.value, anon_1.stop FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1 - WHERE anon_1.value > :value_1 + WHERE anon_1.value > :value_1{stop} A WITH ORDINALITY expression may be generated by passing the keyword - argument "with_ordinality":: + argument "with_ordinality": + + .. sourcecode:: pycon+sql >>> fn = func.generate_series(4, 1, -1).table_valued("gen", with_ordinality="ordinality") >>> print(select(fn)) @@ -296,7 +302,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): """Return this :class:`_functions.FunctionElement` as a column expression that selects from itself as a FROM clause. - E.g.:: + E.g.: + + .. sourcecode:: pycon+sql >>> from sqlalchemy import select, func >>> gs = func.generate_series(1, 5, -1).column_valued() @@ -336,7 +344,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): r"""The set of columns exported by this :class:`.FunctionElement`. This is a placeholder collection that allows the function to be - placed in the FROM clause of a statement:: + placed in the FROM clause of a statement: + + .. sourcecode:: pycon+sql >>> from sqlalchemy import column, select, func >>> stmt = select(column('x'), column('y')).select_from(func.myfunction()) @@ -583,7 +593,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): :meth:`_functions.FunctionElement.table_valued` method first to establish named columns. - e.g.:: + e.g.: + + .. sourcecode:: pycon+sql >>> from sqlalchemy import func, select, column >>> data_view = func.unnest([1, 2, 3]).alias("data_view") @@ -592,7 +604,9 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): FROM unnest(:unnest_1) AS data_view The :meth:`_functions.FunctionElement.column_valued` method provides - a shortcut for the above pattern:: + a shortcut for the above pattern: + + .. sourcecode:: pycon+sql >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view") >>> print(select(data_view)) @@ -763,13 +777,17 @@ class _FunctionGenerator: """Generate SQL function expressions. :data:`.func` is a special object instance which generates SQL - functions based on name-based attributes, e.g.:: + functions based on name-based attributes, e.g.: + + .. sourcecode:: pycon+sql >>> print(func.count(1)) - count(:param_1) + {printsql}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:: + column-oriented SQL element like any other, and is used in that way: + + .. sourcecode:: pycon+sql >>> print(select(func.count(table.c.id))) {printsql}SELECT count(sometable.id) FROM sometable @@ -777,13 +795,17 @@ class _FunctionGenerator: 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:: + function* which will be compiled appropriately to the target database: + + .. sourcecode:: pycon+sql >>> print(func.current_timestamp()) {printsql}CURRENT_TIMESTAMP To call functions which are present in dot-separated packages, - specify them in the same manner:: + specify them in the same manner: + + .. sourcecode:: pycon+sql >>> print(func.stats.yield_curve(5, 10)) {printsql}stats.yield_curve(:yield_curve_1, :yield_curve_2) @@ -794,6 +816,8 @@ class _FunctionGenerator: treated as a string in expressions, specify :class:`~sqlalchemy.types.Unicode` as the type: + .. sourcecode:: pycon+sql + >>> print(func.my_string(u'hi', type_=Unicode) + ' ' + ... func.my_string(u'there', type_=Unicode)) {printsql}my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3) @@ -1048,10 +1072,12 @@ class GenericFunction(Function[_T]): identifier = "buffer" inherit_cache = True - The above function will render as follows:: + The above function will render as follows: + + .. sourcecode:: pycon+sql >>> print(func.geo.buffer()) - ST_Buffer() + {printsql}ST_Buffer() The name will be rendered as is, however without quoting unless the name contains special characters that require quoting. To force quoting @@ -1067,10 +1093,12 @@ class GenericFunction(Function[_T]): identifier = "buffer" inherit_cache = True - The above function will render as:: + The above function will render as: + + .. sourcecode:: pycon+sql >>> print(func.geo.buffer()) - "ST_Buffer"() + {printsql}"ST_Buffer"() .. versionadded:: 1.3.13 The :class:`.quoted_name` construct is now recognized for quoting when used with the "name" attribute of the @@ -1247,14 +1275,18 @@ class now(GenericFunction[datetime.datetime]): class concat(GenericFunction[str]): """The SQL CONCAT() function, which concatenates strings. - E.g.:: + E.g.: + + .. sourcecode:: pycon+sql >>> print(select(func.concat('a', 'b'))) {printsql}SELECT concat(:concat_2, :concat_3) AS concat_1 String concatenation in SQLAlchemy is more commonly available using the Python ``+`` operator with string datatypes, which will render a - backend-specific concatenation operator, such as :: + backend-specific concatenation operator, such as : + + .. sourcecode:: pycon+sql >>> print(select(literal("a") + "b")) {printsql}SELECT :param_1 || :param_2 AS anon_1 |