codekingpro/portable-devtools

1�

2��j�
�
�r�%SrS
SK
Jr S
SKrS
SKrS
SKJr S
SKJr S
SKJr S
SKJ	r	 S
SKJ3r4 S
S	KJr S
S5KJr S
SKJ
r
 S
SKJr S
S
KJr S
SKJr S
SKJr S
SKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJr SSKJ r  SSKJ!r! SSKJ"r" SSKJ#r# SSKJ$r$ SS K%J&r& SS!K%J'r' SS"K%J(r( SS#K%J)r) SS$K%J*r* SS%K%J+r+ SS&K%J,r, SS'K%J-r- SS(K%J.r. SS)K%J/r/ SS*K%J0r0 SS+K%J1r1 SS,K%J2r2 SS-K3J4r4 SS.K3J5r5 SS/K3J6r6 SS0KJ7r7 SS1KJ8r8 SS2K9J:r: S3SKJr S3S4K;J<r< \(a`SS5KJ=r= SS6KJ>r> SS7KJ?r? SS8KJ@r@ SS9KJArA SS:KJBrB SS;KJCrC SS<K%JDrD SS=K%JErE SS>K%JFrF SS?KJGrG S3S@KHJIrI S3SAKJJKrK S3SBKLJMrM S3SCKLJNrN S3SDK;JOrO \"SE\SF9rP\"SG\SF9rQ\R�"\S5
rTSH\USI'S�S�SJjj
rV"SKSL\"\+\P\4\#5rW"SMSN\'\5rX"SOSP\0\P5rY"SQSR5rZ\Z"5r[\ZR\[l\Z"SSST9
r\"SUSV\W\P5r]"SWSX\]\P5r^\V"SY\)5 \V"SZ\,5 "S[S\\^\_5r`"S]S^\^\P5ra"S_S`\^\P5rb"SaSb\b\P5rc"ScSd\c\P5rd"SeSf\b\P5re"SgSh\b\P5rf"SiSj\b\P5rg"SkSl\^\R5rh"SmSn\^\i5rj"SoSp\^\_5rk"SqSr\^\l5rm"SsSt\^\_5rn"SuSv\a\R�5rp"SwSx\a\R�5rr"SySz\a\R5rs"S{S|\a\i5rt"S}S~\a\R5ru"SS�\a\R5rv"S�S�\a\i5rw"S�S�\a\R5rx"S�S�\a\i5ry"S�S�\b\
\P5rz"S�S�\^\P5r{"S�S�\{\P5r|"S�S�\{\P5r}"S�S�\{\P5r~"S�S�\^\_5r"S�S�\^\_5r�"S�S�\^\G
R5r�"S�S�\^\G
R5r�"S�S�\^\P5r�"S�S�\^\P5r�"S�S�\^\P5r�"S�S�\^\i5r�\�r�S�\US�'\a\Pr�S�\US�'\z\Pr�S�\US�'\)\Pr�S�\US�'\kr�S�\US�'\d\Pr�S�\US�'\jr�S�\US�'\nr�S�\US�'\�\Pr�S�\US�'\�r�S�\US�'\pr�S�\US�'\rr�S�\US�'\sr�S�\US�'\tr�S�\US�'\�r�S�\US�'\,r�S�\US�'\�\Pr�S�\US�'\ur�S�\US�'\vr�S�\US�'\e\Pr�S�\US�'\f\Pr�S�\US�'\|\Pr�S�\US�'\`r�S�\US�'\hr�S�\US�'\{\Pr�S�\US�'\�r�S�\US�'\}\Pr�S�\US�'\~\Pr�S�\US�'\mr�S�\US�'\r�S�\US�'\�\Pr�S�\US�'\wr�S�\US�'\g\Pr�S�\US�'\xr�S�\US�'\yr�S�\US�'g)�z4SQL function API, factories, and built-in functions.�)
�annotationsN)
�Any)
�cast)
�Dict)
�List)
�Mapping)
�Optional)
�overload)
�Sequence)
�Tuple)
�Type)
�
TYPE_CHECKING)
�TypeVar)
�Union�
)
�6annotation)
�	coercions)
�	operators)
�roles)
�schema)
�sqltypes)
�type_api)
�util)
�is_table_value_type)
�_entity_namespace)
�ColumnCollection)
�7Executable)
�8Generative)
�HasMemoized)
�_type_from_args)
�BinaryExpression)
�
BindParameter)
�Cast)
�9ClauseList)
�
ColumnElement)
�Extract�
�FunctionFilter)
�Grouping)
�literal_column)
�NamedColumn�
�Over�
�WithinGroup)
�10FromClause)
�Select)
�TableValuedAlias)
�TableValueType)
�11TypeEngine)
�InternalTraversal�)
�	TypeAlias)
�_ByArgument)
�_ColumnExpressionArgument)
�"_ColumnExpressionOrLiteralArgument)
�#_ColumnExpressionOrStrLabelArgument)
�12_StarOrOne)
�_TypeEngineArgument)
�_EntityNamespace)
�
ClauseElement)
�KeyedColumnElement)
�TableValuedColumn)
�OperatorType)
�13Connection)
�CursorResult)
�_CoreMultiExecuteParams)
�CoreExecuteOptionsParameter)
�Self�_T)
�bound�_Sz5util.defaultdict[str, Dict[str, Type[Function[Any]]]]�	_registryc
��[Un[U5
R5nX;a%[R"S
RU5
5
 XU'g)z�Associate a callable with a particular func. name.14 15This is normally called by GenericFunction, but is also16available by itself so that a non-Function construct17can be associated with the :data:`.func` accessor (i.e.18CAST, EXTRACT).19 20zMThe GenericFunction '{}' is already registered and is going to be overridden.N)rK�str�lowerr�warn�format)�21identifier�fn�package�regs    �^D:\code\apps\devtools\python\user_packages\Python313\site-packages\sqlalchemy/sql/functions.py�register_functionrVZsL���G�22�C��Z��&�&�(�J����	�	�

)�)/��23�);�	24��25�O�c
�@^�\r
SrS
r%SrS\R4S\R4S\R4/\	R-rSrS\
S'S	rS	rS26rS\
S'S\
S
'S\
S'S\
S'S*SjrS27r\S+U4
Sjj5rS,SjrS-S.Sjj
rS/SjrS0S1Sjj
r\R4S2Sj5r\R8S2Sj5r\S3Sj5r\S2Sj5r\ RBS4Sj5r"S28S29S30S31S32S.S5Sjjr#S6Sjr$\%S7Sj5r&\%S8Sj5r&S9S jr&S:S!jr'\S+S"j5r(S;S#jr)S0S<S$jj
r*S=S%jr+S0S>S&jj
r,S-S?U4
S'jjj
r-\S@S(j5r.S)r/U=
r0$)A�FunctionElement�rahBase for SQL function-oriented constructs.33 34This is a `generic type <https://peps.python.org/pep-0484/#generics>`_,35meaning that type checkers and IDEs can be instructed on the types to36expect in a :class:`_engine.Result` for this function. See37:class:`.GenericFunction` for an example of how this is done.38 39.. seealso::40 41    :ref:`tutorial_functions` - in the :ref:`unified_tutorial`42 43    :class:`.Function` - named SQL function.44 45    :data:`.func` - namespace which produces registered or ad-hoc46    :class:`.Function` instances.47 48    :class:`.GenericFunction` - allows creation of registered function49    types.50 51�clause_expr�_with_ordinality�_table_value_type�zTuple[str, ...]�packagenamesFNzOptional[TableValueType]r�primary_key�_is_clone_ofz
Grouping[Any]c

�$
�U
Vs/sH3n[R"[RU[	US
S5US9PM5 nnUR52=
(d [
U5
Ul[[U[RSS.6
5
Ulgs snf)a
Construct a :class:`.FunctionElement`.53 54:param \*clauses: list of column expressions that form the arguments55 of the SQL function call.56 57:param \**kwargs:  additional kwargs are typically consumed by58 subclasses.59 60.. seealso::61 62    :data:`.func`63 64    :class:`.Function`65 66�nameN�rc�apply_propagate_attrsT��operator�group_contents)r�expectr�ExpressionElementRole�getattr�	_has_args�boolr)r$r�comma_opr[)�self�clauses�
c�argss    rU�__init__�FunctionElement.__init__�s���2�:67��
�

����+�+���T�6�4�0�&*�	
��	
�:68����5�4��:���#��$�	� 2� 2�4�O�69����:70s�:B
c

�@>
�[T
U]=
(d
 [US
S5$)Nrc)�super�71_proxy_keyrk)ro�	__class__s �rUrw�FunctionElement._proxy_key�s����w�!�@�W�T�6�4�%@�@rWc
�&�U
R
XU5$�
N)
�_execute_function)ro�72connection�distilled_params�execution_optionss    rU�_execute_on_connection�&FunctionElement._execute_on_connection�s���+�+��$5�73�	74rWc
��[
X
U5$)
aReturn a column expression that's against this75:class:`_functions.FunctionElement` as a scalar76table-valued expression.77 78The returned expression is similar to that returned by a single column79accessed off of a :meth:`_functions.FunctionElement.table_valued`80construct, except no FROM clause is generated; the function is rendered81in the similar way as a scalar subquery.82 83E.g.:84 85.. sourcecode:: pycon+sql86 87    >>> from sqlalchemy import func, select88    >>> fn = func.jsonb_each("{'k', 'v'}").scalar_table_valued("key")89    >>> print(select(fn))90    {printsql}SELECT (jsonb_each(:jsonb_each_1)).key91 92.. versionadded:: 1.4.0b293 94.. seealso::95 96    :meth:`_functions.FunctionElement.table_valued`97 98    :meth:`_functions.FunctionElement.alias`99 100    :meth:`_functions.FunctionElement.column_valued`101 102)
�ScalarFunctionColumn)rorc�type_s   rU�scalar_table_valued�#FunctionElement.scalar_table_valued�s��B
$�D��6�6rWc

���UR
5nURS
S5nURSS5nURSS5nU(aX4
-
n
SUl[U
6=
UlUlUR
XeS9$)a�
Return a :class:`_sql.TableValuedAlias` representation of this103:class:`_functions.FunctionElement` with table-valued expressions added.104 105e.g. to use the SQLite form of ``generate_series()`` (including106hidden columns "start", "stop", "step"):107 108.. sourcecode:: pycon+sql109 110    >>> fn = func.generate_series(1, 5).table_valued(111    ...     "value", "start", "stop", "step"112    ... )113 114    >>> print(select(fn))115    {printsql}SELECT anon_1.value, anon_1.start, anon_1.stop, anon_1.step116    FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1{stop}117 118    >>> print(select(fn.c.value, fn.c.stop).where(fn.c.value > 2))119    {printsql}SELECT anon_1.value, anon_1.stop120    FROM generate_series(:generate_series_1, :generate_series_2) AS anon_1121    WHERE anon_1.value > :value_1{stop}122 123Backends like PostgreSQL need the accessed columns to be explicitly124named in "AS" clause.  To achieve this, use125:meth:`_sql.TableValuedAlias.render_derived`; be sure to consult the126:ref:`PostgreSQL-specific documentation for table valued functions127<postgresql_table_valued>` for additional examples:128 129.. sourcecode:: pycon+sql130 131    >>> fn = func.generate_series(1, 5).table_valued("value").render_derived()132 133    >>> print(select(fn))134    {printsql}SELECT anon_1.value FROM135    generate_series(:generate_series_1, :generate_series_2) AS anon_1(value){stop}136 137A WITH ORDINALITY expression may be generated by passing the keyword138argument :paramref:`.FunctionElement.table_valued.with_ordinality`,139illustrated below using PostgreSQL's syntax:140 141.. sourcecode:: pycon+sql142 143    >>> fn = func.generate_series(4, 1, -1).table_valued(144    ...     "gen", with_ordinality="ordinality"145    ... )146    >>> print(select(fn.render_derived()))147    {printsql}SELECT anon_1.gen, anon_1.ordinality148    FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3)149    WITH ORDINALITY AS anon_1(gen, ordinality)150 151:param \*expr: A series of string column names that will be added to the152 ``.c`` collection of the resulting :class:`_sql.TableValuedAlias`153 construct as columns.  :func:`_sql.column` objects with or without154 datatypes may also be used.155 156:param name: optional name to assign to the alias name that's generated.157 If omitted, a unique anonymizing name is used.158 159:param with_ordinality: string name that when present results in the160 ``WITH ORDINALITY`` clause being added to the alias, and the given161 string name will be added as a column to the .c collection162 of the resulting :class:`_sql.TableValuedAlias`.163 164:param joins_implicitly: when True, the table valued function may be165 used in the FROM clause without any explicit JOIN to other tables166 in the SQL query, and no "cartesian product" warning will be generated.167 May be useful for SQL functions such as ``func.json_each()``.168 169 .. versionadded:: 1.4.33170 171.. versionadded:: 1.4.0b2172 173 174.. seealso::175 176    :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial`177 178    :ref:`Table-Valued Functions on PostgreSQL <postgresql_table_valued>` - in the :ref:`postgresql_toplevel` documentation179 180    :meth:`_functions.FunctionElement.scalar_table_valued` - variant of181    :meth:`_functions.FunctionElement.table_valued` which delivers the182    complete table valued expression as a scalar column expression183 184    :meth:`_functions.FunctionElement.column_valued`185 186    :meth:`_sql.TableValuedAlias.render_derived` - renders the alias187    using a derived column clause, e.g. ``AS name(col1, col2, ...)``188 189�with_ordinalityN�joins_implicitlyrcT�rcr�)�	_generate�popr\r3�typer]�alias)ro�expr�kw�new_funcr�r�rcs       rU�table_valued�FunctionElement.table_valued�s��x�>�>�#���&�&�!2�D�9���6�6�"4�d�;���v�v�f�d�#����&�&�D�(,�H�%�5C�T�5J�J��
��2��~�~�4�~�K�KrWc
�4�UR
XS
9R$)a�Return this :class:`_functions.FunctionElement` as a column expression that190selects from itself as a FROM clause.191 192E.g.:193 194.. sourcecode:: pycon+sql195 196    >>> from sqlalchemy import select, func197    >>> gs = func.generate_series(1, 5, -1).column_valued()198    >>> print(select(gs))199    {printsql}SELECT anon_1200    FROM generate_series(:generate_series_1, :generate_series_2, :generate_series_3) AS anon_1201 202This is shorthand for::203 204    gs = func.generate_series(1, 5, -1).alias().column205 206:param name: optional name to assign to the alias name that's generated.207 If omitted, a unique anonymizing name is used.208 209:param joins_implicitly: when True, the "table" portion of the column210 valued function may be a member of the FROM clause without any211 explicit JOIN to other tables in the SQL query, and no "cartesian212 product" warning will be generated. May be useful for SQL functions213 such as ``func.json_array_elements()``.214 215 .. versionadded:: 1.4.46216 217.. seealso::218 219    :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial`220 221    :ref:`postgresql_column_valued` - in the :ref:`postgresql_toplevel` documentation222 223    :meth:`_functions.FunctionElement.table_valued`224 225r�)r��column�rorcr�s   rU�
column_valued�FunctionElement.column_valuedX
s��R
�z�z�t�z�G�N�N�NrWc


��UR$)
a�The set of columns exported by this :class:`.FunctionElement`.226 227This is a placeholder collection that allows the function to be228placed in the FROM clause of a statement:229 230.. sourcecode:: pycon+sql231 232    >>> from sqlalchemy import column, select, func233    >>> stmt = select(column("x"), column("y")).select_from(func.myfunction())234    >>> print(stmt)235    {printsql}SELECT x, y FROM myfunction()236 237The above form is a legacy feature that is now superseded by the238fully capable :meth:`_functions.FunctionElement.table_valued`239method; see that method for details.240 241.. seealso::242 243    :meth:`_functions.FunctionElement.table_valued` - generates table-valued244    SQL function expressions.245 246)
rq�
ros
 rU�columns�FunctionElement.columns�
s
��0�v�v�
rWc

�j�[
URV
s/sHoRU
4PM sn
S
9
$s sn
f)z-synonym for :attr:`.FunctionElement.columns`.�
r�)r�_all_selected_columns�key)ro�cols  rUrq�FunctionElement.c�
s4�� �/3�/I�/I�J�/I��g�g�s�^�/I�J�247�	248��Js�0c

��[
UR5
(a"[S
URR5n
U
$UR	S5
/
n
U
$)N�!Sequence[KeyedColumnElement[Any]])rr�r�	_elements�label)ro�colss  rUr��%FunctionElement._all_selected_columns�
sI���t�y�y�)�)��3�T�Y�Y�5H�5H��D����J�J�t�$�%�D��rWc


��UR$r{r�r�s
 rU�exported_columns� FunctionElement.exported_columns�
s���|�|�rWc

�J�[
[URR5$)
zmReturn the underlying :class:`.ClauseList` which contains249the arguments for this :class:`.FunctionElement`.250 251)rr$r[�elementr�s
 rUrp�FunctionElement.clauses�
s���J�� 0� 0� 8� 8�9�9rW��partition_by�order_by�rows�range_�groupsc
	
��[
UU
UUUUS
9$)a�
Produce an OVER clause against this function.252 253Used against aggregate or so-called "window" functions,254for database backends that support window functions.255 256The expression::257 258    func.row_number().over(order_by="x")259 260is shorthand for::261 262    from sqlalchemy import over263 264    over(func.row_number(), order_by="x")265 266See :func:`_expression.over` for a full description.267 268.. seealso::269 270    :func:`_expression.over`271 272    :ref:`tutorial_window_functions` - in the :ref:`unified_tutorial`273 274r�r,)ror�r�r�r�r�s      rU�over�FunctionElement.over�
s$��B
��%�����
275�	276rWc

��[
U/
U
Q
76$)
a�
Produce a WITHIN GROUP (ORDER BY expr) clause against this function.277 278Used against so-called "ordered set aggregate" and "hypothetical279set aggregate" functions, including :class:`.percentile_cont`,280:class:`.rank`, :class:`.dense_rank`, etc.281 282See :func:`_expression.within_group` for a full description.283 284.. seealso::285 286    :ref:`tutorial_functions_within_group` -287    in the :ref:`unified_tutorial`288 289 290r.)ror�s  rU�within_group�FunctionElement.within_group�
s��$�4�+�(�+�+rWc


��gr{r^r�s
 rU�filter�FunctionElement.filter�
s��!rWc

��gr{r^)ro�_FunctionElement__criterion0�	criterions   rUr�r�s��291!rWc

�,�U
(dU$[
U/
U
Q
76$)
a�
Produce a FILTER clause against this function.292 293Used against aggregate and window functions,294for database backends that support the "FILTER" clause.295 296The expression::297 298    func.count(1).filter(True)299 300is shorthand for::301 302    from sqlalchemy import funcfilter303 304    funcfilter(func.count(1), True)305 306.. seealso::307 308    :ref:`tutorial_functions_within_group` -309    in the :ref:`unified_tutorial`310 311    :class:`.FunctionFilter`312 313    :func:`.funcfilter`314 315 316r')ror�s  rUr�r�s��:��K��d�/�Y�/�/rWc
��[
X
U5$)
a�	Interpret this expression as a boolean comparison between two317values.318 319This method is used for an ORM use case described at320:ref:`relationship_custom_operator_sql_function`.321 322A hypothetical SQL function "is_equal()" which compares to values323for equality would be written in the Core expression language as::324 325    expr = func.is_equal("a", "b")326 327If "is_equal()" above is comparing "a" and "b" for equality, the328:meth:`.FunctionElement.as_comparison` method would be invoked as::329 330    expr = func.is_equal("a", "b").as_comparison(1, 2)331 332Where above, the integer value "1" refers to the first argument of the333"is_equal()" function and the integer value "2" refers to the second.334 335This would create a :class:`.BinaryExpression` that is equivalent to::336 337    BinaryExpression("a", "b", operator=op.eq)338 339However, at the SQL level it would still render as340"is_equal('a', 'b')".341 342The ORM, when it loads a related object or collection, needs to be able343to manipulate the "left" and "right" sides of the ON clause of a JOIN344expression. The purpose of this method is to provide a SQL function345construct that can also supply this information to the ORM, when used346with the :paramref:`_orm.relationship.primaryjoin` parameter. The347return value is a containment object called :class:`.FunctionAsBinary`.348 349An ORM example is as follows::350 351    class Venue(Base):352        __tablename__ = "venue"353        id = Column(Integer, primary_key=True)354        name = Column(String)355 356        descendants = relationship(357            "Venue",358            primaryjoin=func.instr(359                remote(foreign(name)), name + "/"360            ).as_comparison(1, 2)361            == 1,362            viewonly=True,363            order_by=name,364        )365 366Above, the "Venue" class can load descendant "Venue" objects by367determining if the name of the parent Venue is contained within the368start of the hypothetical descendant value's name, e.g. "parent1" would369match up to "parent1/child1", but not to "parent2/child1".370 371Possible use cases include the "materialized path" example given above,372as well as making use of special SQL functions such as geometric373functions to create join conditions.374 375:param left_index: the integer 1-based index of the function argument376 that serves as the "left" side of the expression.377:param right_index: the integer 1-based index of the function argument378 that serves as the "right" side of the expression.379 380.. versionadded:: 1.3381 382.. seealso::383 384    :ref:`relationship_custom_operator_sql_function` -385    example use within the ORM386 387)
�FunctionAsBinary)ro�388left_index�right_indexs   rU�
as_comparison�FunctionElement.as_comparison(s��V ��+�>�>rWc


�.�URR$r{)rp�
_from_objectsr�s
 rUr��FunctionElement._from_objectsus���|�|�)�)�)rWc

��g
)z�For types that define their return type as based on the criteria389within a WITHIN GROUP (ORDER BY) expression, called by the390:class:`.WithinGroup` construct.391 392Returns None by default, in which case the function's normal ``.type``393is used.394 395Nr^)ror�s  rU�within_group_type�!FunctionElement.within_group_typeys��rWc
�D�[R"UU
URUS
9$)a�Produce a :class:`_expression.Alias` construct against this396:class:`.FunctionElement`.397 398.. tip::399 400    The :meth:`_functions.FunctionElement.alias` method is part of the401    mechanism by which "table valued" SQL functions are created.402    However, most use cases are covered by higher level methods on403    :class:`_functions.FunctionElement` including404    :meth:`_functions.FunctionElement.table_valued`, and405    :meth:`_functions.FunctionElement.column_valued`.406 407This construct wraps the function in a named alias which408is suitable for the FROM clause, in the style accepted for example409by PostgreSQL.  A column expression is also provided using the410special ``.column`` attribute, which may411be used to refer to the output of the function as a scalar value412in the columns or where clause, for a backend such as PostgreSQL.413 414For a full table-valued expression, use the415:meth:`_functions.FunctionElement.table_valued` method first to416establish named columns.417 418e.g.:419 420.. sourcecode:: pycon+sql421 422    >>> from sqlalchemy import func, select, column423    >>> data_view = func.unnest([1, 2, 3]).alias("data_view")424    >>> print(select(data_view.column))425    {printsql}SELECT data_view426    FROM unnest(:unnest_1) AS data_view427 428The :meth:`_functions.FunctionElement.column_valued` method provides429a shortcut for the above pattern:430 431.. sourcecode:: pycon+sql432 433    >>> data_view = func.unnest([1, 2, 3]).column_valued("data_view")434    >>> print(select(data_view))435    {printsql}SELECT data_view436    FROM unnest(:unnest_1) AS data_view437 438.. versionadded:: 1.4.0b2  Added the ``.column`` accessor439 440:param name: alias name, will be rendered as ``AS <name>`` in the441 FROM clause442 443:param joins_implicitly: when True, the table valued function may be444 used in the FROM clause without any explicit JOIN to other tables445 in the SQL query, and no "cartesian product" warning will be446 generated.  May be useful for SQL functions such as447 ``func.json_each()``.448 449 .. versionadded:: 1.4.33450 451.. seealso::452 453    :ref:`tutorial_functions_table_valued` -454    in the :ref:`unified_tutorial`455 456    :meth:`_functions.FunctionElement.table_valued`457 458    :meth:`_functions.FunctionElement.scalar_table_valued`459 460    :meth:`_functions.FunctionElement.column_valued`461 462 463)rc�table_value_typer�)r2�464_constructr�r�s   rUr��FunctionElement.alias�s(��R �*�*���!�Y�Y�-�	465�	466rWc

�v�[
U5
n
UR(aU
R"S
0URD
6
n
U
$)z�Produce a :func:`_expression.select` construct467against this :class:`.FunctionElement`.468 469This is shorthand for::470 471    s = select(function_element)472 473r^)r1�_execution_optionsr)ro�
ss  rU�select�FunctionElement.select�s4�� ���
��"�"��#�#�>�d�&=�&=�>�A��rWc	
�<�[
SU4U
URS
UUS.UD
6
$)NT)�_compared_to_operator�_compared_to_type�uniquer��	expanding)r"r��rorg�objr�r�r�s      rU�_bind_param�FunctionElement._bind_param�s;�����	474�#+�"�i�i����	475��	476�		477rWc
�>
�U
[RLa4[UR[R4785(a[
U5
$[TU]!U
S
9
$)N)
�against)	r�getitem�479isinstancer�r�ARRAYr)rv�480self_group)ror�rxs  �rUr��FunctionElement.self_group�sK���481�i�'�'�'�J��I�I�x�~�~�-482�-483��D�>�!��7�%�g�%�6�6rWc

�,�[
UR5
$)
zjoverrides FromClause.entity_namespace as functions are generally484column expressions and not FromClauses.485 486)rr[r�s
 rU�entity_namespace� FunctionElement.entity_namespaces��!��!1�!1�2�2rW)rlr[)rp�'_ColumnExpressionOrLiteralArgument[Any]�return�None�r�r)r}rCr~rErrFr�zCursorResult[Any]r{)rcrMr��!Optional[_TypeEngineArgument[_T]]r�zScalarFunctionColumn[_T])r�z(_ColumnExpressionOrStrLabelArgument[Any]r�rr�r2�NF)rc�
Optional[str]r�rmr�zTableValuedColumn[_T])r�z.ColumnCollection[str, KeyedColumnElement[Any]])r�r�)r�r$)r��Optional[_ByArgument]r�r�r��-Optional[Tuple[Optional[int], Optional[int]]]r�r�r�r�r�zOver[_T])r��_ColumnExpressionArgument[Any]r�zWithinGroup[_T])r�rG)r��_ColumnExpressionArgument[bool]r�r�r�zFunctionFilter[_T])r�r�r�zUnion[Self, FunctionFilter[_T]])r��intr�r�r�r�)r�zWithinGroup[_S]r�zOptional[TypeEngine[_S]])rcr�r�rmr�r2)r�zSelect[Tuple[_T]]�rgrBr�rr�zOptional[TypeEngine[_T]]r�rmr�rr�zBindParameter[_T])r�zOptional[OperatorType]r�r?)r�r>)1�__name__�487__module__�__qualname__�__firstlineno__�__doc__r5�dp_clauseelement�488dp_boolean�dp_has_cache_keyr�_executable_traverse_internals�_traverse_internalsr_�__annotations__rlr\r]rs�_non_anon_label�propertyrwr�r�r�r�r�ro_non_memoized_propertyr��ro_memoized_propertyrqr�r�r�memoized_attributerpr�r�r489r�r�r�r�r�r�r�r�r��__static_attributes__�
__classcell__�
rxs
@rUrYrYrsn����,490�)�:�:�;�	�.�9�9�:�	�/�@�@�A��	�1�1�	2��%'�L�/�&��I���26��/�6�������491�?�492�	
�493�@
�O�
�
A
��
A
�494��495�2�496�7�	497�498499�500�E
I
�!7��!7� A�!7�	!�!7�F
h
L
�=�h
L
�EH�h
L
�	�h
L
�VD
I
�)O
�!�)O
�<@�)O
�	�)O
�V
501�"�"��#��2502���503��504��	��	���	7����505�#�#�:�$�:�/3�*.�>B�@D�@D�(506�,�(507�(�	(508�509<�(510�>�
(511�>�(512�513�(514�T
,�7�,�	�,�(�!��!�
�!�5�!�4�!�515�	!��!�0�9�0�	(�0�B
K
?��K
?�,/�K
?�	�K
?�Z�
*��
*��+��	!��D
I
�N
516�!�N
517�<@�N
518�	�N
519�`�$+/��520��521��522�(�	523�524�525��
526�527�528�&5297�5307��3��3rWrYc
�X
�\r
SrS
r%S\R5314S\R4S\R4S\R4/rS\	S'S\	S'S\	S'SSjr532SS	jr\SS533j5r
\
RSSj5r
\SSj5r\RSS
j5r\(d\
r\rSrgSrg)r�i�sql_functionr�r��	modifiers�FunctionElement[Any]r�c
�0�[R"X
U5$r{)r%�_gen_cache_key)ro�anon_map�534bindparamss   rUr
�FunctionAsBinary._gen_cache_keys���+�+�D�J�G�GrWc
���XlX l
X0l[RUl[RUlSUl	S
Ul535[R"05
Ul
g)NT)r
r�r�r�function_as_comparison_oprgr�BOOLEANTYPEr��negate�_is_implicitly_booleanr�
immutabledictr
)rorRr�r�s    rUrs�FunctionAsBinary.__init__sP����$��&��!�;�;��
��(�(��	����&*��#��+�+�B�/��rWc

�b�URRRURS
-536$�Nr�r
rpr�r�s
 rU�	left_expr�FunctionAsBinary.left_expr+s(��� � �(�(�0�0����1�1D�E�ErWc
�b�XRRRURS
-537'gr
r
�ro�values  rUr
r
/s%��AF���!�!�)�)�$�/�/�A�*=�>rWc

�b�URRRURS
-538$r
�r
rpr�r�s
 rU�539right_expr�FunctionAsBinary.right_expr3s*��� � �(�(�0�0��1A�1A�A�1E�F�FrWc
�b�XRRRURS
-540'gr
r#
r 
s  rUr$
r%
7s'��BG���!�!�)�)�$�*:�*:�Q�*>�?rW)r
r�r
r
rgr�r
r�N)r
rr
rr�r)rRr

r�r�r�r�r�r�)r��ColumnElement[Any])r!
r'
r�r�)r�r�r�r�r5r��dp_plain_obj�
dp_plain_dictr
r

r
rsr
r
�setterr$
r�left�rightr
r^rWrUr�r�s���	�*�;�;�<�	�(�5�5�6�	�)�6�6�7�	�'�5�5�6�	��'�&��O���
H
�0�&�0�47�0�FI�0�	
�0��
F
��
F
����
G
��
G
��
G
��
G
����
H
��
H
������rWr�c
��\r
SrS
rSrS\R4S\R4S\R4/r	Sr541SrS542SSjj
rS	r
g)r�iC�scalar_function_columnrcr�rRFNc
�R�XlX l
[R"U5
Ulgr{)rRrcr�to_instancer�)rorRrcr�s    rUrs�ScalarFunctionColumn.__init__Os"�����	��(�(��/��	rW)rRrcr�r{)rRzFunctionElement[_T]rcrMr�r�r�r�)r�r�r�r��__visit_name__r5�dp_anon_name�dp_typer�r
�543is_literal�tablersr
r^rWrUr�r�Cs��-�N�544�"�/�/�0�	�"�*�*�+�	
� �1�1�2����J��E�48�	0��0��0�1�	0�545546�0�0rWr�c
�z�\r
SrS
rSrS<SjrS=Sjr\S>Sj5r\S?Sj5rS?Sjr\	(Ga~\547S@Sj5r\548SAS	j5r\SBS549j5r
\SCSj5r
\SDSj5r
SES
jr
\550SFSj5r\551SGSj5r\SHSj5r\SISj5r\SJSj5rSKSjr\552SLSj5r\553SMSj5r\554SNSj5r\555SOSj5r\556SPSj5r\557SQSj5r\558SRSj5r\559SSSj5r\560STSj5r\561SUSj5r\562SVSj5r\563SWSj5r\564SXS j5r\SYS!j5r\SZS"j5r\S[S#j5rS\S$jr\S]S%j5r\S^S&j5r\S_S'j5rS`S(jr\565SaS)j5r \566SbS*j5r!\567ScS+j5r"\568SdS,j5r#\569SeS-j5r$\570SfS.j5r%\571SgS/j5r&\572ShS0j5r'\573SiS1j5r(\574SjS2j5r)\575SkS3j5r*\SlS4j5r+\SmS5j5r+\SnS6j5r+SoS7jr+\576SpS8j5r,\577SqS9j5r-S:r.g;S:r.g;)r�_FunctionGeneratori]a�Generate SQL function expressions.578 579:data:`.func` is a special object instance which generates SQL580functions based on name-based attributes, e.g.:581 582.. sourcecode:: pycon+sql583 584    >>> print(func.count(1))585    {printsql}count(:param_1)586 587The returned object is an instance of :class:`.Function`, and  is a588column-oriented SQL element like any other, and is used in that way:589 590.. sourcecode:: pycon+sql591 592    >>> print(select(func.count(table.c.id)))593    {printsql}SELECT count(sometable.id) FROM sometable594 595Any name can be given to :data:`.func`. If the function name is unknown to596SQLAlchemy, it will be rendered exactly as is. For common SQL functions597which SQLAlchemy is aware of, the name may be interpreted as a *generic598function* which will be compiled appropriately to the target database:599 600.. sourcecode:: pycon+sql601 602    >>> print(func.current_timestamp())603    {printsql}CURRENT_TIMESTAMP604 605To call functions which are present in dot-separated packages,606specify them in the same manner:607 608.. sourcecode:: pycon+sql609 610    >>> print(func.stats.yield_curve(5, 10))611    {printsql}stats.yield_curve(:yield_curve_1, :yield_curve_2)612 613SQLAlchemy can be made aware of the return type of functions to enable614type-specific lexical and result-based behavior. For example, to ensure615that a string-based function returns a Unicode value and is similarly616treated as a string in expressions, specify617:class:`~sqlalchemy.types.Unicode` as the type:618 619.. sourcecode:: pycon+sql620 621    >>> print(622    ...     func.my_string("hi", type_=Unicode)623    ...     + " "624    ...     + func.my_string("there", type_=Unicode)625    ... )626    {printsql}my_string(:my_string_1) || :my_string_2 || my_string(:my_string_3)627 628The object returned by a :data:`.func` call is usually an instance of629:class:`.Function`.630This object meets the "column" interface, including comparison and labeling631functions.  The object can also be passed the :meth:`~.Connectable.execute`632method of a :class:`_engine.Connection` or :class:`_engine.Engine`,633where it will be634wrapped inside of a SELECT statement first::635 636    print(connection.execute(func.current_timestamp()).scalar())637 638In a few exception cases, the :data:`.func` accessor639will redirect a name to a built-in expression such as :func:`.cast`640or :func:`.extract`, as these names have well-known meaning641but are not exactly the same as "functions" from a SQLAlchemy642perspective.643 644Functions which are interpreted as "generic" functions know how to645calculate their return type automatically. For a listing of known generic646functions, see :ref:`generic_functions`.647 648.. note::649 650    The :data:`.func` construct has only limited support for calling651    standalone "stored procedures", especially those with special652    parameterization concerns.653 654    See the section :ref:`stored_procedures` for details on how to use655    the DBAPI-level ``callproc()`` method for fully traditional stored656    procedures.657 658.. seealso::659 660    :ref:`tutorial_functions` - in the :ref:`unified_tutorial`661 662    :class:`.Function`663 664c

��/UlXl
gr{)�_FunctionGenerator__names�opts)ror;
s  rUrs�_FunctionGenerator.__init__�s��"$����	rWc
� 
�U
R
S
5
(aURU
$U
R	S5
(aU
SSn
[S0URD
6
n[UR5
U
/
-UlU$![a [U
5
e
f=f
)N�__�
_r�����r^)	�665startswith�__dict__�KeyError�AttributeError�endswithr8
r;
�listr:
)rorc�
fs   rU�__getattr__�_FunctionGenerator.__getattr__�s����?�?�4� � �
+��}�}�T�*�*��]�]�3�
�
��
�"�:�D��+����+�
�����&�$��/�
�	�����

+�$�T�*�*�

+�s�A7�7B
c



��gr{r^)ror�rq�kwargss    rU�__call__�_FunctionGenerator.__call__�s��rWc


��gr{r^)rorqrK
s   rUrL
rM
����ADrWc
	
�
�URR5nURU5
 [UR5
nUS
:XaURupVOUS:XaSURSpeOSnUb1[666UR
WR55
nUbU"U
0UD
6
$[URS/
U
Q
7S[URSS5
0
UD
6
$)Nr6r�_defaultrr@
r_)667r;
�copy�update�lenr:
rK�getrN�Function�tuple)rorqrK
�
o�tokensrS�fname�funcs        rUrL
rM
�s����I�I�N�N��
�	������T�\�\�"���Q�;�!�\�\�N�G�U�
�q�[�'����a��U��G����W�%�)�)�%�+�+�-�8�D����Q�}�!�}�$���L�L���668�GH�669�+0����a��1C�+D�670�LM�671�	672rWc


��gr{r^r�s
 rU�aggregate_strings�$_FunctionGenerator.aggregate_strings����FIrWc


��gr{r^r�s
 rU�ansifunction�_FunctionGenerator.ansifunction�rO
rWc

��gr{r^�ror�rrrK
s    rU�	array_agg�_FunctionGenerator.array_agg����#&rWc

��gr{r^rd
s    rUre
rf
rg
rWc

��gr{r^rd
s    rUre
rf
rg
rWc

��gr{r^rd
s    rUre
rf
s��673#&rWc


��gr{r^r�s
 rUr�_FunctionGenerator.cast���14rWc


��gr{r^r�s
 rU�char_length�_FunctionGenerator.char_lengths��:=rWc

��gr{r^rd
s    rU�coalesce�_FunctionGenerator.coalesce"���"%rWc

��gr{r^rd
s    rUrr
rs
*rt
rWc

��gr{r^rd
s    rUrr
rs
2rt
rWc

��gr{r^rd
s    rUrr
rs
:s��674"%rWc


��gr{r^r�s
 rU�concat�_FunctionGenerator.concatA���03rWc


��gr{r^r�s
 rU�count�_FunctionGenerator.countDs��.1rWc


��gr{r^r�s
 rU�cube�_FunctionGenerator.cubeGrm
rWc


��gr{r^r�s
 rU�	cume_dist�_FunctionGenerator.cume_distJ���69rWc


��gr{r^r�s
 rU�current_date�_FunctionGenerator.current_dateM���<?rWc


��gr{r^r�s
 rU�current_time�_FunctionGenerator.current_timePr�
rWc


��gr{r^r�s
 rU�current_timestamp�$_FunctionGenerator.current_timestampSr_
rWc


��gr{r^r�s
 rU�current_user�_FunctionGenerator.current_userVr�
rWc


��gr{r^r�s
 rU�675dense_rank�_FunctionGenerator.dense_rankY���8;rWc


��gr{r^r�s
 rU�extract�_FunctionGenerator.extract\���25rWc


��gr{r^r�s
 rU�
grouping_sets� _FunctionGenerator.grouping_sets_���CFrWc


��gr{r^r�s
 rU�	localtime�_FunctionGenerator.localtimebr�
rWc


��gr{r^r�s
 rU�localtimestamp�!_FunctionGenerator.localtimestampes��@CrWc

��gr{r^rd
s    rU�max�_FunctionGenerator.maxm��� rWc

��gr{r^rd
s    rUr�
r�
ur�
rWc

��gr{r^rd
s    rUr�
r�
}r�
rWc

��gr{r^rd
s    rUr�
r�
����676 rWc

��gr{r^rd
s    rU�min�_FunctionGenerator.min�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc


��gr{r^r�s
 rU�mode�_FunctionGenerator.mode�rm
rWc


��gr{r^r�s
 rU�677next_value�_FunctionGenerator.next_value�r�
rWc


��gr{r^r�s
 rU�now�_FunctionGenerator.now�s��*-rWc


��gr{r^r�s
 rU�
orderedsetagg� _FunctionGenerator.orderedsetagg�r�
rWc


��gr{r^r�s
 rU�percent_rank�_FunctionGenerator.percent_rank�r�
rWc


��gr{r^r�s
 rU�percentile_cont�"_FunctionGenerator.percentile_cont����GJrWc


��gr{r^r�s
 rU�percentile_disc�"_FunctionGenerator.percentile_disc�r�
rWc


��gr{r^r�s
 rU�random�_FunctionGenerator.random�r{
rWc


��gr{r^r�s
 rU�rank�_FunctionGenerator.rank����,/rWc


��gr{r^r�s
 rU�rollup�_FunctionGenerator.rollup�s��58rWc


��gr{r^r�s
 rU�session_user�_FunctionGenerator.session_user�r�
rWc

��gr{r^rd
s    rU�sum�_FunctionGenerator.sum�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc

��gr{r^rd
s    rUr�
r�
�r�
rWc


��gr{r^r�s
 rU�sysdate�_FunctionGenerator.sysdate�r�
rWc


��gr{r^r�s
 rU�user�_FunctionGenerator.user�r�
rW)�__namesr;
N)r;
rr�r�)rcrMr�r8
)rqrr��_TypeEngineArgument[_T]rK
rr�zFunction[_T])rqrrK
rr�z
Function[Any])r�zType[_aggregate_strings_func])r�zType[_AnsiFunction_func[Any]])r��ColumnElement[_T]rrr�rK
rr��_array_agg_func[_T])r��_ColumnExpressionArgument[_T]rrr�rK
rr�r�
)r�rHrrr�rK
rr�r�
)r��&_ColumnExpressionOrLiteralArgument[_T]rrr�rK
rr�r�
)r�zType[_Cast_func[Any]])r�zType[_char_length_func])r�r�
rrr�rK
rr��_coalesce_func[_T])r��'_ColumnExpressionArgument[Optional[_T]]rrr�rK
rr�r�
)r��Optional[_T]rrr�rK
rr�r�
)r��0_ColumnExpressionOrLiteralArgument[Optional[_T]]rrr�rK
rr�r�
)r�zType[_concat_func])r�zType[_count_func])r�zType[_cube_func[Any]])r�zType[_cume_dist_func])r�zType[_current_date_func])r�zType[_current_time_func])r�zType[_current_timestamp_func])r�zType[_current_user_func])r�zType[_dense_rank_func])r�zType[_Extract_func])r�zType[_grouping_sets_func[Any]])r�zType[_localtime_func])r�zType[_localtimestamp_func])r�r�
rrr�rK
rr��
_max_func[_T])r�r�
rrr�rK
rr�r�
)r�rHrrr�rK
rr�r�
)r�r�
rrr�rK
rr�r�
)r�r�
rrr�rK
rr��
_min_func[_T])r�r�
rrr�rK
rr�r�
)r�rHrrr�rK
rr�r�
)r�r�
rrr�rK
rr�r�
)r�zType[_mode_func[Any]])r�zType[_next_value_func])r�zType[_now_func])r�zType[_OrderedSetAgg_func[Any]])r�zType[_percent_rank_func])r�z Type[_percentile_cont_func[Any]])r�z Type[_percentile_disc_func[Any]])r�zType[_random_func])r�zType[_rank_func])r�zType[_rollup_func[Any]])r�zType[_session_user_func])r�r�
rrr�rK
rr��
_sum_func[_T])r�r�
rrr�rK
rr�r�
)r�rHrrr�rK
rr�r�
)r�r�
rrr�rK
rr�r�
)r�zType[_sysdate_func])r�zType[_user_func])/r�r�r�r�r�rsrH
r678rL
rr
r]
ra
re
rro
rr
ry
r}
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r�
r
r^rWrUr8
r8
]sR��W
�r������5��AD��	�����D��D�679�,�680�I�681�I�	�D�682�D�683�	&�"�	&�;�	&��		&�684!�	&�685�	&�686�	&�.�	&�;�	&��		&�687!�	&�688�	&�689�	&��	&�;�	&��		&�690!�	&�691�	&�	&�7�	&�;�	&��		&�692!�	&�693�4�694�4�	�=�695�=�696�	%�"�	%�;�	%��		%�697 �	%�698�	%�699�	%�8�	%�;�	%��		%�700 �	%�701�	%�702�	%��	%�;�	%��		%�703 �	%�704�	%�	%�A�	%�;�	%��		%�705 �	%�706�3�707�3�	�1�708�1�	�4�709�4�	�9�710�9�	�?�711�?�	�?�712�?�	�I�713�I�	�?�714�?�	�;�715�;�	�5�716�5�	�F�717�F�	�9�718�9�	�C�719�C�720�	 �"�	 �;�	 ��		 �721�	 �722�	 �723�	 �.�	 �;�	 ��		 �724�	 �725�	 �726�	 ��	 �;�	 ��		 �727�	 �728�	 �	 �7�	 �;�	 ��		 �729�	 �730�	 �"�	 �;�	 ��		 �731�	 �732�	 �733�	 �.�	 �;�	 ��		 �734�	 �735�	 �736�	 ��	 �;�	 ��		 �737�	 �738�	 �	 �7�	 �;�	 ��		 �739�	 �740�4�741�4�	�;�742�;�	�-�743�-�	�F�744�F�	�?�745�?�	�J�746�J�	�J�747�J�	�3�748�3�	�/�749�/�	�8�750�8�	�?�751�?�752�	 �"�	 �;�	 ��		 �753�	 �754�	 �755�	 �.�	 �;�	 ��		 �756�	 �757�	 �758�	 ��	 �;�	 ��		 �759�	 �760�	 �	 �7�	 �;�	 ��		 �761�	 �762�5�763�5�	�/�764�/�erWr8
F)
�groupc
�X
�\r
SrS
r%SrSr\RS\R4S\R4S\R4/-rS\S'S\S'S	\S'\
S765S766S.SSjj5r\
S767S768S.SS
jj5rSSS.SSjjrSSSjj
rSrg)rV
ia�Describe a named SQL function.769 770The :class:`.Function` object is typically generated from the771:data:`.func` generation object.772 773 774:param \*clauses: list of column expressions that form the arguments775 of the SQL function call.776 777:param type\_: optional :class:`.TypeEngine` datatype object that will be778 used as the return value of the column expression generated by this779 function call.780 781:param packagenames: a string which indicates package prefix names782 to be prepended to the function name when the SQL is generated.783 The :data:`.func` generator creates these when it is called using784 dotted format, e.g.::785 786    func.mypackage.some_function(col1, col2)787 788.. seealso::789 790    :ref:`tutorial_functions` - in the :ref:`unified_tutorial`791 792    :data:`.func` - namespace which produces registered or ad-hoc793    :class:`.Function` instances.794 795    :class:`.GenericFunction` - allows creation of registered function796    types.797 798�functionr_rcr�rMrQzTypeEngine[_T].)r�r_c

��gr{r^�rorcr�r_rps     rUrs�Function.__init__B���rWc

��gr{r^r�
s     rUrsr�
Kr�
rWNc
��U=
(d S
UlXl
[R"U5
Ul[799R"U/
UQ
76 g)z~Construct a :class:`.Function`.800 801The :data:`.func` construct is normally used to construct802new :class:`.Function` instances.803 804r^N)r_rcrr0
r�rYrsr�
s     rUrsr�
Ts=��)�.�B����	��(�(��/��	�� � ��0��0rWc	
�P�[
URU4U
URUS
US.UD
6
$)NT)r�r�r�r�r�)r"rcr�r�s      rUr��Function._bind_paramjs?����I�I��	805�#+�"�i�i����	806��	807�		808rW)rcr_r�)809rcrMrpr�
r�r�r_�Optional[Tuple[str, ...]]r�r�)810rcrMrpr�r�r�
r_r�
r�r�)811rcrMrpr�r�r�r_r�
r�r�r�r�)r�r�r�r�r�r2
rYr
r5r(
�	dp_stringr4
r

r812rsr�r
r^rWrUrV
rV
s�
���@
 �N�)�=�=�	�*�7�7�8�	�"�,�,�-�	�"�*�*�+�A
����I��O�813��� �814�25����9���	�8150��816�
����817*-�25����:��'�	�8180��819�
���48�26�1��1�:�1�1�	1�8200�1�821�
1�4+/��822��823��824�(�	825�826�827��
828�829�830�831rWrV
c
�~^�\r
SrS
r%SrSrSrS\S'SrS832U4
Sjjr	\833SSj5rSSjrS	r
U=
r$)
�GenericFunctioni~a<
Define a 'generic' function.834 835A generic function is a pre-established :class:`.Function`836class that is instantiated automatically when called837by name from the :data:`.func` attribute.    Note that838calling any name from :data:`.func` has the effect that839a new :class:`.Function` instance is created automatically,840given that name.  The primary use case for defining841a :class:`.GenericFunction` class is so that a function842of a particular name may be given a fixed return type.843It can also include custom argument parsing schemes as well844as additional methods.845 846Subclasses of :class:`.GenericFunction` are automatically847registered under the name of the class.  For848example, a user-defined function ``as_utc()`` would849be available immediately::850 851    from sqlalchemy.sql.functions import GenericFunction852    from sqlalchemy.types import DateTime853 854 855    class as_utc(GenericFunction):856        type = DateTime()857        inherit_cache = True858 859 860    print(select(func.as_utc()))861 862User-defined generic functions can be organized into863packages by specifying the "package" attribute when defining864:class:`.GenericFunction`.   Third party libraries865containing many functions may want to use this in order866to avoid name conflicts with other systems.   For example,867if our ``as_utc()`` function were part of a package868"time"::869 870    class as_utc(GenericFunction):871        type = DateTime()872        package = "time"873        inherit_cache = True874 875The above function would be available from :data:`.func`876using the package name ``time``::877 878    print(select(func.time.as_utc()))879 880A final option is to allow the function to be accessed881from one name in :data:`.func` but to render as a different name.882The ``identifier`` attribute will override the name used to883access the function as loaded from :data:`.func`, but will retain884the usage of ``name`` as the rendered name::885 886    class GeoBuffer(GenericFunction):887        type = Geometry()888        package = "geo"889        name = "ST_Buffer"890        identifier = "buffer"891        inherit_cache = True892 893The above function will render as follows:894 895.. sourcecode:: pycon+sql896 897    >>> print(func.geo.buffer())898    {printsql}ST_Buffer()899 900The name will be rendered as is, however without quoting unless the name901contains special characters that require quoting.  To force quoting902on or off for the name, use the :class:`.sqlalchemy.sql.quoted_name`903construct::904 905    from sqlalchemy.sql import quoted_name906 907 908    class GeoBuffer(GenericFunction):909        type = Geometry()910        package = "geo"911        name = quoted_name("ST_Buffer", True)912        identifier = "buffer"913        inherit_cache = True914 915The above function will render as:916 917.. sourcecode:: pycon+sql918 919    >>> print(func.geo.buffer())920    {printsql}"ST_Buffer"()921 922Type parameters for this class as a923`generic type <https://peps.python.org/pep-0484/#generics>`_ can be passed924and should match the type seen in a :class:`_engine.Result`. For example::925 926    class as_utc(GenericFunction[datetime.datetime]):927        type = DateTime()928        inherit_cache = True929 930The above indicates that the following expression returns a ``datetime``931object::932 933    connection.scalar(select(func.as_utc()))934 935.. versionadded:: 1.3.13  The :class:`.quoted_name` construct is now936   recognized for quoting when used with the "name" attribute of the937   object, so that quoting can be forced on or off for the function938   name.939 940 941Trm�	_registerc

�>
�[RUR;
a&URURUR9425 [T
U]5 gr{)r�	Annotated�__mro__�_register_generic_functionr�rB
rv�__init_subclass__)�clsrxs �rUr�!GenericFunction.__init_subclass__�s8������s�{�{�2��*�*�3�<�<����F�
��!�#rWc
�
�UR
S
U
5=
Ul
nUR
SU5=
UlnUR
SS5nSU;a943USUl[	USS5UlUR944(a
[
X@U5 gSUlg)NrcrQrSrQ
�__return_type__r�
T)rU
rcrQr�rkr�
rV)r�clsname�clsdictrcrQrSs      rUr�*GenericFunction._register_generic_function�s���"�+�+�f�g�6�6���4�&-�k�k�,��&E�E�����+�+�i��4����'��0�1�C�H� ��[�$�7��
��=�=��j�w�7�!�C�MrWc
945
��
�UR
S
S5nUc?U
Vs/sH2n[R"[RUUR946US9PM4 nnUR=
(d [U5
UlSUl[[U[RSS.6
5
Ul
[R"UR
SS5=
(d
 [!USS55
Ulgs snf)N�_parsed_argsrdr^Trfr�r�)r�rrirrjrcrlrmr_r)r$rrnr[rr0
rkr�)rorrrK
�parsed_argsrqs     rUrs�GenericFunction.__init__s����j�j���6�������A�
� � ��/�/�����*.�	��
�����<�4��+<������#��CN��+�+�D�
�947����(�(��J�J�w��%�D���v�t�)D�948��	��%s�9C')rlr[r_r�)r�r�)rrMr	zMapping[str, Any]r�r�)rrr�rK
rr�r�)r�r�r�r�r��coerce_arguments�
inherit_cacher

rcr�classmethodrrsr
r
r	
s
@rUr�
r�
~st���l
�\���M��O��D�$�949�!��!�$5�!�	
�!��!�(950�<�951�HK�952�	
�953�954rWr�
rr�
c
��\r
SrS
rSr\R"5rSrS\	R4/
rS	SjrS955Sjr
\SSj5rSrg)r�
i.z�Represent the 'next value', given a :class:`.Sequence`956as its single argument.957 958Compiles into the appropriate function on each backend,959or will raise NotImplementedError if used on a backend960that does not provide support for sequences.961 962�sequencec
���[
U
[R5(dS
5e
Xl[R963"U
R=
(d
 [USS55
Ulg)Nz0next_value() accepts a Sequence object as input.r�)	r�rrrrr0
�	data_typerkr�)ro�seqr�s   rUrs�next_value.__init__?sX�������964�965�	>�=�	>�966��
��(�(��M�M�8�W�T�6�4�8�967��	rWc
��[
U
[5=
(a- URRU
RR:H$r{)r�r�
rrc)ro�otherr�s   rU�compare�next_value.compareHs2���u�j�)�

:��
�
�"�"�e�n�n�&9�&9�9�	968rWc


��/$r{r^r�s
 rUr��next_value._from_objectsNs���	rW)rr�N)rzschema.Sequencer�rr�r�)rrr�rr�rmr�)r�r�r�r�r�r�Integerr�rcr5�dp_named_ddl_elementr
rsrr
r�r
r^rWrUr�
r�
.sS�������D��D�969�&�;�;�<���970�971��
��
rWr�
c
�2�\r
SrS
rSrSrSSjrSrg)�AnsiFunctioniSzEDefine a function in "ansi" format, which doesn't render parenthesis.Tc

�8�[R"U/
U
Q
70UD
6
 gr{)r�
rs)rorrrK
s   rUrs�AnsiFunction.__init__Xs��	� � ��7��7��7rWr^N�rrr�rK
rr�r�)r�r�r�r�r�rrsr
r^rWrUr!r!Ss'��O��M�8�3�8�?B�8�	
�8rWr!c
�^�\r
SrS
rSrSr\S	Sj5r\S972Sj5r\SSj5rSU4
SjjrSrU=
r	$)
�ReturnTypeFromArgsi^zKDefine a function whose return type is bound to the type of its973arguments.974Tc

��gr{r^rd
s    rUrs�ReturnTypeFromArgs.__init__j���rWc

��gr{r^rd
s    rUrsr(rr)rWc

��gr{r^rd
s    rUrsr(zr)rWc
975
��>
�U
Vs/sH2n[R"[RUURUS
9PM4 nnURS[
U5
5 XBS'[TU] "U0UD
6
 gs snf)Nrdr�r)	rrirrjrc�976setdefaultr rvrs)rorrrK
rq�fn_argsrxs     �rUrsr(�s�����1977��
�

����+�+���Y�Y�&*�	
��	�1978�	���'�?�7�#;�<�!(�~��
���'�,�V�,��1979s�9A1r^�r�r�
rrr�rK
rr�r�)r�r�
rrr�rK
rr�r�)r�rHrrr�rK
rr�r�)rrr�
rK
rr�r�)980r�r�r�r�r�rr981rsr
r
r	
s
@rUr&r&^s������M���
��7���	�982983������
*��7���	�984985������
��7���	�986987����-�;�-�GJ�-�	
�-�-rWr&c
�^�\r
SrS
rSr\SSj5r\S	Sj5r\S988Sj5rSU4
SjjrSrU=
r$)�ReturnTypeFromOptionalArgsi�Tc

��gr{r^rd
s    rUrs�#ReturnTypeFromOptionalArgs.__init__�r)rWc

��gr{r^rd
s    rUrsr3�r)rWc

��gr{r^rd
s    rUrsr3�r)rWc

�&>
�[TU]"U
0UD
6
 gr{�rvrs)rorrrK
rxs   �rUrsr3�s���989	���$�)�&�)rWr^r/)r�r�
rrr�rK
rr�r�)r�r�
rrr�rK
rr�r�)rrr�
rK
rr�r�)	r�r�r�r�rr990rsr
r
r	
s
@rUr1r1�s�����M�
��
��7���	�991992������
4��7���	�993994������
��7���	�995996����*�?�*��*�997�	*�*rWr1c

��\r
SrS
rSrSrSrg)rr
i�Tr^N)r�r�r�r�rlrr
r^rWrUrr
rr
�s���I��MrWrr
c

��\r
SrS
rSrSrSrg)r�
i�z!The SQL MAX() aggregate function.Tr^N�r�r�r�r�r�rr
r^rWrUr�
r�
��998��+��MrWr�
c

��\r
SrS
rSrSrSrg)r�
i�z!The SQL MIN() aggregate function.Tr^Nr:r^rWrUr�
r�
�r;rWr�
c

��\r
SrS
rSrSrSrg)r�
i�z!The SQL SUM() aggregate function.Tr^Nr:r^rWrUr�
r�
�r;rWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i�z�The SQL now() datetime function.999 1000SQLAlchemy dialects will usually render this particular function1001in a backend-specific way, such as rendering it as ``CURRENT_TIMESTAMP``.1002 1003Tr^N�1004r�r�r�r�r�r�DateTimer�rr
r^rWrUr�
r�
�s�������D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)ry
i�a�
The SQL CONCAT() function, which concatenates strings.1005 1006E.g.:1007 1008.. sourcecode:: pycon+sql1009 1010    >>> print(select(func.concat("a", "b")))1011    {printsql}SELECT concat(:concat_2, :concat_3) AS concat_11012 1013String concatenation in SQLAlchemy is more commonly available using the1014Python ``+`` operator with string datatypes, which will render a1015backend-specific concatenation operator, such as :1016 1017.. sourcecode:: pycon+sql1018 1019    >>> print(select(literal("a") + "b"))1020    {printsql}SELECT :param_1 || :param_2 AS anon_11021 1022 1023Tr^N�1024r�r�r�r�r�r�Stringr�rr
r^rWrUry
ry
�s���*�?�?��D��MrWry
c
�V^�\r
SrS
rSr\R"5rSrSU4
Sjjr	Sr1025U=
r$)ro
i�zThe CHAR_LENGTH() SQL function.Tc
�(>
�[TU]"U
4
0UD
6
 gr{r7)ro�argr�rxs   �rUrs�char_length.__init__�s���	����#��#rWr^)rFz_ColumnExpressionArgument[str]r�rr�r��r�r�r�r�r�rrr�rrsr
r
r	
s
@rUro
ro
�s#���)�����D��M�$�$rWro
c

� �\r
SrS
rSrSrSrSrg)r�
i�zThe RANDOM() SQL function.Tr^N�r�r�r�r�r�rlrr
r^rWrUr�
r�
�s��$��I��MrWr�
c
�f^�\r
SrS
rSr\R"5rSrSSU4
Sjjj
r	Sr1026U=
r$)r}
ia�
The ANSI COUNT aggregate function.  With no arguments,1027emits COUNT \*.1028 1029E.g.::1030 1031    from sqlalchemy import func1032    from sqlalchemy import select1033    from sqlalchemy import table, column1034 1035    my_table = table("some_table", column("id"))1036 1037    stmt = select(func.count()).select_from(my_table)1038 1039Executing ``stmt`` would emit:1040 1041.. sourcecode:: sql1042 1043    SELECT count(*) AS count_11044    FROM some_table1045 1046 1047Tc
�D>
�U
c[
S
5
n
[TU]"U
4
0UD
6
 g)N�
*)r*rvrs)ro�1048expressionrK
rxs   �rUrs�count.__init__!s'�����'��,�J�
����.�v�.rWr^r{)rNz7Union[_ColumnExpressionArgument[Any], _StarOrOne, None]rK
rr�r�rHr	
s
@rUr}
r}
sJ����.����D��M�
�		/�1049�	/�1050�	/�1051�
	/�	/rWr}
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i-z The CURRENT_DATE() SQL function.Tr^N)1052r�r�r�r�r�r�Dater�rr
r^rWrUr�
r�
-���*��=�=�?�D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i4z The CURRENT_TIME() SQL function.Tr^N)1053r�r�r�r�r�r�Timer�rr
r^rWrUr�
r�
4rRrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i;z%The CURRENT_TIMESTAMP() SQL function.Tr^Nr?r^rWrUr�
r�
;s��/�����D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
iBz The CURRENT_USER() SQL function.Tr^NrBr^rWrUr�
r�
B���*��?�?��D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
iIzThe localtime() SQL function.Tr^Nr?r^rWrUr�
r�
Is��'�����D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
iPz"The localtimestamp() SQL function.Tr^Nr?r^rWrUr�
r�
Ps��,�����D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
iWz The SESSION_USER() SQL function.Tr^NrBr^rWrUr�
r�
WrWrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i^zThe SYSDATE() SQL function.Tr^Nr?r^rWrUr�
r�
^s��%�����D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
iezThe USER() SQL function.Tr^NrBr^rWrUr�
r�
es��"��?�?��D��MrWr�
c
�@^�\r
SrS
rSrSrSU4
SjjrSrU=
r$)re
ilai
Support for the ARRAY_AGG function.1054 1055The ``func.array_agg(expr)`` construct returns an expression of1056type :class:`_types.ARRAY`.1057 1058e.g.::1059 1060    stmt = select(func.array_agg(table.c.values)[2:5])1061 1062.. seealso::1063 1064    :func:`_postgresql.array_agg` - PostgreSQL-specific version that1065    returns :class:`_postgresql.ARRAY`, which has PG-specific operators1066    added.1067 1068Tc
	
�\
>
�U
Vs/sH&n[R"[RX0S
9PM( nnUR	S[1069R5nSU;
a9[U5
n[U[1070R5(aXbS'O1071U"USS9US'XBS'[TU]("U0UD
6
 gs snf)N)
re�_default_array_typer�r)
�1072dimensionsr)rrirrjr�rr�r r�rvrs)rorrrK
rqr.�default_array_type�type_from_argsrxs       �rUrs�array_agg.__init__�s�����	11073��
�
����+�+�Q�
��		�11074�$�Z�Z�(=�x�~�~�N���&� �,�W�5�N��.�(�.�.�9�9�"0�w��"4�"�q�#��w��")�~��
���'�,�V�,��#11075s�-B)r^r$)	r�r�r�r�r�rrsr
r
r	
s
@rUre
re
ls1����"�M�-�3�-�?B�-�	
�-�-rWre
c
�2�\r
SrS
rSrSrSrSSjrSrg)	�
OrderedSetAggi�z�Define a function where the return type is based on the sort1076expression type as defined by the expression passed to the1077:meth:`.FunctionElement.within_group` method.FTc
�B
�[
[URR5n[R1078"U
R5
nUR(a<[UR5
S
:�a#[R"USR5
$USR$)Nrr)
rr$r[r��sqlutil�unwrap_order_byr��array_for_multi_clauserT
rprr�r�)ror��func_clausesr�s    rUr��OrderedSetAgg.within_group_type�s{���J��(8�(8�(@�(@�A��18�1H�1H��!�!�21079���&�&�3�|�/C�/C�+D�q�+H��>�>�(�1�+�"2�"2�3�3��A�;�#�#�#rWr^N)r�zWithinGroup[Any]r�zTypeEngine[Any])	r�r�r�r�r�rirr�r
r^rWrUrere�s)��5�#���M�1080$�,�1081$�	�1082$rWrec

��\r
SrS
rSrSrSrg)r�
i�z�Implement the ``mode`` ordered-set aggregate function.1083 1084This function must be used with the :meth:`.FunctionElement.within_group`1085modifier to supply a sort expression to operate upon.1086 1087The return type of this function is the same as the sort expression.1088 1089Tr^Nr:r^rWrUr�
r�
�s����MrWr�
c

� �\r
SrS
rSrSrSrSrg)r�
i�ad
Implement the ``percentile_cont`` ordered-set aggregate function.1090 1091This function must be used with the :meth:`.FunctionElement.within_group`1092modifier to supply a sort expression to operate upon.1093 1094The return type of this function is the same as the sort expression,1095or if the arguments are an array, an :class:`_types.ARRAY` of the sort1096expression's type.1097 1098Tr^N�r�r�r�r�r�rirr
r^rWrUr�
r�
����	�"���MrWr�
c

� �\r
SrS
rSrSrSrSrg)r�
i�ad
Implement the ``percentile_disc`` ordered-set aggregate function.1099 1100This function must be used with the :meth:`.FunctionElement.within_group`1101modifier to supply a sort expression to operate upon.1102 1103The return type of this function is the same as the sort expression,1104or if the arguments are an array, an :class:`_types.ARRAY` of the sort1105expression's type.1106 1107Tr^Nrnr^rWrUr�
r�
�rorWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i�z�Implement the ``rank`` hypothetical-set aggregate function.1108 1109This function must be used with the :meth:`.FunctionElement.within_group`1110modifier to supply a sort expression to operate upon.1111 1112The return type of this function is :class:`.Integer`.1113 1114Tr^N�1115r�r�r�r�r�rrr�rr
r^rWrUr�
r�
���������D��MrWr�
c
�>�\r
SrS
rSr\R"5rSrSr	g)r�
i�z�Implement the ``dense_rank`` hypothetical-set aggregate function.1116 1117This function must be used with the :meth:`.FunctionElement.within_group`1118modifier to supply a sort expression to operate upon.1119 1120The return type of this function is :class:`.Integer`.1121 1122Tr^Nrrr^rWrUr�
r�
�rsrWr�
c
�J�\r
SrS
r%Sr\R"5rS\S'Sr	Sr1123g)r�
i�z�Implement the ``percent_rank`` hypothetical-set aggregate function.1124 1125This function must be used with the :meth:`.FunctionElement.within_group`1126modifier to supply a sort expression to operate upon.1127 1128The return type of this function is :class:`.Numeric`.1129 1130�!sqltypes.Numeric[decimal.Decimal]r�Tr^N�r�r�r�r�r�r�Numericr�r

rr
r^rWrUr�
r�
��"���/7�.>�.>�.@�D�1131+�@��MrWr�
c
�J�\r
SrS
r%Sr\R"5rS\S'Sr	Sr1132g)r�
iz�Implement the ``cume_dist`` hypothetical-set aggregate function.1133 1134This function must be used with the :meth:`.FunctionElement.within_group`1135modifier to supply a sort expression to operate upon.1136 1137The return type of this function is :class:`.Numeric`.1138 1139rvr�Tr^Nrwr^rWrUr�
r�
ryrWr�
c

� �\r
SrS
rSrSrSrSrg)r�
ia7
Implement the ``CUBE`` grouping operation.1140 1141This function is used as part of the GROUP BY of a statement,1142e.g. :meth:`_expression.Select.group_by`::1143 1144    stmt = select(1145        func.sum(table.c.value), table.c.col_1, table.c.col_21146    ).group_by(func.cube(table.c.col_1, table.c.col_2))1147 1148.. versionadded:: 1.21149 1150Tr^NrJr^rWrUr�
r�
�����I��MrWr�
c

� �\r
SrS
rSrSrSrSrg)r�
i#a;
Implement the ``ROLLUP`` grouping operation.1151 1152This function is used as part of the GROUP BY of a statement,1153e.g. :meth:`_expression.Select.group_by`::1154 1155    stmt = select(1156        func.sum(table.c.value), table.c.col_1, table.c.col_21157    ).group_by(func.rollup(table.c.col_1, table.c.col_2))1158 1159.. versionadded:: 1.21160 1161Tr^NrJr^rWrUr�
r�
#r|rWr�
c

� �\r
SrS
rSrSrSrSrg)r�
i5a�Implement the ``GROUPING SETS`` grouping operation.1162 1163This function is used as part of the GROUP BY of a statement,1164e.g. :meth:`_expression.Select.group_by`::1165 1166    stmt = select(1167        func.sum(table.c.value), table.c.col_1, table.c.col_21168    ).group_by(func.grouping_sets(table.c.col_1, table.c.col_2))1169 1170In order to group by multiple sets, use the :func:`.tuple_` construct::1171 1172    from sqlalchemy import tuple_1173 1174    stmt = select(1175        func.sum(table.c.value), table.c.col_1, table.c.col_2, table.c.col_31176    ).group_by(1177        func.grouping_sets(1178            tuple_(table.c.col_1, table.c.col_2),1179            tuple_(table.c.value, table.c.col_3),1180        )1181    )1182 1183.. versionadded:: 1.21184 1185Tr^NrJr^rWrUr�
r�
5s���4�I��MrWr�
c
�f^�\r
SrS
rSr\R"5rSrSr	SU4
Sjjr1186SrU=
r$)r]
iTa�
Implement a generic string aggregation function.1187 1188This function will concatenate non-null values into a string and1189separate the values by a delimiter.1190 1191This function is compiled on a per-backend basis, into functions1192such as ``group_concat()``, ``string_agg()``, or ``LISTAGG()``.1193 1194e.g. Example usage with delimiter '.'::1195 1196    stmt = select(func.aggregate_strings(table.c.str_col, "."))1197 1198The return type of this function is :class:`.String`.1199 1200.. versionadded: 2.0.21

Showing the first 1,200 of 1232 lines. Download the file for the rest.