H`Tc@s.dZddlmZddlmZmZmZmZmZ m Z ddl m Z m Z mZmZmZddlmZddlmZmZmZmZmZdd lmZmZmZmZmZmZdd lm Z dd lmZ!m"Z"m#Z#dd l$m%Z%dd lm&Z&dddgZ'ej(Z)ej*ej+de,fdYZ-ddl.m/Z/de/fdYZ0de,fdYZ1de1fdYZ2ej*de,fdYZ3de1fdYZ4de1fdYZ5de,fdYZ6d ej7fd!YZ8d"S(#sThe Query class and support. Defines the :class:`.Query` class, the central construct used by the ORM to construct database queries. The :class:`.Query` class should not be confused with the :class:`.Select` class, which defines database SELECT operations at the SQL (non-ORM) level. ``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts with an ORM session, whereas the ``Select`` construct interacts directly with the database to return iterable result sets. i(tchaini(t attributest interfacest object_mappert persistencetexctloading(t_entity_descriptort_is_aliased_classt_is_mapped_classt _orm_columnst _generative(t PathRegistry(t AliasedClasst ORMAdaptertjoint with_parenttaliasedi(tsqltutiltlogRtinspectt inspection(t_interpret_as_from(Rt expressiontvisitors(tColumnCollection(t propertiestQueryt QueryContextRcBsJeZdZeZeZeZd{Z d{Z eZ eZ d{Z eZd{Zd{Zd{Zd{Zd{ZeZeZeZeZeZd{Zd{Zd|Zd}Zd{ZiZd{Z d{Z!e"j#Z$Z%e"j#Z&e"j#Z'e"j#Z(d~Z)dZ*eZ+e,Z-d{dZ.d{dZ/dZ0dZ1dZ2dZ3dZ4dZ5e6d Z7d Z8d Z9d Z:e;d Z<dZ=dZ>d{dZ?dZ@d{dZAdZBdZCdZDeedZEeedZFdZGdZHdZIdZJd{d{d{d{dZKdZLe;dZMd{eedZNd{ed ZOd!ZPd"ZQe;d#ZRd$ZSe6d%ZTe6d&ZUe6d'ZVe;d(ZWe6d)ZXe6eGd{d{d*ZYe6d+ZZd,Z[e6d-Z\e6d.Z]e6d/Z^e6d0Z_d{d1Z`e6d{d2Zae6d3Zbd4Zce6d5Zde6d6Zed7ZfefZgd8Zhe6d9Zie6d:Zje"jkd;d<ed=Zld>Zmd?Zne6d@ZodAZpe6dBdCZqe6dDZre6dEZse6eed{dFZte6dGZue6eHeIdHZvdIZwe6eHeIdJZxe6eHeIdKZye6eHeIdLZzdMZ{dNZ|dOZ}dPZ~dQZdRZdSZdTZdUZe6eHeIdVZdWZdXZdYZdZZe6eHd[Ze6eGd\Ze6eGd]Zd^Ze6eHd_Ze6eHd`Ze6eHdaZe6eHdbZe6dcZddZe6eGdeZdfZdgZdhZdiZdjZdkZe;dlZd{dmZednZe;doZe;dpZdqZdrZdsdtZdsduZedvZdwZdxZdyZdzZRS(sORM-level SQL construction object. :class:`.Query` is the source of all SELECT statements generated by the ORM, both those formulated by end-user query operations as well as by high level internal operations such as related collection loading. It features a generative interface whereby successive calls return a new :class:`.Query` object, a copy of the former with additional criteria and options associated with it. :class:`.Query` objects are normally initially generated using the :meth:`~.Session.query` method of :class:`.Session`. For a full walkthrough of :class:`.Query` usage, see the :ref:`ormtutorial_toplevel`. cCs#||_i|_|j|dS(N(tsessiont_polymorphic_adapterst _set_entities(tselftentitiesR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt__init__is  cCsb|dkrt}ng|_d|_x$tj|D]}|||q7W|j|jdS(N(tNonet _QueryEntityt _entitiest_primary_entityRtto_listt_set_entity_selectables(R!R"tentity_wrappertent((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR ns    cCs|jj|_}x|D]}x|jD]}||krt|}|j r|jjr|jj|jkr|j |jt j |j |jj nd}n-|jrt j |j |jj }nd}||f||(R!R/R@RA((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_reset_polymorphic_adapterscCsd|jkrG|jd}|jj|d}|rG|j|Snt|tjrb|}nt|dr}|j }ndS|jj|d}|r|j|SdS(Nt parententityttable( t _annotationsRtgetR$t adapt_clauseRIRt FromClauseRBR](R!telementtsearchRK((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_adapt_polymorphic_elements   cCs/g|D]$}|jtj|tt^qS(N(t _adapt_clauseRt_literal_as_texttTrue(R!tcolsto((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_adapt_col_listscCs t|_dS(N(tFalset_orm_only_adapt(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_adapt_all_clausesscsgt|d|}|rW|jrWx-|jjD]}j||jfq4Wn|jrjt|d||jjfn|jrj||jfns|Sfd}tj |i|S(s\Adapt incoming clauses to transformations which have been applied within this query.Rlt_orm_only_from_obj_aliascs_xXD]P\}}| s8d|jks8d|jkr||}|dk rW|SqqWdS(Nt _orm_adaptR\(R^R$(telemt _orm_onlyR?te(tadapters(sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytreplace s  ( tgetattrt_filter_aliasest_visitor_iteratorRGRtRQRRdRtreplacement_traverse(R!tclauset as_filtertorm_onlyRTRt((RssZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRes(   cCs |jdS(Ni(R&(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt _entity_zeroscCs|jp|jjS(N(RDR|t entity_zero(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt _mapper_zero"s ccs/x(|jD]}t|tr |Vq q WdS(N(R&RIt _MapperEntity(R!R+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_mapper_entities&scCs|jjd|jS(Nt_joinpoint_entity(t _joinpointR_R~(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_joinpoint_zero,s cCs|jr|jjSdSdS(N(R'R/R$(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_mapper_zero_or_none2s  cCs7t|jdkr-tj|p$dn|jS(Nis8This operation requires a Query against a single mapper.(RNR&REtInvalidRequestErrorR~(R!t rationale((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_only_mapper_zero8s  cCs5|j|jgkr+tjd|n|jjS(Ns4%s() can only be used against a single mapped class.(R&R'RERR}(R!tmethname((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_only_full_mapper_zeroAs  cCs7t|jdkr-tj|p$dn|jS(Nis8This operation requires a Query against a single mapper.(RNR&RERR|(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_only_entity_zeroHs  cCs1i}x$|jD]}|j|jjqW|S(N(RtupdateR/R6(R!RXR+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt __all_equivsQscCs|jddtdtS(NR_torder_bytdistinct(t_no_criterion_conditionRk(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_get_conditionWscCs|jddtdtdS(NR_RR(t_no_criterion_assertionRk(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_get_existing_condition[sc Cs|js dS|jdk sy|jdk sy|jsy|jdk sy|jdk sy|jsy|rj|jsy|r|j rt j d|ndS(Ns<Query.%s() being called on a Query with existing criterion. ( t_enable_assertionst _criterionR$t _statementRMt_limitt_offsett _group_byt _order_byt _distinctRER(R!tmethRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR^s cCsG|j|||d|_d|_|_t|_|_|_dS(N(( RRMR$RRRkRRR(R!RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRjs cCs=|js dS|jr,tjd|n|j|dS(Ns<Query.%s() being called on a Query with existing criterion. (RRRERR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_no_clauseelement_conditionqs   cCs6|js dS|jdk r2tjd|ndS(Ns[Query.%s() being called on a Query with an existing full statement - can't apply criterion.(RRR$RER(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_no_statement_conditionzs  cCsK|js dS|jdk s+|jdk rGtjd||fndS(NsQuery.%s() being called on a Query which already has LIMIT or OFFSET applied. To modify the row-limited results of a Query, call from_self() first. Otherwise, call %s() before limit() or offset() are applied.(RRR$RRER(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_no_limit_offsets  cCs|js dSxrd d ddtfddtfd d tffD]@\}}}t|||k r>tjd ||fq>q>WdS(NRslimit()Rsoffset()Rs order_by()Rs group_by()Rs distinct()s-Can't call Query.%s() when %s has been called(s_limitslimit()N(s_offsetsoffset()N(RR$RkRuRER(R!RtattrRtnotset((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_no_select_modifierss   cCsR|r||_n|r$||_n|r6||_n|rNt||_n|S(N(t_populate_existingt_version_checkt_refresh_statetsett_only_load_props(R!tpopulate_existingt version_checktonly_load_propst refresh_state((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt _get_optionss   cCs.|j}|j|}|jj|_|S(N(t __class__t__new__t__dict__R-(R!tclstq((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_clones cCsJ|jd|jj}|jr6|j|j}n|jitd6S(sThe full SELECT statement represented by this Query. The statement by default will not have disambiguating labels applied to the construct unless with_labels(True) is called first. tlabelstno_replacement_traverse(t_compile_contextt _with_labelst statementt_paramstparamst _annotateRg(R!tstmt((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs  cCsR|jt}|r$|j}n|j}|rB|j}n|jd|S(sreturn the full SELECT statement represented by this :class:`.Query`, embedded within an :class:`.Alias`. Eager JOIN generation within the query is disabled. :param name: string name to be assigned as the alias; this is passed through to :meth:`.FromClause.alias`. If ``None``, a name will be deterministically generated at compile time. :param with_labels: if True, :meth:`.with_labels` will be called on the :class:`.Query` first to apply table-qualified labels to all columns. :param reduce_columns: if True, :meth:`.Select.reduce_columns` will be called on the resulting :func:`.select` construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. .. versionchanged:: 0.8 the ``with_labels`` and ``reduce_columns`` keyword arguments were added. tname(tenable_eagerloadsRkt with_labelsRtreduce_columnsRK(R!RRRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytsubquerys cCs"|jtjjd|d|S(sOReturn the full SELECT statement represented by this :class:`.Query` represented as a common table expression (CTE). .. versionadded:: 0.7.6 Parameters and usage are the same as those of the :meth:`.SelectBase.cte` method; see that method for further details. Here is the `Postgresql WITH RECURSIVE example `_. Note that, in this example, the ``included_parts`` cte and the ``incl_alias`` alias of it are Core selectables, which means the columns are accessed via the ``.c.`` attribute. The ``parts_alias`` object is an :func:`.orm.aliased` instance of the ``Part`` entity, so column-mapped attributes are available directly:: from sqlalchemy.orm import aliased class Part(Base): __tablename__ = 'part' part = Column(String, primary_key=True) sub_part = Column(String, primary_key=True) quantity = Column(Integer) included_parts = session.query( Part.sub_part, Part.part, Part.quantity).\ filter(Part.part=="our part").\ cte(name="included_parts", recursive=True) incl_alias = aliased(included_parts, name="pr") parts_alias = aliased(Part, name="p") included_parts = included_parts.union_all( session.query( parts_alias.sub_part, parts_alias.part, parts_alias.quantity).\ filter(parts_alias.part==incl_alias.c.sub_part) ) q = session.query( included_parts.c.sub_part, func.sum(included_parts.c.quantity). label('total_quantity') ).\ group_by(included_parts.c.sub_part) .. seealso:: :meth:`.SelectBase.cte` Rt recursive(RRkRtcte(R!RR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs9cCs|jtjj|S(s Return the full SELECT statement represented by this :class:`.Query`, converted to a scalar subquery with a label of the given name. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.label`. .. versionadded:: 0.6.5 (RRkRtlabel(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR"s cCs|jtjjS(sReturn the full SELECT statement represented by this :class:`.Query`, converted to a scalar subquery. Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.as_scalar`. .. versionadded:: 0.6.5 (RRkRt as_scalar(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR/s cCs |jS(sReturn the :class:`.Select` object emitted by this :class:`.Query`. Used for :func:`.inspect` compatibility, this is equivalent to:: query.enable_eagerloads(False).with_labels().statement (t__clause_element__(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR5;s cCs|jtjjS(N(RRkRR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRFscCs ||_dS(sControl whether or not eager joins and subqueries are rendered. When set to False, the returned Query will not render eager joins regardless of :func:`~sqlalchemy.orm.joinedload`, :func:`~sqlalchemy.orm.subqueryload` options or mapper-level ``lazy='joined'``/``lazy='subquery'`` configurations. This is used primarily when nesting the Query's statement into a subquery or other selectable. N(t_enable_eagerloads(R!tvalue((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRIscCs t|_dS(sApply column labels to the return value of Query.statement. Indicates that this Query's `statement` accessor should return a SELECT statement that applies labels to all columns in the form _; this is commonly used to disambiguate columns from multiple tables which have the same name. When the `Query` actually issues SQL to load rows, it always uses column labeling. N(RgR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR[scCs ||_dS(sControl whether assertions are generated. When set to False, the returned Query will not assert its state before certain operations, including that LIMIT/OFFSET has not been applied when filter() is called, no criterion exists when get() is called, and no "from_statement()" exists when filter()/order_by()/group_by() etc. is called. This more permissive mode is used by custom Query subclasses to specify criterion or other modifiers outside of the usual usage patterns. Care should be taken to ensure that the usage pattern is even possible. A statement applied by from_statement() will override any criterion set by filter() or order_by(), for example. N(R(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytenable_assertionskscCs|jS(sA readonly attribute which returns the current WHERE criterion for this Query. This returned value is a SQL expression construct, or ``None`` if no criterion has been established. (R(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt whereclauses cCs ||_dS(sindicate that this query applies to objects loaded within a certain path. Used by deferred loaders (see strategies.py) which transfer query options from an originating query to a newly generated query intended for the deferred load. N(t _current_path(R!tpath((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_with_current_paths cCse|jstjdn|jdj}|g|jd|_|j||d|d|dS(spLoad columns for inheriting classes. :meth:`.Query.with_polymorphic` applies transformations to the "main" mapped class represented by this :class:`.Query`. The "main" mapped class here means the :class:`.Query` object's first argument is a full class, i.e. ``session.query(SomeClass)``. These transformations allow additional tables to be present in the FROM clause so that columns for a joined-inheritance subclass are available in the query, both for the purposes of load-time efficiency as well as the ability to use these columns at query time. See the documentation section :ref:`with_polymorphic` for details on how this method is used. .. versionchanged:: 0.8 A new and more flexible function :func:`.orm.with_polymorphic` supersedes :meth:`.Query.with_polymorphic`, as it can apply the equivalent functionality to any set of columns or classes in the :class:`.Query`, not just the "zero mapper". See that function for a description of arguments. s(No primary mapper set up for this Query.iiR5tpolymorphic_onN(R'RERR&Rtset_with_polymorphic(R!tcls_or_mappersR5RR9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR0s   cCs)||_|jjitd6|_dS(sMYield only ``count`` rows at a time. The purpose of this method is when fetching very large result sets (> 10K rows), to batch results in sub-collections and yield them out partially, so that the Python interpreter doesn't need to declare very large areas of memory which is both time consuming and leads to excessive memory use. The performance from fetching hundreds of thousands of rows can often double when a suitable yield-per setting (e.g. approximately 1000) is used, even with DBAPIs that buffer rows (which are most). The :meth:`.yield_per` method **is not compatible with most eager loading schemes, including joinedload and subqueryload**. See the warning below. .. warning:: Use this method with caution; if the same instance is present in more than one batch of rows, end-user changes to attributes will be overwritten. In particular, it's usually impossible to use this setting with eagerly loaded collections (i.e. any lazy='joined' or 'subquery') since those collections will be cleared for a new load when encountered in a subsequent result batch. In the case of 'subquery' loading, the full result for all rows is fetched which generally defeats the purpose of :meth:`~sqlalchemy.orm.query.Query.yield_per`. Also note that while :meth:`~sqlalchemy.orm.query.Query.yield_per` will set the ``stream_results`` execution option to True, currently this is only understood by :mod:`~sqlalchemy.dialects.postgresql.psycopg2` dialect which will stream results using server side cursors instead of pre-buffer all rows for this query. Other DBAPIs **pre-buffer all rows** before making them available. The memory use of raw database rows is much less than that of an ORM-mapped object, but should still be taken into consideration when benchmarking. tstream_resultsN(t _yield_pert_execution_optionstunionRg(R!tcount((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt yield_pers,  cCst|dr|j}ntj|}|jd}t|t|jkrtjddj d|jDn|j |}|j r|j r|j dkrtj|j|tj}|dk r|jt|j|jsdS|Sntj||S(s Return an instance based on the given primary key identifier, or ``None`` if not found. E.g.:: my_user = session.query(User).get(5) some_object = session.query(VersionedFoo).get((5, 10)) :meth:`~.Query.get` is special in that it provides direct access to the identity map of the owning :class:`.Session`. If the given primary key identifier is present in the local identity map, the object is returned directly from this collection and no SQL is emitted, unless the object has been marked fully expired. If not present, a SELECT is performed in order to locate the object. :meth:`~.Query.get` also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. If not, :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. :meth:`~.Query.get` is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. The originating :class:`.Query` must be constructed in this way, i.e. against a single mapped entity, with no additional filtering criterion. Loading options via :meth:`~.Query.options` may be applied however, and will be used if the object is not yet locally present. A lazy-loading, many-to-one attribute configured by :func:`.relationship`, using a simple foreign-key-to-primary-key criterion, will also use an operation equivalent to :meth:`~.Query.get` in order to retrieve the target value from the local identity map before querying the database. See :doc:`/orm/loading` for further details on relationship loading. :param ident: A scalar or tuple value representing the primary key. For a composite primary key, the order of identifiers corresponds in most cases to that of the mapped :class:`.Table` object's primary key columns. For a :func:`.mapper` that was given the ``primary key`` argument during construction, the order of identifiers corresponds to the elements present in this collection. :return: The object instance, or ``None``. t__composite_values__R_smIncorrect number of values in identifier to formulate primary key for query.get(); primary key columns are %st,css|]}d|VqdS(s'%s'N((t.0tc((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pys 6sN(RBRRR(RRNt primary_keyRERRtidentity_key_from_primary_keyRtalways_refresht_for_update_argR$Rtget_from_identityRRt PASSIVE_OFFRt issubclassRtclass_t load_on_ident(R!tidentR/tkeytinstance((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR_s(;#    cGs#|jjd|D|_dS(s#Return a :class:`.Query` construct which will correlate the given FROM clauses to that of an enclosing :class:`.Query` or :func:`~.expression.select`. The method here accepts mapped classes, :func:`.aliased` constructs, and :func:`.mapper` constructs as arguments, which are resolved into expression constructs, in addition to appropriate expression constructs. The correlation arguments are ultimately passed to :meth:`.Select.correlate` after coercion to expression constructs. The correlation arguments take effect in such cases as when :meth:`.Query.from_self` is used, or when a subquery as returned by :meth:`.Query.subquery` is embedded in another :func:`~.expression.select` construct. css-|]#}|dk r!t|ndVqdS(N(R$R(Rts((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pys `sN(t _correlateR(R!targs((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt correlateJs cCs ||_dS(s%Return a Query with a specific 'autoflush' setting. Note that a Session with autoflush=False will not autoflush, even if this flag is set to True at the Query level. Therefore this flag is usually used only to disable autoflush for a specific Query. N(t _autoflush(R!tsetting((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt autoflushds cCs t|_dS(sReturn a :class:`.Query` that will expire and refresh all instances as they are loaded, or reused from the current :class:`.Session`. :meth:`.populate_existing` does not improve behavior when the ORM is used normally - the :class:`.Session` object's usual behavior of maintaining a transaction and expiring all attributes after rollback or commit handles object state automatically. This method is not intended for general use. N(RgR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRps cCs ||_dS(sSet the 'invoke all eagers' flag which causes joined- and subquery loaders to traverse into already-loaded related objects and collections. Default is that of :attr:`.Query._invoke_all_eagers`. N(t_invoke_all_eagers(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_with_invoke_all_eagers~s cCs|dkrt|}xp|jD]7}t|tjr"|j|jkr"|}Pq"q"Wtj d|jj j |j j fn|j t||S(sCAdd filtering criterion that relates the given instance to a child object or collection, using its attribute state as well as an established :func:`.relationship()` configuration. The method uses the :func:`.with_parent` function to generate the clause, the result of which is passed to :meth:`.Query.filter`. Parameters are the same as :func:`.with_parent`, with the exception that the given property can be None, in which case a search is performed against this :class:`.Query` object's target mapper. s\Could not locate a property which relates instances of class '%s' to instances of class '%s'N(R$Rtiterate_propertiesRIRtRelationshipPropertyR/R~RERRt__name__RtfilterR(R!RtpropertyR/tprop((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs  cCsS|dk rt||}nt|j|_t||}|j|gdS(sIadd a mapped entity to the list of result columns to be returned.N(R$RtlistR&RR)(R!R9RKRA((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt add_entitys  cCs ||_dS(sMReturn a :class:`.Query` that will use the given :class:`.Session`. N(R(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt with_sessionscGsS|jjtjtjjd}|j|}|rO|j|n|S(sreturn a Query that selects from this Query's SELECT statement. \*entities - optional list of entities which will replace those being selected. N( RRRkt_set_enable_single_critRRR$t_from_selectableR (R!R"t fromclauseR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt from_selfs  cCs ||_dS(N(t_enable_single_crit(R!tval((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRsc Cs~x!d D]}|jj|dqW|j|gtt|_|j}g|_x%|D]}|j||j d qYWdS(NRRRRRRt _joinpathRRt_havingt _prefixesi( s _statements _criterions _order_bys _group_bys_limits_offsets _joinpaths _joinpoints _distincts_havings _prefixes( RRZR$RYRgRkRnR&tadapt_to_selectableRM(R!RRt old_entitiesRr((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs     cGsN|stdS|j}|j|dt|jsDd|_nt|S(s\Return an iterator yielding result tuples corresponding to the given list of columnsR*i ((titerRR t _ColumnEntityR(R!tcolumnsR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytvaluess    cCs4yt|j|dSWntk r/dSXdS(sLReturn a scalar result corresponding to the given column expression.iN(tnextRt StopIterationR$(R!tcolumn((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs cGs|j|dS(sJReturn a new :class:`.Query` replacing the SELECT list with the given entities. e.g.:: # Users, filtered on some arbitrary criterion # and then ordered by related email address q = session.query(User).\ join(User.address).\ filter(User.name.like('%ed%')).\ order_by(Address.email) # given *only* User.id==5, Address.email, and 'q', what # would the *next* User in the result be ? subq = q.with_entities(Address.email).\ order_by(None).\ filter(User.id==5).\ subquery() q = q.join((subq, subq.c.email < Address.email)).\ limit(1) .. versionadded:: 0.6.5 N(R (R!R"((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt with_entitiesscGsWt|j|_t|j}x|D]}t||q(W|j|j|dS(sXAdd one or more column expressions to the list of result columns to be returned.N(RR&RNRR)(R!RtlR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt add_columnss  s0.7s9:meth:`.add_column` is superseded by :meth:`.add_columns`cCs |j|S(sAdd a column expression to the list of result columns to be returned. Pending deprecation: :meth:`.add_column` will be superseded by :meth:`.add_columns`. (R (R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt add_column's cGs|jt|S(s/Return a new Query object, applying the given list of mapper options. Most supplied options regard changing how column- and relationship-mapped attributes are loaded. See the sections :ref:`deferred` and :doc:`/orm/loading` for reference documentation. (t_optionsRk(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytoptions5s cGs|jt|S(N(R Rg(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_conditional_optionsAscGs|jj|_ttj|}|j||_|r^x<|D]}|j|qDWnx|D]}|j|qeWdS(N(t _attributesR-RLRtflatten_iteratort _with_optionstprocess_query_conditionallyt process_query(R!t conditionalRtoptstopt((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR Ds  cCs ||S(sReturn a new :class:`.Query` object transformed by the given function. E.g.:: def filter_something(criterion): def transform(q): return q.filter(criterion) return transform q = q.with_transformation(filter_something(x==5)) This allows ad-hoc recipes to be created for :class:`.Query` objects. See the example at :ref:`hybrid_transformers`. .. versionadded:: 0.7.4 ((R!tfn((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytwith_transformationRst*cCs.t|j}|j|||ff7_dS(s_Add an indexing hint for the given entity or selectable to this :class:`.Query`. Functionality is passed straight through to :meth:`~sqlalchemy.sql.expression.Select.with_hint`, with the addition that ``selectable`` can be a :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class /etc. N(RR5t _with_hints(R!R5ttextt dialect_name((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt with_hintgs cKs|jj||_dS(sS Set non-SQL options which take effect during execution. The options are the same as those accepted by :meth:`.Connection.execution_options`. Note that the ``stream_results`` execution option is enabled automatically if the :meth:`~sqlalchemy.orm.query.Query.yield_per()` method is used. N(RR(R!tkwargs((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytexecution_optionsvs cCstj||_dS(s[Return a new :class:`.Query` object with the specified "locking mode", which essentially refers to the ``FOR UPDATE`` clause. .. deprecated:: 0.9.0 superseded by :meth:`.Query.with_for_update`. :param mode: a string representing the desired locking mode. Valid values are: * ``None`` - translates to no lockmode * ``'update'`` - translates to ``FOR UPDATE`` (standard SQL, supported by most dialects) * ``'update_nowait'`` - translates to ``FOR UPDATE NOWAIT`` (supported by Oracle, PostgreSQL 8.1 upwards) * ``'read'`` - translates to ``LOCK IN SHARE MODE`` (for MySQL), and ``FOR SHARE`` (for PostgreSQL) .. seealso:: :meth:`.Query.with_for_update` - improved API for specifying the ``FOR UPDATE`` clause. N(t LockmodeArgtparse_legacy_queryR(R!tmode((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt with_lockmodescCs"td|d|d||_dS(sreturn a new :class:`.Query` with the specified options for the ``FOR UPDATE`` clause. The behavior of this method is identical to that of :meth:`.SelectBase.with_for_update`. When called with no arguments, the resulting ``SELECT`` statement will have a ``FOR UPDATE`` clause appended. When additional arguments are specified, backend-specific options such as ``FOR UPDATE NOWAIT`` or ``LOCK IN SHARE MODE`` can take effect. E.g.:: q = sess.query(User).with_for_update(nowait=True, of=User) The above query on a Postgresql backend will render like:: SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT .. versionadded:: 0.9.0 :meth:`.Query.with_for_update` supersedes the :meth:`.Query.with_lockmode` method. .. seealso:: :meth:`.GenerativeSelect.with_for_update` - Core level method with full argument and behavioral description. treadtnowaittofN(R!R(R!R%R&R'((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytwith_for_updatescOspt|dkr&|j|dn$t|dkrJtjdn|jj|_|jj|dS(sadd values for bind parameters which may have been specified in filter(). parameters may be specified using \**kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that \**kwargs is convenient, however some parameter dictionaries contain unicode keys in which case \**kwargs cannot be used. iisFparams() takes zero or one positional argument, which is a dictionary.N(RNRRERFRR-(R!RR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs  cGsjxct|D]U}tj|}|j|tt}|jdk rY|j|@|_q ||_q WdS(sapply the given filtering criterion to a copy of this :class:`.Query`, using SQL expressions. e.g.:: session.query(MyClass).filter(MyClass.name == 'some name') Multiple criteria are joined together by AND:: session.query(MyClass).\ filter(MyClass.name == 'some name', MyClass.id > 5) The criterion is any SQL expression object applicable to the WHERE clause of a select. String expressions are coerced into SQL expression constructs via the :func:`.text` construct. .. versionchanged:: 0.7.5 Multiple criteria joined by AND. .. seealso:: :meth:`.Query.filter_by` - filter on keyword expressions. N(RRRfReRgRR$(R!t criterion((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs cKsPg|jD]'\}}t|j||k^q }|jtj|S(s]apply the given filtering criterion to a copy of this :class:`.Query`, using keyword expressions. e.g.:: session.query(MyClass).filter_by(name = 'some name') Multiple criteria are joined together by AND:: session.query(MyClass).\ filter_by(name = 'some name', id = 5) The keyword expressions are extracted from the primary entity of the query, or the last entity that was the target of a call to :meth:`.Query.join`. .. seealso:: :meth:`.Query.filter` - filter on SQL expressions. (titemsRRRRtand_(R!RRRtclauses((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt filter_bys7cGst|dkr^|dtkr>d|jkr:|`ndS|ddkr^d|_dSn|j|}|jtks|jdkr||_n|j||_dS(sapply one or more ORDER BY criterion to the query and return the newly resulting ``Query`` All existing ORDER BY settings can be suppressed by passing ``None`` - this will suppress any ORDER BY configured on mappers as well. Alternatively, an existing ORDER BY setting on the Query object can be entirely cancelled by passing ``False`` as the value - use this before calling methods where an ORDER BY is invalid. iiRN(RNRkRRR$Rj(R!R)((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs   cGsittg|D]}t|^q }|j|}|jtkrU||_n|j||_dS(shapply one or more GROUP BY criterion to the query and return the newly resulting :class:`.Query`N(RRR RjRRk(R!R)R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytgroup_by3s + cCst|tjr$tj|}n|dk rUt|tj rUtjdn|j |t t }|j dk r|j |@|_ n ||_ dS(s apply a HAVING criterion to the query and return the newly resulting :class:`.Query`. :meth:`~.Query.having` is used in conjunction with :meth:`~.Query.group_by`. HAVING criterion makes it possible to use filters on aggregate functions like COUNT, SUM, AVG, MAX, and MIN, eg.:: q = session.query(User.id).\ join(User.addresses).\ group_by(User.id).\ having(func.count(Address.id) > 2) sHhaving() argument must be of type sqlalchemy.sql.ClauseElement or stringN( RIRt string_typesRRR$t ClauseElementRERFReRgR(R!R)((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pythaving@s  cGs#|jtj|gt|S(sProduce a UNION of this Query against one or more queries. e.g.:: q1 = sess.query(SomeClass).filter(SomeClass.foo=='bar') q2 = sess.query(SomeClass).filter(SomeClass.bar=='foo') q3 = q1.union(q2) The method accepts multiple Query objects so as to control the level of nesting. A series of ``union()`` calls such as:: x.union(y).union(z).all() will nest on each ``union()``, and produces:: SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y) UNION SELECT * FROM Z) Whereas:: x.union(y, z).all() produces:: SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION SELECT * FROM Z) Note that many database backends do not allow ORDER BY to be rendered on a query called within UNION, EXCEPT, etc. To disable all ORDER BY clauses including those configured on mappers, issue ``query.order_by(None)`` - the resulting :class:`.Query` object will not render ORDER BY within its SELECT statement. (RRRR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRbs&cGs#|jtj|gt|S(sProduce a UNION ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. (RRt union_allR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR2scGs#|jtj|gt|S(sProduce an INTERSECT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. (RRt intersectR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR3scGs#|jtj|gt|S(sProduce an INTERSECT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. (RRt intersect_allR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR4scGs#|jtj|gt|S(sProduce an EXCEPT of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. (RRtexcept_R(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR5scGs#|jtj|gt|S(sProduce an EXCEPT ALL of this Query against one or more queries. Works the same way as :meth:`~sqlalchemy.orm.query.Query.union`. See that method for usage examples. (RRt except_allR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR6scOsi|jdt|jdt}}|rJtddj|jn|j|dtd|d|S(s&+Create a SQL JOIN against this :class:`.Query` object's criterion and apply generatively, returning the newly resulting :class:`.Query`. **Simple Relationship Joins** Consider a mapping between two classes ``User`` and ``Address``, with a relationship ``User.addresses`` representing a collection of ``Address`` objects associated with each ``User``. The most common usage of :meth:`~.Query.join` is to create a JOIN along this relationship, using the ``User.addresses`` attribute as an indicator for how this should occur:: q = session.query(User).join(User.addresses) Where above, the call to :meth:`~.Query.join` along ``User.addresses`` will result in SQL equivalent to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to :meth:`~.Query.join` as the *on clause*, that is, it indicates how the "ON" portion of the JOIN should be constructed. For a single-entity query such as the one above (i.e. we start by selecting only from ``User`` and nothing else), the relationship can also be specified by its string name:: q = session.query(User).join("addresses") :meth:`~.Query.join` can also accommodate multiple "on clause" arguments to produce a chain of joins, such as below where a join across four related entities is constructed:: q = session.query(User).join("orders", "items", "keywords") The above would be shorthand for three separate calls to :meth:`~.Query.join`, each using an explicit attribute to indicate the source entity:: q = session.query(User).\ join(User.orders).\ join(Order.items).\ join(Item.keywords) **Joins to a Target Entity or Selectable** A second form of :meth:`~.Query.join` allows any mapped entity or core selectable construct as a target. In this usage, :meth:`~.Query.join` will attempt to create a JOIN along the natural foreign key relationship between two entities:: q = session.query(User).join(Address) The above calling form of :meth:`~.Query.join` will raise an error if either there are no foreign keys between the two entities, or if there are multiple foreign key linkages between them. In the above calling form, :meth:`~.Query.join` is called upon to create the "on clause" automatically for us. The target can be any mapped entity or selectable, such as a :class:`.Table`:: q = session.query(User).join(addresses_table) **Joins to a Target with an ON Clause** The third calling form allows both the target entity as well as the ON clause to be passed explicitly. Suppose for example we wanted to join to ``Address`` twice, using an alias the second time. We use :func:`~sqlalchemy.orm.aliased` to create a distinct alias of ``Address``, and join to it using the ``target, onclause`` form, so that the alias can be specified explicitly as the target along with the relationship to instruct how the ON clause should proceed:: a_alias = aliased(Address) q = session.query(User).\ join(User.addresses).\ join(a_alias, User.addresses).\ filter(Address.email_address=='ed@foo.com').\ filter(a_alias.email_address=='ed@bar.com') Where above, the generated SQL would be similar to:: SELECT user.* FROM user JOIN address ON user.id = address.user_id JOIN address AS address_1 ON user.id=address_1.user_id WHERE address.email_address = :email_address_1 AND address_1.email_address = :email_address_2 The two-argument calling form of :meth:`~.Query.join` also allows us to construct arbitrary joins with SQL-oriented "on clause" expressions, not relying upon configured relationships at all. Any SQL expression can be passed as the ON clause when using the two-argument form, which should refer to the target entity in some way as well as an applicable source entity:: q = session.query(User).join(Address, User.id==Address.user_id) .. versionchanged:: 0.7 In SQLAlchemy 0.6 and earlier, the two argument form of :meth:`~.Query.join` requires the usage of a tuple: ``query(User).join((Address, User.id==Address.user_id))``\ . This calling form is accepted in 0.7 and further, though is not necessary unless multiple join conditions are passed to a single :meth:`~.Query.join` call, which itself is also not generally necessary as it is now equivalent to multiple calls (this wasn't always the case). **Advanced Join Targeting and Adaption** There is a lot of flexibility in what the "target" can be when using :meth:`~.Query.join`. As noted previously, it also accepts :class:`.Table` constructs and other selectables such as :func:`.alias` and :func:`.select` constructs, with either the one or two-argument forms:: addresses_q = select([Address.user_id]).\ where(Address.email_address.endswith("@bar.com")).\ alias() q = session.query(User).\ join(addresses_q, addresses_q.c.user_id==User.id) :meth:`~.Query.join` also features the ability to *adapt* a :meth:`~sqlalchemy.orm.relationship` -driven ON clause to the target selectable. Below we construct a JOIN from ``User`` to a subquery against ``Address``, allowing the relationship denoted by ``User.addresses`` to *adapt* itself to the altered target:: address_subq = session.query(Address).\ filter(Address.email_address == 'ed@foo.com').\ subquery() q = session.query(User).join(address_subq, User.addresses) Producing SQL similar to:: SELECT user.* FROM user JOIN ( SELECT address.id AS id, address.user_id AS user_id, address.email_address AS email_address FROM address WHERE address.email_address = :email_address_1 ) AS anon_1 ON user.id = anon_1.user_id The above form allows one to fall back onto an explicit ON clause at any time:: q = session.query(User).\ join(address_subq, User.id==address_subq.c.user_id) **Controlling what to Join From** While :meth:`~.Query.join` exclusively deals with the "right" side of the JOIN, we can also control the "left" side, in those cases where it's needed, using :meth:`~.Query.select_from`. Below we construct a query against ``Address`` but can still make usage of ``User.addresses`` as our ON clause by instructing the :class:`.Query` to select first from the ``User`` entity:: q = session.query(Address).select_from(User).\ join(User.addresses).\ filter(User.name == 'ed') Which will produce SQL similar to:: SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 **Constructing Aliases Anonymously** :meth:`~.Query.join` can construct anonymous aliases using the ``aliased=True`` flag. This feature is useful when a query is being joined algorithmically, such as when querying self-referentially to an arbitrary depth:: q = session.query(Node).\ join("children", "children", aliased=True) When ``aliased=True`` is used, the actual "alias" construct is not explicitly available. To work with it, methods such as :meth:`.Query.filter` will adapt the incoming entity to the last join point:: q = session.query(Node).\ join("children", "children", aliased=True).\ filter(Node.name == 'grandchild 1') When using automatic aliasing, the ``from_joinpoint=True`` argument can allow a multi-node join to be broken into multiple calls to :meth:`~.Query.join`, so that each path along the way can be further filtered:: q = session.query(Node).\ join("children", aliased=True).\ filter(Node.name='child 1').\ join("children", aliased=True, from_joinpoint=True).\ filter(Node.name == 'grandchild 1') The filtering aliases above can then be reset back to the original ``Node`` entity using :meth:`~.Query.reset_joinpoint`:: q = session.query(Node).\ join("children", "children", aliased=True).\ filter(Node.name == 'grandchild 1').\ reset_joinpoint().\ filter(Node.name == 'parent 1) For an example of ``aliased=True``, see the distribution example :ref:`examples_xmlpersistence` which illustrates an XPath-like query system using algorithmic joins. :param \*props: A collection of one or more join conditions, each consisting of a relationship-bound attribute or string relationship name representing an "on clause", or a single target entity, or a tuple in the form of ``(target, onclause)``. A special two-argument calling form of the form ``target, onclause`` is also accepted. :param aliased=False: If True, indicate that the JOIN target should be anonymously aliased. Subsequent calls to :meth:`~.Query.filter` and similar will adapt the incoming criterion to the target alias, until :meth:`~.Query.reset_joinpoint` is called. :param from_joinpoint=False: When using ``aliased=True``, a setting of True here will cause the join to be from the most recent joined target, rather than starting back from the original FROM clauses of the query. .. seealso:: :ref:`ormtutorial_joins` in the ORM tutorial. :ref:`inheritance_toplevel` for details on how :meth:`~.Query.join` is used for inheritance relationships. :func:`.orm.join` - a standalone ORM-level join function, used internally by :meth:`.Query.join`, which in previous SQLAlchemy versions was the primary ORM-level joining interface. Rtfrom_joinpointsunknown arguments: %sRt outerjointcreate_aliases(RZRkt TypeErrorRtkeyst_join(R!tpropsRRR7((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs  cOsf|jdt|jdt}}|rGtddj|n|j|dtd|d|S(sCreate a left outer join against this ``Query`` object's criterion and apply generatively, returning the newly resulting ``Query``. Usage is the same as the ``join()`` method. RR7sunknown arguments: %sRR8R9(RZRkR:RR<Rg(R!R=RRR7((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR8s  cCse||_xLd|krW|d\}}|j}|||<||f|d<|}q W||_dS(Ntprev(RR-R(R!tjptfR>((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_update_joinpoints    c Cs|s|jnt|dkrrt|dtjttfrrt|dttjt j frr|f}nx{t j |D]j}t|t r|\}}nd }t|t j t jfr||}}n ||}}d } } t|t jr$|j} t| |} | }n|rt|t j r|j} t|j} t| dd | jt| dd } }}| | kr|j} t| |j} | }qnt|t j r|d kr|jj}t|dd }|r|}q|jj}n|j} |j} t|tjsC| }n|s| || jf}||jkr|j|j}||jf|d<|j|qqqn'|d k r|d krtdn|j| ||||| qWd S( sconsumes arguments from join() or outerjoin(), places them into a consistent format with which to form the actual JOIN constructs. iiiR/R.t_of_typeR>squery.join(a==b) not supported.N( t_reset_joinpointRNRIRRattypeR tstrR0RtPropComparatorRR(RLR$R/RRt _parententityRRuR5RRR/RtQueryableAttributeRR-RAtNotImplementedErrort_join_left_to_right(R!R;R8R9R7targ1targ2t right_entitytonclauset left_entityRt descriptorRWt left_mappertleft_selectabletleft_is_aliasedtof_typetedgeR?((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR<sr                   c CsE|jj|_|dkrV|jr7|jd}qV|jrV|jdj}qVn|dkrtjd|jdn||kr| rtjd||fnt|}t|}t } |st |dd} | r_| j st | j tjr_xu|jp|jgD]:} tj|j| rtj| |jrt} PqqWqtj|j|jrt} qn| r|j|jkrtjd|jn|j|||||| \}}| r|r|ji|d6|||jf|jfd6ni|d6|_|j|||||dS( s)append a JOIN to the query's from clause.ismDon't know how to join from %s; please use select_from() to establish the left entity/selectable of this joins>Can't construct a join from %s to %s, they are the same entityR/s*Can't join table/selectable '%s' to itselfRR>N(RR-R$RMR&tentity_zero_or_selectableRERRRkRuR0RIR1RtJoinR5R3tselectables_overlapRgt_prepare_right_sideRARRt _join_to_left( R!tlefttrightRNR8R9Rtl_infotr_infotoverlapt right_mapperRV((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRJDs^               #c Cs$|}t|dd|jt|dt}} } |rP|j|f7_n|r|r|j|j rtjd||fn| r|r|j}nt} |r,|| kr,| j |j stjd| j |j j fnt | t jr| j} t} nt|| }n|oZ| oZ|jrWt |jt jpZ|} | r|sp| rt|dt}t} n| rt|d|r|jpid|j|_nt |t jr|j|tt}n| r| r|j|t|d|jn||fS(NR/R.sIJoin target %s does not correspond to the right side of join condition %ss(Selectable '%s' is not derived from '%s'tflatt equivalentstchain_to(RuR$R5Rkt_join_entitiest common_parentR/RERtis_derived_fromR1t descriptionRIRRJRKRgRR0t_with_polymorphic_selectableRORR6RvR0ReR2( R!R^R\RNR9RR_RWR`tright_selectabletright_is_aliasedt need_adaptertaliased_entity((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRYsb          c Cs|}t|dd}|j}|jrtj|j|\} } | dk ryt| ||d|} Wn/tjk r} tj d|| fnX|j| | f|j| d|_dSn|r x<|j D]"} | j |r| j} PqqW|} n|} | dk s#t yt| ||d|} Wn/tjk rp} tj d|| fnX|j| f|_dS(NR/tisoutersLCould not find a FROM clause to join from. Tried joining to %s, but got: %si( RuR$R5RMR3tfind_join_sourcetorm_joinRERFRR&tcorresponds_totAssertionError( R!R]R[R\RNR8RWRQRRtreplace_clause_indexRytaeR+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRZsD     cCs|j|_d|_dS(N(RRR$Rv(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRC s cCs|jdS(sSReturn a new :class:`.Query`, where the "join point" has been reset back to the base FROM entities of the query. This method is usually used in conjunction with the ``aliased=True`` feature of the :meth:`~.Query.join` method. See the example in :meth:`~.Query.join` for how this is used. N(RC(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytreset_joinpoints cGs|j|tdS(sPSet the FROM clause of this :class:`.Query` explicitly. :meth:`.Query.select_from` is often used in conjunction with :meth:`.Query.join` in order to control which entity is selected from on the "left" side of the join. The entity or selectable object here effectively replaces the "left edge" of any calls to :meth:`~.Query.join`, when no joinpoint is otherwise established - usually, the default "join point" is the leftmost entity in the :class:`~.Query` object's list of entities to be selected. A typical example:: q = session.query(Address).select_from(User).\ join(User.addresses).\ filter(User.name == 'ed') Which produces SQL equivalent to:: SELECT address.* FROM user JOIN address ON user.id=address.user_id WHERE user.name = :name_1 :param \*from_obj: collection of one or more entities to apply to the FROM clause. Entities can be mapped classes, :class:`.AliasedClass` objects, :class:`.Mapper` objects as well as core :class:`.FromClause` elements like subqueries. .. versionchanged:: 0.9 This method no longer applies the given FROM object to be the selectable from which matching entities select from; the :meth:`.select_entity_from` method now accomplishes this. See that method for a description of this behavior. .. seealso:: :meth:`~.Query.join` :meth:`.Query.select_entity_from` N(RYRk(R!RV((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt select_froms.cCs|j|gtdS(s Set the FROM clause of this :class:`.Query` to a core selectable, applying it as a replacement FROM clause for corresponding mapped entities. This method is similar to the :meth:`.Query.select_from` method, in that it sets the FROM clause of the query. However, where :meth:`.Query.select_from` only affects what is placed in the FROM, this method also applies the given selectable to replace the FROM which the selected entities would normally select from. The given ``from_obj`` must be an instance of a :class:`.FromClause`, e.g. a :func:`.select` or :class:`.Alias` construct. An example would be a :class:`.Query` that selects ``User`` entities, but uses :meth:`.Query.select_entity_from` to have the entities selected from a :func:`.select` construct instead of the base ``user`` table:: select_stmt = select([User]).where(User.id == 7) q = session.query(User).\ select_entity_from(select_stmt).\ filter(User.name == 'ed') The query generated will select ``User`` entities directly from the given :func:`.select` construct, and will be:: SELECT anon_1.id AS anon_1_id, anon_1.name AS anon_1_name FROM (SELECT "user".id AS id, "user".name AS name FROM "user" WHERE "user".id = :id_1) AS anon_1 WHERE anon_1.name = :name_1 Notice above that even the WHERE criterion was "adapted" such that the ``anon_1`` subquery effectively replaces all references to the ``user`` table, except for the one that it refers to internally. Compare this to :meth:`.Query.select_from`, which as of version 0.9, does not affect existing entities. The statement below:: q = session.query(User).\ select_from(select_stmt).\ filter(User.name == 'ed') Produces SQL where both the ``user`` table as well as the ``select_stmt`` construct are present as separate elements in the FROM clause. No "adaptation" of the ``user`` table is applied:: SELECT "user".id AS user_id, "user".name AS user_name FROM "user", (SELECT "user".id AS id, "user".name AS name FROM "user" WHERE "user".id = :id_1) AS anon_1 WHERE "user".name = :name_1 :meth:`.Query.select_entity_from` maintains an older behavior of :meth:`.Query.select_from`. In modern usage, similar results can also be achieved using :func:`.aliased`:: select_stmt = select([User]).where(User.id == 7) user_from_select = aliased(User, select_stmt.alias()) q = session.query(user_from_select) :param from_obj: a :class:`.FromClause` object that will replace the FROM clause of this :class:`.Query`. .. seealso:: :meth:`.Query.select_from` .. versionadded:: 0.8 :meth:`.Query.select_entity_from` was added to specify the specific behavior of entity replacement, however the :meth:`.Query.select_from` maintains this behavior as well until 0.9. N(RYRg(R!RV((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytselect_entity_fromLsSc Cst|trtj|\}}}t|trYt|trY||dkrYgSt|trt|dkst|tr|dkrt||S|j||}|dk rt|dd|jSt|Sn3|dkrt|dSt|||d!dSdS(Niii(RItsliceRt decode_slicetintRR$tstep(R!titemtstarttstopRztres((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt __getitem__s    cCs|dk r>|dk r>|jp$d||_|||_nU|dkrb|dk rb||_n1|dk r|dkr|jpd||_n|jdkrd|_ndS(siapply LIMIT/OFFSET to the ``Query`` based on a " "range and return the newly resulting ``Query``.iN(R$RR(R!R|R}((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRws cCs ||_dS(s[Apply a ``LIMIT`` to the query and return the newly resulting ``Query``. N(R(R!tlimit((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRscCs ||_dS(s\Apply an ``OFFSET`` to the query and return the newly resulting ``Query``. N(R(R!toffset((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRscGsR|st|_n<|j|}t|jtrE|j|7_n ||_dS(sApply a ``DISTINCT`` to the query and return the newly resulting ``Query``. :param \*expr: optional column expressions. When present, the Postgresql dialect will render a ``DISTINCT ON (>)`` construct. N(RgRRjRIR(R!R)((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs  cGs(|jr|j|7_n ||_dS(s-Apply the prefixes to the query and return the newly resulting ``Query``. :param \*prefixes: optional prefixes, typically strings, not using any commas. In particular is useful for MySQL keywords. e.g.:: query = sess.query(User.name).\ prefix_with('HIGH_PRIORITY').\ prefix_with('SQL_SMALL_RESULT', 'ALL') Would render:: SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name FROM users .. versionadded:: 0.7.7 N(R(R!tprefixes((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt prefix_withs cCs t|S(sReturn the results represented by this ``Query`` as a list. This results in an execution of the underlying query. (R(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytall scCs^t|tjr$tj|}nt|tjtjfsQtj dn||_ dS(s%Execute the given SELECT statement and return results. This method bypasses all internal statement compilation, and the statement is executed without modification. The statement is typically either a :func:`~.expression.text` or :func:`~.expression.select` construct, and should return the set of columns appropriate to the entity class represented by this :class:`.Query`. .. seealso:: :ref:`orm_tutorial_literal_sql` - usage examples in the ORM tutorial sBfrom_statement accepts text(), select(), and union() objects only.N( RIRR/RRRt TextClauseRJRERFR(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytfrom_statement s cCsZ|jdk r%t|dd!}nt|dd!}t|dkrR|dSdSdS(sReturn the first result of this ``Query`` or None if the result doesn't contain any row. first() applies a limit of one within the generated SQL, so that only one primary entity row is generated on the server side (note this may consist of multiple result rows if join-loaded collections are present). Calling ``first()`` results in an execution of the underlying query. iiN(RR$RRN(R!tret((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytfirst0 s cCs]t|}t|}|dkr,|dS|dkrJtjdntjddS(sReturn exactly one result or raise an exception. Raises ``sqlalchemy.orm.exc.NoResultFound`` if the query selects no rows. Raises ``sqlalchemy.orm.exc.MultipleResultsFound`` if multiple object identities are returned, or if multiple rows are returned for a query that does not return object identities. Note that an entity query, that is, one which selects one or more mapped classes as opposed to individual column attributes, may ultimately represent many rows but only one row of unique entity or entities - this is a successful result for one(). Calling ``one()`` results in an execution of the underlying query. .. versionchanged:: 0.6 ``one()`` fully fetches all results instead of applying any kind of limit, so that the "unique"-ing of entities does not conceal multiple object identities. iisNo row was found for one()s"Multiple rows were found for one()N(RRNtorm_exct NoResultFoundtMultipleResultsFound(R!RR ((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytoneE s    cCsGy+|j}t|ts"|S|dSWntjk rBdSXdS(s4Return the first element of the first result or None if no rows present. If multiple rows are returned, raises MultipleResultsFound. >>> session.query(Item).scalar() >>> session.query(Item.id).scalar() 1 >>> session.query(Item.id).filter(Item.id < 0).scalar() None >>> session.query(Item.id, Item.name).scalar() 1 >>> session.query(func.count(Parent.id)).scalar() 20 This results in an execution of the underlying query. iN(RRIRLRRR$(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytscalarf s  cCsH|j}t|j_|jr;|j r;|jjn|j|S(N(RRgRt use_labelsRRRt_execute_and_instances(R!tcontext((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt__iter__ s   cKs4|jj|}|jr0|j|j}n|S(N(Rt connectionRR (R!tkwtconn((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_connection_from_session s    cCsR|jd|jd|jdt}|j|j|j}tj|||S(NR/Rytclose_with_result(RRRRgtexecuteRRt instances(R!t querycontextRtresult((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s     cCsKg|jD]=}i|jd6|jd6t|dtd6|jd6^q S(sReturn metadata about the columns which would be returned by this :class:`.Query`. Format is a list of dictionaries:: user_alias = aliased(User, name='user2') q = sess.query(User, User.id, user_alias) # this expression: q.column_descriptions # would return: [ { 'name':'User', 'type':User, 'aliased':False, 'expr':User, }, { 'name':'id', 'type':Integer(), 'aliased':False, 'expr':User.id, }, { 'name':'user2', 'type':User, 'aliased':True, 'expr':user_alias } ] RRDR.Rtexpr(R&t _label_nameRDRuRkR(R!R+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytcolumn_descriptions s%cCs4|}|dkr!t|}ntj|||S(sGiven a ResultProxy cursor as returned by connection.execute(), return an ORM result as an iterator. e.g.:: result = engine.execute("select * from users") for u in session.query(User).instances(result): print u N(R$RRR(R!tcursort_Query__contextR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s  cCstj|||S(s?Merge a result into this :class:`.Query` object's Session. Given an iterator returned by a :class:`.Query` of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using :meth:`.Session.merge`. This is an optimized method which will merge all mapped instances, preserving the structure of the result rows and unmapped columns with less method overhead than that of calling :meth:`.Session.merge` explicitly for each value. The structure of the results is determined based on the column list of this :class:`.Query` - if these do not correspond, unchecked errors will occur. The 'load' argument is the same as that of :meth:`.Session.merge`. For an example of how :meth:`~.Query.merge_result` is used, see the source code for the example :ref:`examples_caching`, where :meth:`~.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. (Rt merge_result(R!titeratortload((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR scCsFi|jd6|jd6|jd6|jd6|jp7dd6|jd6S(NRRRRR.R1(RRRRRR$R(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt _select_args s    cCsC|j}|jddk pB|jddk pB|jdtS(NRRR(RR_R$Rk(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_should_nest_selectable s cCs+tj|jdjjjdgS(sA convenience method that turns a query into an EXISTS subquery of the form EXISTS (SELECT 1 FROM ... WHERE ...). e.g.:: q = session.query(User).filter(User.name == 'fred') session.query(q.exists()) Producing SQL similar to:: SELECT EXISTS ( SELECT 1 FROM users WHERE users.name = :name_1 ) AS anon_1 The EXISTS construct is usually used in the WHERE clause:: session.query(User.id).filter(q.exists()).scalar() Note that some databases such as SQL Server don't allow an EXISTS expression to be present in the columns clause of a SELECT. To select a simple boolean value based on the exists as a WHERE, use :func:`.literal`:: from sqlalchemy import literal session.query(literal(True)).filter(q.exists()).scalar() .. versionadded:: 0.8.1 t1(RtexistsR RRtwith_only_columns(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s%cCs.tjjtjd}|j|jS(soReturn a count of rows this Query would return. This generates the SQL for this Query as follows:: SELECT count(1) AS count_1 FROM ( SELECT ) AS anon_1 .. versionchanged:: 0.7 The above scheme is newly refined as of 0.7b3. For fine grained control over specific columns to count, to skip the usage of a subquery or otherwise control of the FROM clause, or to use other aggregate functions, use :attr:`~sqlalchemy.sql.expression.func` expressions in conjunction with :meth:`~.Session.query`, i.e.:: from sqlalchemy import func # count User records, without # using a subquery. session.query(func.count(User.id)) # return count of user "id" grouped # by "name" session.query(func.count(User.id)).\ group_by(User.name) from sqlalchemy import distinct # count distinct "name" values session.query(func.count(distinct(User.name))) R(RtfuncRtliteral_columnRR(R!tcol((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR* s%tevaluatecCs&tjj||}|j|jS(sD Perform a bulk delete query. Deletes rows matched by this query from the database. :param synchronize_session: chooses the strategy for the removal of matched objects from the session. Valid values are: ``False`` - don't synchronize the session. This option is the most efficient and is reliable once the session is expired, which typically occurs after a commit(), or explicitly using expire_all(). Before the expiration, objects may still remain in the session which were in fact deleted which can lead to confusing results if they are accessed via get() or already loaded collections. ``'fetch'`` - performs a select query before the delete to find objects that are matched by the delete query and need to be removed from the session. Matched objects are removed from the session. ``'evaluate'`` - Evaluate the query's criteria in Python straight on the objects in the session. If evaluation of the criteria isn't implemented, an error is raised. In that case you probably want to use the 'fetch' strategy as a fallback. The expression evaluator currently doesn't account for differing string collations between the database and Python. :return: the count of rows matched as returned by the database's "row count" feature. This method has several key caveats: * The method does **not** offer in-Python cascading of relationships - it is assumed that ON DELETE CASCADE/SET NULL/etc. is configured for any foreign key references which require it, otherwise the database may emit an integrity violation if foreign key references are being enforced. After the DELETE, dependent objects in the :class:`.Session` which were impacted by an ON DELETE may not contain the current state, or may have been deleted. This issue is resolved once the :class:`.Session` is expired, which normally occurs upon :meth:`.Session.commit` or can be forced by using :meth:`.Session.expire_all`. Accessing an expired object whose row has been deleted will invoke a SELECT to locate the row; when the row is not found, an :class:`~sqlalchemy.orm.exc.ObjectDeletedError` is raised. * The :meth:`.MapperEvents.before_delete` and :meth:`.MapperEvents.after_delete` events are **not** invoked from this method. Instead, the :meth:`.SessionEvents.after_bulk_delete` method is provided to act upon a mass DELETE of entity rows. .. seealso:: :meth:`.Query.update` :ref:`inserts_and_updates` - Core SQL tutorial (Rt BulkDeletetfactorytexec_trowcount(R!tsynchronize_sessiont delete_op((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytdeleteR sA   cCs)tjj|||}|j|jS(s Perform a bulk update query. Updates rows matched by this query in the database. :param values: a dictionary with attributes names as keys and literal values or sql expressions as values. :param synchronize_session: chooses the strategy to update the attributes on objects in the session. Valid values are: ``False`` - don't synchronize the session. This option is the most efficient and is reliable once the session is expired, which typically occurs after a commit(), or explicitly using expire_all(). Before the expiration, updated objects may still remain in the session with stale values on their attributes, which can lead to confusing results. ``'fetch'`` - performs a select query before the update to find objects that are matched by the update query. The updated attributes are expired on matched objects. ``'evaluate'`` - Evaluate the Query's criteria in Python straight on the objects in the session. If evaluation of the criteria isn't implemented, an exception is raised. The expression evaluator currently doesn't account for differing string collations between the database and Python. :return: the count of rows matched as returned by the database's "row count" feature. This method has several key caveats: * The method does **not** offer in-Python cascading of relationships - it is assumed that ON UPDATE CASCADE is configured for any foreign key references which require it, otherwise the database may emit an integrity violation if foreign key references are being enforced. After the UPDATE, dependent objects in the :class:`.Session` which were impacted by an ON UPDATE CASCADE may not contain the current state; this issue is resolved once the :class:`.Session` is expired, which normally occurs upon :meth:`.Session.commit` or can be forced by using :meth:`.Session.expire_all`. * As of 0.8, this method will support multiple table updates, as detailed in :ref:`multi_table_updates`, and this behavior does extend to support updates of joined-inheritance and other multiple table mappings. However, the **join condition of an inheritance mapper is currently not automatically rendered**. Care must be taken in any multiple-table update to explicitly include the joining condition between those tables, even in mappings where this is normally automatic. E.g. if a class ``Engineer`` subclasses ``Employee``, an UPDATE of the ``Engineer`` local table using criteria against the ``Employee`` local table might look like:: session.query(Engineer).\ filter(Engineer.id == Employee.id).\ filter(Employee.name == 'dilbert').\ update({"engineer_type": "programmer"}) * The :meth:`.MapperEvents.before_update` and :meth:`.MapperEvents.after_update` events are **not** invoked from this method. Instead, the :meth:`.SessionEvents.after_bulk_update` method is provided to act upon a mass UPDATE of entity rows. .. seealso:: :meth:`.Query.delete` :ref:`inserts_and_updates` - Core SQL tutorial (Rt BulkUpdateRRR(R!RRt update_op((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR sR  cCs:t|}|jdk r|S||_|j|_x!|jD]}|j||q>Wx)|jD]}|d}||dqbW|jrt |j|_ n |j |_ |j r|j |n|j s|jrtjdqtjdn|jr$|jr$|j||_n|j||_|S(NiisyNo column-based properties specified for refresh operation. Use session.expire() to reload collections and related items.s4Query contains no columns with which to SELECT from.(RRR$RRR&t setup_contexttcreate_eager_joinst from_clauseRtfromsRt_adjust_for_single_inheritancetprimary_columnsRRERtmulti_row_eager_loadersRt_compound_eager_statementt_simple_statement(R!RRR9trectstrategy((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s2           c Cs|jr=ttg|jD]}tj|^q}nd|_g}tj|j||j d|j d|j d|j|j }x |j D]}|j|}qW|jr|j|j}n|j}|j}tj|||_tj|g|jd|j }|j|_|}x/|jjD]} tj|| | j}q;W|j||jr|j|jj|jn|j|j|S(NRVRR(RRRR3tunwrap_order_byR$RtselectRRRRRRRRRRKRPR4R?tsecondary_columnsRt eager_joinsRt splice_joinststop_ont append_fromtappend_order_bytcopy_and_processteager_order_by( R!RRitorder_by_col_exprtinnerthintRXRRt eager_join((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR sJ +              c Cs5|jsd|_n|jrj|jrjttg|jD]}tj|^q7}|j|7_n|jt |j j 7_t j |j|j|jd|jd|jd|j|j}|j|_x |jD]}|j|}qW|jr|j|j}n|jr1|j|jn|S(NRVRR(RR$RRRR3RRRRLRRRRRRRRRRRRRRR(R!RRiRRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR` s2  (       cCsxt|jjD]\}}||jkr7qn|jj}|dk r|rg|j|}n|j|t t }t j t j j |j||_qqWdS(s@Apply single-table-inheritance filtering. For all distinct single-table-inheritance mappers represented in the columns clause of this query, add criterion to the WHERE clause of the given QueryContext such that only the appropriate subtypes are selected from the total results. N(RR,RRdR/t_single_table_criterionR$ttraverseReRkRR+tTrue_t_ifnoneR(R!RR:R?t single_crit((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s "  cCst|jjS(N(RERR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt__str__ sN(((((Rt __module__t__doc__RgRRRkRR$RRRRRRRRRRRt frozensetRRRRRRRRMRdRDR,RvRQRt immutabledictRRRRRRRRt_path_registryRR#R R)R2RYR[RdRjR RmReR|R~RRRRRRRRPRRRRRRRRRRRRRRRR5RRRRRRR0RR_RRRRRRRRRRRt_valuesRR R tpending_deprecationR RRR RRR R$R(RRR-RR.R1RR2R3R4R5R6RR8RAR<RJRYRZRCRtRuRvRRwRRRRRRRRRRRRRRRRRRRRRRRRRR(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR1sJ      !  #    9             <    $0 Z  "       $   " )  j F U ,  0U     !    .    ( ( F W . C $ (t ForUpdateArgR!cBseZedZRS(cCs|dtfkrdS|dkr1t}t}nG|dkrJt}}n.|dkret}t}ntjd|td|d|S(NR%Rt update_nowaits"Unknown with_lockmode argument: %rR&(R$RkRgRERFR!(R!R#R%R&((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR" s       (RRt classmethodR"(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR! sR%cBs eZdZdZdZRS(s:represent an entity column returned within a Query result.cOsl|tkr_|d}t|tj r>t|r>t}q_t|trVt}q_t}nt j |S(Ni( R%RIRR/R RtBundlet _BundleEntityRtobjectR(RRRR9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s      cCs+|jj|j}|jj|_|S(N(RRRR-(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s(RRRRR(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR% s RcBseZdZdZeZdZdZeZ e dZ e dZ dZ dZdZd Zd Zd ZRS( s mapper/class/AliasedClass entitycCs>|js||_n|jj||g|_||_dS(N(R'R&RGR"R(R!tqueryR9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR# s    cCs|j|_||_|j|_|j|_|j|_|j|_||_|jri|jj |_ n|jj j |_ |jj |_t|jjj|_dS(N(R/R;R5R.twith_polymorphic_mapperst_with_polymorphicRt_polymorphic_discriminatorR}RRRRRRtbooltdispatcht append_resultt custom_rows(R!R:R;((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR7 s        cCs|jrtdn|dkr8|j|jdS|jj||\}}||_||_||_|j |jt j ||jj dS(sReceive an update from a call to query.with_polymorphic(). Note the newer style of using a free standing with_polymporphic() construct doesn't make use of this method. s6Can't use with_polymorphic() against an Aliased objectN( R.RIR$R[R/t_with_polymorphic_argsRRR5R2R3R4R6(R!RRR5RtmappersRV((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s        cCs |jjS(N(R/R(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRD scCs|jS(N(R}(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRV scCst|jr2|jr.|j|jjkr.tSntS|jrd|jjrT||jkS||jkSn|j|jS(N(R.t _base_aliasR}RgRkt_use_mapper_pathRRe(R!R9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRp s     cCs|jj|dS(N(R&RG(R!Rtsel((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR scCsyd}|js6|jr?|jj|jd}q?n |j}|rl|jrc|j|j}qu|}n |j}|S(N(R$R.RR_R/R;RQtwrap(R!RRR?R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt_get_entity_clauses s      c Cs|j||}|jr6|r6|j|j}n|sH|j}n| ry|jjrytj|j|jj}n|j |krt j |j||j |d|j d|jd|j}n't j |j||j |d|j}||jfS(NRRtpolymorphic_discriminator(RR?RR/t_requires_row_aliasingR3R4R5R6R'Rtinstance_processorRRRRR(R!RRRR?t _instance((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt row_processor4 s2    c Csb|j||}|j|jf7_|jtkr{|jjr{|jj|_|r{|jtj|j|_q{n|j r|jj |j }n |jj }xZ|D]R}|j r|j |j krqn|j|||j|d|j d|jqW|jdk r^|j|jjk r^|rB|j|j}n |j}|jj|ndS(NRtcolumn_collection(RRR5RRkR/t adapt_listRR(Rt_iterate_polymorphic_propertiest_polymorphic_propertiesRRtsetupRRRR$RRRG(R!RRR?tpoly_propertiesRtpd((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRY s<       cCs t|jS(N(RER/(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s(RRRR#Rgtsupports_single_entityR7Rtidt filter_fnRRDRVRpRRRRR(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s       % .RcBs\eZdZeZdZdZdZdZ dZ e dZ dZ dZRS(s>A grouping of SQL expressions that are returned by a :class:`.Query` under one namespace. The :class:`.Bundle` essentially allows nesting of the tuple-based results returned by a column-oriented :class:`.Query` object. It also is extensible via simple subclassing, where the primary capability to override is that of how the set of expressions should be returned, allowing post-processing as well as custom return types, without involving ORM identity-mapped classes. .. versionadded:: 0.9.0 .. seealso:: :ref:`bundles` cOsb||_|_||_t|_|_|jjd|D|jd|j|_dS(sQConstruct a new :class:`.Bundle`. e.g.:: bn = Bundle("mybundle", MyClass.x, MyClass.y) for row in session.query(bn).filter( bn.c.x == 5).filter(bn.c.y == 4): print(row.mybundle.x, row.mybundle.y) :param name: name of the bundle. :param \*exprs: columns or SQL expressions comprising the bundle. :param single_entity=False: if True, rows for this :class:`.Bundle` can be returned as a "single entity" outside of any enclosing tuple in the same manner as a mapped entity. css*|] }t|d|j|fVqdS(RN(Rut_label(RR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pys st single_entityN( RRtexprsRRRRRZR(R!RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR# s   cCs,|jj|j}|jj|j|S(N(RRRR(R!tcloned((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR scCstjdt|jS(Ntgroup(Rt ClauseListRkR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR scCs |jjS(N(RR,(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR, scCs|j}||_|S(s<Provide a copy of this :class:`.Bundle` passing a new label.(RR(R!RR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s  csfd}|S(sProduce the "row processing" function for this :class:`.Bundle`. May be overridden by subclasses. .. seealso:: :ref:`bundles` - includes an example of subclassing. cs,tjgD]}||d^q S(N(Rt KeyedTupleR$(trowRtproc(Rtprocs(sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s((R!RRRR((RRsZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytcreate_row_processor s N(RRRRkRR#R$RRRRRR,RR (((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s    RcBseeZedZeZedZdZedZ dZ dZ dZ dZ RS(cCs|jj|||_|_t||_|j|_g|_|rxF|jD]8}t|t ryt ||qTt ||d|qTWnd|_ d|_ |jj|_dS(Nt namespacecSs|S(N((R{((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt s((R&RGtbundleRRDRRRRIRRRR"RRR(R!RR tsetup_entitiesR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR# s    cCs5x.|jD]}|j}|dk r |Sq WdSdS(N(R&R}R$(R!R+tezero((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR} s   cCstS(N(Rk(R!R9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRp scCs5x.|jD]}|j}|dk r |Sq WdSdS(N(R&RVR$(R!R+R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRV s   cCs@t||jdt}x!|jD]}|j||q"WdS(NR (RR RkR&R(R!RRRR+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR) scCs(x!|jD]}|j||q WdS(N(R&R7(R!R:R;R+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR72 scCs(x!|jD]}|j||q WdS(N(R&R(R!RRR+((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR6 scCs\tg|jD]}|j|||^q \}}|jj|||}||jfS(N(tzipR&RR R R(R!RRRR+RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR: s 1(RRRgR#RkRRR}RpRVRR7RR(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s    RcBsteZdZd dZeZeZedZ dZ dZ dZ dZ dZdZd ZRS( sColumn/expression based entity.csf||_||_t|tjrBtj|}|j|_nKt|t j t j frx|j |_|j}nt|dd|_t|tj rt|drx[|jD])}||krPnt||d|qWdSn t|tr t||dSt|tjs8tjd|fn|j|_}|jr`d|_ntjfd|_|j rt|dt r|j |j}n|j!j"|||_#t$|_%t$|j&|_'tj(fdt)j*|iD|_+|j+r;t,|j+d |_-n'|jdk rY|j|_-n d|_-dS( NRt_select_iterableR s<SQL expression, column, or mapped entity expected - got '%r'cSs|S(N((R{((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR l scsS(N((R{(tcounter(sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR o st is_literalc3s=|]3}d|jkrj|jr|jdVqdS(R\N(R^t intersectiont _from_objects(RRp(t actual_froms(sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pys si(.RR RIRR/RRRRRRHRRFRt_query_clause_elementRuR$Rt ColumnElementRBRRRRRERRDthashableRRRRkRR&RGRRRRRt OrderedSetRtiterateR"RR}(R!RRR Rttype_((RRsZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR#H sX           cCs8|jdk r|jS|jr0t|jdSdSdS(Ni(R}R$RR(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRV s  cCsCt||j|j}|j|_|j|_|j|_dS(N(Rtcorresponding_columnRRR}R"(R!RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s  cCs5d|jkr|j|_n|jj|jdS(NR5(RR5Rtadd(R!R:R;((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR7 scCsP|jdkrtSt|r,||jkSt|j oK|j|jSdS(N(R}R$RkRRe(R!R9((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRp s   cCs|j|ttS(N(ReRkRg(R!RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyt#_resolve_expr_against_query_aliases scsP|j||j||jr4|jjnfd}||jfS(Ncs|S(N((RR(R(sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s(RRR?RR(R!RRRR((RsZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s  cCsD|j||j|}|jt|j7_|jj|dS(N(RRRRLRRG(R!RRR((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR scCs t|jS(N(RER(R!((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR sN(RRRR$R#RkRRRRVRR7RpRRRR(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRE s M    cBs)eZeZdZdZdZdZRS(cCs3|jdk rbt|jtjrS|jj rS|jj rS|jj|_q|j|_n-d|_|j |_ |j |_ |j |_||_|j|_|j|_|j|_|j|_|j|_g|_g|_g|_i|_g|_td|jD|_ |j!j"|_#dS(Ncss|]}|jr|VqdS(N(tpropagate_to_loaders(RRi((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pys s($RR$RIRRJt_textualRt apply_labelsRRMRRRRRRRRRRtinvoke_all_eagersRRRRRRRRRRRtpropagate_optionsRR-R(R!R((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR# s.                 N(( RRRkRR$R?Rt for_updateR#(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR s t AliasOptioncBseZdZdZRS(cCs ||_dS(s!Return a :class:`.MapperOption` that will indicate to the :class:`.Query` that the main table has been aliased. This is a seldom-used option to suit the very rare case that :func:`.contains_eager` is being used in conjunction with a user-defined SELECT statement that aliases the parent table. E.g.:: # define an aliased UNION called 'ulist' ulist = users.select(users.c.user_id==7).\ union(users.select(users.c.user_id>7)).\ alias('ulist') # add on an eager load of "addresses" statement = ulist.outerjoin(addresses).\ select().apply_labels() # create query, indicating "ulist" will be an # alias for the main table, "addresses" # property should be eager loaded query = session.query(User).options( contains_alias(ulist), contains_eager(User.addresses)) # then get results via the statement results = query.from_statement(statement).all() :param alias: is the string name of an alias, or a :class:`~.sql.expression.Alias` object representing the alias. N(RK(R!RK((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR# s!cCsRt|jtjr3|jjj|j}n |j}tj||_dS(N( RIRKRR/R~R1R3R4RQ(R!RRK((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyRs (RRR#R(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pyR% s #N(9Rt itertoolsRtRRRRRRRtbaseRRR R R t path_registryR RR RRRoRRRRRERRtsql.expressionRR3RRtsql.baseRRt__all__trootRt_self_inspectst class_loggerRRtsql.selectableRR!R%RRRRRt MapperOptionR%(((sZ/var/www/send.findwatt.com/datamanager/lib/python2.7/site-packages/sqlalchemy/orm/query.pytsH.((.  u oJ%