U a@sZdZddlmZddlZddlZddlZddlmZddlmZddlm Z ddlm Z dd lm Z dd l m Z dd l mZdd lmZdd lmZddlmZddlmZddlmZddlmZddlmZddlmZddlmZddl mZddl mZddl mZddlmZddlmZddlmZddlm Z ddlm!Z!ddlm"Z"ddlm#Z#d d!Z$dd#d$Z%dd%d&Z&dd'd(Z'd)d*Z(e"j)Gd+d,d,e j*eeee Z+Gd-d.d.e j,e j-e j.e j/e j0e j1e j2e j3e j4e j5ej6e+Z7Gd/d0d0e8Z9Gd1d2d2e j:e7Z;Gd3d4d4e+Ze j/e j:ee+ Z?Gd7d8d8ee j@e7ZAeABGd9d:d:ee j@e7ZCeCBGd;d<dd>e j:e j0e j1e j3e+ZEGd?d@d@eEe7ZFeFjGZGeFjHZHGdAdBdBeEe7ZIGdCdDdDe7ZJddEdFZKGdGdHdHe9e7ZLGdIdJdJe9e7ZMGdKdLdLe7ZNGdMdNdNe7ZOGdOdPdPe7ZPGdQdRdRe7ZQGdSdTdTeQZRGdUdVdVe9eQZSGdWdXdXe7ZTGdYdZdZe7ZUGd[d\d\eTZVGd]d^d^e+ZWGd_d`d`eWe7ZXe#YdaZZe#YdbZ[Gdcdddde7Z\Gdedfdfe7Z]Gdgdhdhe7Z^Gdidjdje j_e7Z`Gdkdldle7ZaGdmdndne jbe j_e jceeaZdGdodpdpeaZeGdqdrdre7ZfGdsdtdtee+ZgGdudvdvegZhGdwdxdxegZiGdydzdzegZjGd{d|d|e#jke#jlZmd}d~ZnddZodddZpGddde ZqGdddemZrGddderZse#YdZterZuGddderZvdS)zCore SQL expression elements, including :class:`_expression.ClauseElement`, :class:`_expression.ColumnElement`, and derived classes. )unicode_literalsN) coercions) operators)roles) traversals)type_api) Annotated)SupportsWrappingAnnotations)_clone) _generative) Executable) HasMemoized) Immutable)NO_ARG)PARSE_AUTOCOMMIT)SingletonConstant)_document_text_coercion)HasCopyInternals)MemoizedHasCacheKey)NO_CACHE)cloned_traverse)InternalTraversal)traverse) Traversible)exc) inspection)utilcCs&ttj|}t|t|tj|jdS)aReturn the clause ``expression COLLATE collation``. e.g.:: collate(mycolumn, 'utf8_bin') produces:: mycolumn COLLATE utf8_bin The collation expression is also quoted if it is a case sensitive identifier, e.g. contains uppercase characters. .. versionchanged:: 1.2 quoting is automatically applied to COLLATE expressions if they are case sensitive. type_) rexpectrExpressionElementRoleBinaryExpressionCollationClausercollatetype) expression collationexprr*XC:\Users\vtejo\AppData\Local\Temp\pip-unpacked-wheel-nyjtotrf\sqlalchemy\sql\elements.pyr%/sr%FcCsttj|}|j|||dS)atProduce a ``BETWEEN`` predicate clause. E.g.:: from sqlalchemy import between stmt = select(users_table).where(between(users_table.c.id, 5, 7)) Would produce SQL resembling:: SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2 The :func:`.between` function is a standalone version of the :meth:`_expression.ColumnElement.between` method available on all SQL expressions, as in:: stmt = select(users_table).where(users_table.c.id.between(5, 7)) All arguments passed to :func:`.between`, including the left side column expression, are coerced from Python scalar values if a the value is not a :class:`_expression.ColumnElement` subclass. For example, three fixed values can be compared as in:: print(between(5, 3, 7)) Which would produce:: :param_1 BETWEEN :param_2 AND :param_3 :param expr: a column expression, typically a :class:`_expression.ColumnElement` instance or alternatively a Python scalar expression to be coerced into a column expression, serving as the left side of the ``BETWEEN`` expression. :param lower_bound: a column or Python scalar expression serving as the lower bound of the right side of the ``BETWEEN`` expression. :param upper_bound: a column or Python scalar expression serving as the upper bound of the right side of the ``BETWEEN`` expression. :param symmetric: if True, will render " BETWEEN SYMMETRIC ". Note that not all databases support this syntax. .. versionadded:: 0.9.5 .. seealso:: :meth:`_expression.ColumnElement.between` ) symmetric)rr!rr"between)r)Z lower_boundZ upper_boundr,r*r*r+r-Hs4r-cCstjtj||dS)aReturn a literal clause, bound to a bind parameter. Literal clauses are created automatically when non- :class:`_expression.ClauseElement` objects (such as strings, ints, dates, etc.) are used in a comparison operation with a :class:`_expression.ColumnElement` subclass, such as a :class:`~sqlalchemy.schema.Column` object. Use this function to force the generation of a literal clause, which will be created as a :class:`BindParameter` with a bound value. :param value: the value to be bound. Can be any Python object supported by the underlying DB-API, or is translatable via the given type argument. :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` which will provide bind-parameter translation for this literal. r)rr!rZLiteralValueRole)valuer r*r*r+literalsr/cCst|d|dddS)axCreate an 'OUT' parameter for usage in functions (stored procedures), for databases which support them. The ``outparam`` can be used like a regular function parameter. The "output" value will be available from the :class:`~sqlalchemy.engine.CursorResult` object via its ``out_parameters`` attribute, which returns a dictionary containing the values. NFT)r unique isoutparam BindParameter)keyr r*r*r+outparams r5cCstttj|S)zReturn a negation of the given clause, i.e. ``NOT(clause)``. The ``~`` operator is also overloaded on all :class:`_expression.ColumnElement` subclasses to produce the same result. )rinvrr!rr"clauser*r*r+not_sr9c@sReZdZdZdZeZdZdZ gZ dZ dZ dZ dZdZdZdZdZdZdZdZdZdZdZdZdZdZddZd d Zd d Zd dZe ddZ!e"j#ddZ$e ddZ%ddZ&d7ddZ'ddZ(ddZ)ddZ*dd Z+d8d!d"Z,d#d$Z-e.d%e.d&d9d'd(Z/d:d)d*Z0d+d,Z1d-d.Z2d/d0Z3d1d2Z4d3d4Z5e5Z6d5d6Z7dS); ClauseElementzSBase class for elements of a programmatically constructed SQL expression. r8FdefaultNTcCst||_|SN)r immutabledict_propagate_attrs)selfvaluesr*r*r+_set_propagate_attrss z"ClauseElement._set_propagate_attrsc s8|j|j|j}fdd|jD|_||_|S)zCreate a shallow copy of this ClauseElement. This method may be used by a generative API. Its also used as part of the "deep" copy afforded by a traversal that combines the _copy_internals() method. csi|]\}}|kr||qSr*r*).0kvskipr*r+ sz(ClauseElement._clone..)Z_memoized_keys __class____new____dict__items _is_clone_of)r?kwcr*rEr+r s zClauseElement._clonecCs|S)za hook to allow the right side of a binary expression to respond to a negation of the binary expression. Used for the special case of expanding bind parameter with IN. r*)r? negated_op original_opr*r*r+_negate_in_binaryszClauseElement._negate_in_binarycCs|S)zin the context of binary expression, convert the type of this object to the one given. applies only to :class:`_expression.ColumnElement` classes. r*r?r r*r*r+_with_binary_element_typesz'ClauseElement._with_binary_element_typecCs|jS)a.return the 'constructor' for this ClauseElement. This is for the purposes for creating a new object of this type. Usually, its just the element's __class__. However, the "Annotated" version of the object overrides to return the class of its proxied element. rHr?r*r*r+ _constructors zClauseElement._constructorcCs*t}|}|dk r&|||j}q |S)aReturn the set consisting all cloned ancestors of this ClauseElement. Includes this ClauseElement. This accessor tends to be used for FromClause objects to identify 'equivalent' FROM clauses, regardless of transformative operations. N)r column_setaddrL)r?sfr*r*r+ _cloned_sets  zClauseElement._cloned_setcCs tddS)NzFThis SQL expression has no entity namespace with which to filter from.)AttributeErrorrUr*r*r+entity_namespace2szClauseElement.entity_namespacecCs&|j}|dd|dd|S)NrL_generate_cache_key)rJcopypop)r?dr*r*r+ __getstate__9s   zClauseElement.__getstate__cCs(|s |jr|||||St|dSr<)supports_executionZ_execute_clauseelementrZObjectNotExecutableError)r? connectionZ multiparamsparamsZexecution_optionsZ_forcer*r*r+_execute_on_connection?s z$ClauseElement._execute_on_connectioncOs|d||S)aReturn a copy with :func:`_expression.bindparam` elements replaced. Same functionality as :meth:`_expression.ClauseElement.params`, except adds `unique=True` to affected bind parameters so that multiple statements can be used. T_replace_paramsr? optionaldictkwargsr*r*r+ unique_paramsIs zClauseElement.unique_paramscOs|d||S)aReturn a copy with :func:`_expression.bindparam` elements replaced. Returns a copy of this ClauseElement with :func:`_expression.bindparam` elements replaced with values taken from the given dictionary:: >>> clause = column('x') + bindparam('foo') >>> print(clause.compile().params) {'foo':None} >>> print(clause.params({'foo':7}).compile().params) {'foo':7} Frgrir*r*r+reUszClauseElement.paramscsTt|dkr|dnt|dkr2tdfdd}t|ddid|iS) Nrrz9params() takes zero or one positional dictionary argumentcs,|jkr|j|_d|_r(|dS)NF)r4r.required_convert_to_uniquebindrkr0r*r+visit_bindparamns   z6ClauseElement._replace_params..visit_bindparam maintain_keyT bindparam)lenupdater ArgumentErrorr)r?r0rjrkrrr*rqr+rhfs  zClauseElement._replace_paramscKstj||f|S)aCompare this :class:`_expression.ClauseElement` to the given :class:`_expression.ClauseElement`. Subclasses should override the default behavior, which is a straight identity comparison. \**kw are arguments consumed by subclass ``compare()`` methods and may be used to modify the criteria for comparison (see :class:`_expression.ColumnElement`). )rcompare)r?otherrMr*r*r+rxys zClauseElement.comparecCs|S)aApply a 'grouping' to this :class:`_expression.ClauseElement`. This method is overridden by subclasses to return a "grouping" construct, i.e. parenthesis. In particular it's used by "binary" expressions to provide a grouping around themselves when placed into a larger expression, as well as by :func:`_expression.select` constructs when placed into the FROM clause of another :func:`_expression.select`. (Note that subqueries should be normally created using the :meth:`_expression.Select.alias` method, as many platforms require nested SELECT statements to be named). As expressions are composed together, the application of :meth:`self_group` is automatic - end-user code should never need to use this method directly. Note that SQLAlchemy's clause constructs take operator precedence into account - so parenthesis might not be needed, for example, in an expression like ``x OR (y AND z)`` - AND takes precedence over OR. The base :meth:`self_group` method of :class:`_expression.ClauseElement` just returns self. r*r?againstr*r*r+ self_groupszClauseElement.self_groupcCs|S)zVReturn this :class:`_expression.ClauseElement` without any groupings. r*rUr*r*r+_ungroupszClauseElement._ungroupzsqlalchemy.engine.defaultzsqlalchemy.engine.urlcKsf|sX|r|j}nH|jr |jj}n8|jdkr) descriptionobject__repr__ __module__rH__name__id)r?Zfriendlyr*r*r+rEs zClauseElement.__repr__)F)N)NN)NNFN)8rr __qualname____doc____visit_name__rr=r>rcr _from_objectsrprrLZis_clause_elementZ is_selectable _is_textualZ_is_from_clauseZ_is_returns_rows_is_text_clauseZ_is_from_containerZ_is_select_containerZ_is_select_statement_is_bind_parameter_is_clause_listZ_is_lambda_element_order_by_label_elementZ_cache_key_traversalrAr rQrSpropertyrVrmemoized_attributer[r]rbrfrlrerhrxr|r}preload_modulerrrrrrr __nonzero__rr*r*r*r+r:sr         C :r:cseZdZdZdZdZgZdZdZdZ e j ddZ e dd Ze d d Ze d d ZdZdZdZdZdZdLddZfddZejddZe j ddZddZddZddZdMddZe dd Z e d!d"Z!ejd#d$Z"ejd%d&Z#d'd(Z$d)d*Z%d+d,Z&e j d-d.Z'e j d/d0Z(dNd1d2Z)d3d4Z*d5d6Z+d7d8Z,ejd9d:Z-ejd;d<Z.e e/d=d>d?d@Z0e e/d=dAdBdCZ1ejdDdEZ2ejdFdGZ3ejdHdIZ4ejdJdKZ5Z6S)O ColumnElementaRepresent a column-oriented SQL expression suitable for usage in the "columns" clause, WHERE clause etc. of a statement. While the most familiar kind of :class:`_expression.ColumnElement` is the :class:`_schema.Column` object, :class:`_expression.ColumnElement` serves as the basis for any unit that may be present in a SQL expression, including the expressions themselves, SQL functions, bound parameters, literal expressions, keywords such as ``NULL``, etc. :class:`_expression.ColumnElement` is the ultimate base class for all such elements. A wide variety of SQLAlchemy Core functions work at the SQL expression level, and are intended to accept instances of :class:`_expression.ColumnElement` as arguments. These functions will typically document that they accept a "SQL expression" as an argument. What this means in terms of SQLAlchemy usually refers to an input which is either already in the form of a :class:`_expression.ColumnElement` object, or a value which can be **coerced** into one. The coercion rules followed by most, but not all, SQLAlchemy Core functions with regards to SQL expressions are as follows: * a literal Python value, such as a string, integer or floating point value, boolean, datetime, ``Decimal`` object, or virtually any other Python object, will be coerced into a "literal bound value". This generally means that a :func:`.bindparam` will be produced featuring the given value embedded into the construct; the resulting :class:`.BindParameter` object is an instance of :class:`_expression.ColumnElement`. The Python value will ultimately be sent to the DBAPI at execution time as a parameterized argument to the ``execute()`` or ``executemany()`` methods, after SQLAlchemy type-specific converters (e.g. those provided by any associated :class:`.TypeEngine` objects) are applied to the value. * any special object value, typically ORM-level constructs, which feature an accessor called ``__clause_element__()``. The Core expression system looks for this method when an object of otherwise unknown type is passed to a function that is looking to coerce the argument into a :class:`_expression.ColumnElement` and sometimes a :class:`_expression.SelectBase` expression. It is used within the ORM to convert from ORM-specific objects like mapped classes and mapped attributes into Core expression objects. * The Python ``None`` value is typically interpreted as ``NULL``, which in SQLAlchemy Core produces an instance of :func:`.null`. A :class:`_expression.ColumnElement` provides the ability to generate new :class:`_expression.ColumnElement` objects using Python expressions. This means that Python operators such as ``==``, ``!=`` and ``<`` are overloaded to mimic SQL operations, and allow the instantiation of further :class:`_expression.ColumnElement` instances which are composed from other, more fundamental :class:`_expression.ColumnElement` objects. For example, two :class:`.ColumnClause` objects can be added together with the addition operator ``+`` to produce a :class:`.BinaryExpression`. Both :class:`.ColumnClause` and :class:`.BinaryExpression` are subclasses of :class:`_expression.ColumnElement`:: >>> from sqlalchemy.sql import column >>> column('a') + column('b') >>> print(column('a') + column('b')) a + b .. seealso:: :class:`_schema.Column` :func:`_expression.column` Zcolumn_elementFr*NcCs|jS)alA label-based version of 'key' that in some circumstances refers to this object in a Python namespace. _tq_key_label comes into play when a select() statement is constructed with apply_labels(); in this case, all Column objects in the ``.c`` collection are rendered as _ in SQL; this is essentially the value of ._label. But to locate those columns in the ``.c`` collection, the name is along the lines of _; that's the typical value of .key_label. .. versionchanged:: 1.4.21 renamed from ``._key_label`` ) _proxy_keyrUr*r*r+ _tq_key_labelszColumnElement._tq_key_labelcCs|jS)z legacy; renamed to _tq_key_label)rrUr*r*r+ _key_labelszColumnElement._key_labelcCs|jS)zlegacy; renamed to _tq_label) _tq_labelrUr*r*r+_labelszColumnElement._labelcCs t|ddS)a:the 'name' that naturally applies this element when rendered in SQL. Concretely, this is the "name" of a column or a label in a SELECT statement; ```` and ```` below:: SELECT FROM table SELECT column AS FROM table Above, the two names noted will be what's present in the DBAPI ``cursor.description`` as the names. If this attribute returns ``None``, it means that the SQL element as written does not have a 100% fully predictable "name" that would appear in the ``cursor.description``. Examples include SQL functions, CAST functions, etc. While such things do return names in ``cursor.description``, they are only predictable on a database-specific basis; e.g. an expression like ``MAX(table.col)`` may appear as the string ``max`` on one database (like PostgreSQL) or may appear as the whole expression ``max(table.col)`` on SQLite. The default implementation looks for a ``.name`` attribute on the object, as has been the precedent established in SQLAlchemy for many years. An exception is made on the ``FunctionElement`` subclass so that the return value is always ``None``. .. versionadded:: 1.4.21 nameN)getattrrUr*r*r+_non_anon_labels"zColumnElement._non_anon_labelTcCsT|tjtjtjfkr4|jjtjjkr4t|tj tj S|tj tj fkrLt |S|SdSr<)rand_or__asboolr&_type_affinityr BOOLEANTYPE AsBooleanis_trueis_falseany_opall_opGroupingrzr*r*r+r|,szColumnElement.self_groupcs2|jjtjjkr t|tjtjStt | SdSr<) r&rrrrrrrsuperrrrUrTr*r+r7szColumnElement._negatecCstjSr<rNULLTYPErUr*r*r+r&=szColumnElement.typec CsTz |jj}Wn:tk rF}ztjtd|j|dW5d}~XYn X||SdS)NzOObject %r associated with '.type' attribute is not a TypeEngine class or objectZreplace_context)r&comparator_factoryr\rraise_r)r?rerrr*r*r+ comparatorAs zColumnElement.comparatorc Cs`zt|j|WStk rZ}z.tjtdt|jt|jj|f|dW5d}~XYnXdS)Nz3Neither %r object nor %r object has an attribute %rr)rrr\rrr&r)r?r4rr*r*r+ __getattr__Ps zColumnElement.__getattr__cOs||jf||Sr<rr?opryrkr*r*r+operate`szColumnElement.operatecKs|||jf|Sr<rrr*r*r+reverse_operatecszColumnElement.reverse_operatec Cstd||||jd|dS)NT)_compared_to_operatorr _compared_to_typer0 expanding)r3r&r?robjr rr*r*r+ _bind_paramfszColumnElement._bind_paramcCs|S)z^Return a column expression. Part of the inspection interface; returns self. r*rUr*r*r+r'qszColumnElement.expressioncCs|fSr<r*rUr*r*r+_select_iterablezszColumnElement._select_iterablecCstdd|jDS)Ncss|]}|js|VqdSr<)_proxiesrBrNr*r*r+ sz-ColumnElement.base_columns..)rrW proxy_setrUr*r*r+ base_columns~szColumnElement.base_columnscCs(t|g}|jD]}||jq|Sr<)rrWrrvrr?rYrNr*r*r+rs  zColumnElement.proxy_setcCs*t|g}|jD]}||q|S)zAn 'uncached' version of proxy set. This is so that we can read annotations from the list of columns without breaking the caching of the above proxy_set. )rrWrrv_uncached_proxy_setrr*r*r+rs  z!ColumnElement._uncached_proxy_setcCst|j|jS)zReturn True if the given :class:`_expression.ColumnElement` has a common ancestor to this :class:`_expression.ColumnElement`.)rr intersection)r?Z othercolumnr*r*r+shares_lineageszColumnElement.shares_lineagecCs t|dot|do|j|jkS)zhReturn True if the given column element compares to this one when targeting within a result row.r)rrr?ryr*r*r+_compare_name_for_results   z&ColumnElement._compare_name_for_resultcCs@|jrd|jkr|jdS|j}|s*|j}t|tr8dS|SdS)N proxy_key) _annotationsr4r isinstance_anonymous_labelr?rr*r*r+rs  zColumnElement._proxy_keycCs6t|dddk rdS|jr.d|jkr.|jdSdSdS)a\a suggested label to use in the case that the column has no name, which should be used if possible as the explicit 'AS