festival.edmaven.com:80

Linux b747.shapiroconsult.com 3.10.0-1160.119.1.vz7.224.4 #1 SMP Mon Sep 30 15:36:27 MSK 2024 x86_64
Apache
173.231.212.80

File Name : query.py

# orm/query.py
# Copyright (C) 2005-2021 the SQLAlchemy authors and contributors
# <see AUTHORS file>
#
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php

"""The Query class and support.

Defines the :class:`_query.Query` class, the central
construct used by the ORM to construct database queries.

The :class:`_query.Query` class should not be confused with the
:class:`_expression.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.

"""
from itertools import chain

from . import attributes
from . import exc as orm_exc
from . import interfaces
from . import loading
from . import persistence
from . import properties
from .base import _entity_descriptor
from .base import _generative
from .base import _is_aliased_class
from .base import _is_mapped_class
from .base import _orm_columns
from .base import InspectionAttr
from .path_registry import PathRegistry
from .util import _entity_corresponds_to
from .util import aliased
from .util import AliasedClass
from .util import join as orm_join
from .util import object_mapper
from .util import ORMAdapter
from .util import with_parent
from .. import exc as sa_exc
from .. import inspect
from .. import inspection
from .. import log
from .. import sql
from .. import util
from ..sql import expression
from ..sql import util as sql_util
from ..sql import visitors
from ..sql.base import ColumnCollection
from ..sql.expression import _interpret_as_from
from ..sql.selectable import ForUpdateArg

__all__ = ["Query", "QueryContext", "aliased"]

_path_registry = PathRegistry.root

@inspection._self_inspects
@log.class_logger
class Query(object):
    """ORM-level SQL construction object.

:class:`_query.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.Query` object, a copy of the former with additional
    criteria and options associated with it.

:class:`_query.Query` objects are normally initially generated using the
    :meth:`~.Session.query` method of :class:`.Session`, and in
    less common cases by instantiating the :class:`_query.Query` directly and
    associating with a :class:`.Session` using the
    :meth:`_query.Query.with_session`
    method.

For a full walkthrough of :class:`_query.Query` usage, see the
    :ref:`ormtutorial_toplevel`.

"""

_only_return_tuples = False
    _enable_eagerloads = True
    _enable_assertions = True
    _with_labels = False
    _criterion = None
    _yield_per = None
    _order_by = False
    _group_by = False
    _having = None
    _distinct = False
    _prefixes = None
    _suffixes = None
    _offset = None
    _limit = None
    _for_update_arg = None
    _statement = None
    _correlate = frozenset()
    _populate_existing = False
    _invoke_all_eagers = True
    _version_check = False
    _autoflush = True
    _only_load_props = None
    _refresh_state = None
    _refresh_identity_token = None
    _from_obj = ()
    _join_entities = ()
    _select_from_entity = None
    _mapper_adapter_map = {}
    _filter_aliases = ()
    _from_obj_alias = None
    _joinpath = _joinpoint = util.immutabledict()
    _execution_options = util.immutabledict()
    _params = util.immutabledict()
    _attributes = util.immutabledict()
    _with_options = ()
    _with_hints = ()
    _enable_single_crit = True
    _orm_only_adapt = True
    _orm_only_from_obj_alias = True
    _current_path = _path_registry
    _has_mapper_entities = False
    _bake_ok = True

lazy_loaded_from = None
    """An :class:`.InstanceState` that is using this :class:`_query.Query`
    for a lazy load operation.

The primary rationale for this attribute is to support the horizontal
    sharding extension, where it is available within specific query
    execution time hooks created by this extension.   To that end, the
    attribute is only intended to be meaningful at **query execution time**,
    and importantly not any time prior to that, including query compilation
    time.

.. note::

Within the realm of regular :class:`_query.Query` usage,
        this attribute is
        set by the lazy loader strategy before the query is invoked.  However
        there is no established hook that is available to reliably intercept
        this value programmatically.  It is set by the lazy loading strategy
        after any  mapper option objects would have been applied, and now that
        the lazy  loading strategy in the ORM makes use of "baked" queries to
        cache SQL  compilation, the :meth:`.QueryEvents.before_compile` hook is
        also not reliable.

Currently, setting the :paramref:`_orm.relationship.bake_queries` to
        ``False`` on the target :func:`_orm.relationship`,
        and then making use of
        the :meth:`.QueryEvents.before_compile` event hook, is the only
        available programmatic path to intercepting this attribute. In future
        releases, there will be new hooks available that allow interception of
        the :class:`_query.Query` before it is executed,
        rather than before it is
        compiled.

.. versionadded:: 1.2.9

"""

def __init__(self, entities, session=None):
        """Construct a :class:`_query.Query` directly.

E.g.::

q = Query([User, Address], session=some_session)

The above is equivalent to::

q = some_session.query(User, Address)

:param entities: a sequence of entities and/or SQL expressions.

:param session: a :class:`.Session` with which the
         :class:`_query.Query`
         will be associated.   Optional; a :class:`_query.Query`
         can be associated
         with a :class:`.Session` generatively via the
         :meth:`_query.Query.with_session` method as well.

.. seealso::

:meth:`.Session.query`

:meth:`_query.Query.with_session`

"""

self.session = session
        self._polymorphic_adapters = {}
        self._set_entities(entities)

def _set_entities(self, entities, entity_wrapper=None):
        if entity_wrapper is None:
            entity_wrapper = _QueryEntity
        self._entities = []
        self._primary_entity = None
        self._has_mapper_entities = False

# 1. don't run util.to_list() or _set_entity_selectables
        #    if no entities were passed - major performance bottleneck
        #    from lazy loader implementation when it seeks to use Query
        #    class for an identity lookup, causes test_orm.py to fail
        #    with thousands of extra function calls, see issue #4228
        #    for why this use had to be added
        # 2. can't use classmethod on Query because session.query_cls
        #    is an arbitrary callable in some user recipes, not
        #    necessarily a class, so we don't have the class available.
        #    see issue #4256
        # 3. can't do "if entities is not None" because we usually get here
        #    from session.query() which takes in *entities.
        # 4. can't do "if entities" because users make use of undocumented
        #    to_list() behavior here and they pass clause expressions that
        #    can't be evaluated as boolean.  See issue #4269.
        if entities != ():
            for ent in util.to_list(entities):
                entity_wrapper(self, ent)

self._set_entity_selectables(self._entities)

def _set_entity_selectables(self, entities):
        self._mapper_adapter_map = d = self._mapper_adapter_map.copy()

for ent in entities:
            for entity in ent.entities:
                if entity not in d:
                    ext_info = inspect(entity)
                    if (
                        not ext_info.is_aliased_class
                        and ext_info.mapper.with_polymorphic
                    ):
                        if (
                            ext_info.mapper.persist_selectable
                            not in self._polymorphic_adapters
                        ):
                            self._mapper_loads_polymorphically_with(
                                ext_info.mapper,
                                sql_util.ColumnAdapter(
                                    ext_info.selectable,
                                    ext_info.mapper._equivalent_columns,
                                ),
                            )
                        aliased_adapter = None
                    elif ext_info.is_aliased_class:
                        aliased_adapter = ext_info._adapter
                    else:
                        aliased_adapter = None

d[entity] = (ext_info, aliased_adapter)
                ent.setup_entity(*d[entity])

def _mapper_loads_polymorphically_with(self, mapper, adapter):
        for m2 in mapper._with_polymorphic_mappers or [mapper]:
            self._polymorphic_adapters[m2] = adapter
            for m in m2.iterate_to_root():
                self._polymorphic_adapters[m.local_table] = adapter

def _set_select_from(self, obj, set_base_alias):
        fa = []
        select_from_alias = None

for from_obj in obj:
            info = inspect(from_obj)
            if hasattr(info, "mapper") and (
                info.is_mapper or info.is_aliased_class
            ):
                self._select_from_entity = info
                if set_base_alias and not info.is_aliased_class:
                    raise sa_exc.ArgumentError(
                        "A selectable (FromClause) instance is "
                        "expected when the base alias is being set."
                    )
                fa.append(info.selectable)
            elif not info.is_selectable:
                raise sa_exc.ArgumentError(
                    "argument is not a mapped class, mapper, "
                    "aliased(), or FromClause instance."
                )
            else:
                if isinstance(from_obj, expression.SelectBase):
                    from_obj = from_obj.alias()
                if set_base_alias:
                    select_from_alias = from_obj
                fa.append(from_obj)

self._from_obj = tuple(fa)

if (
            set_base_alias
            and len(self._from_obj) == 1
            and isinstance(select_from_alias, expression.Alias)
        ):
            equivs = self.__all_equivs()
            self._from_obj_alias = sql_util.ColumnAdapter(
                self._from_obj[0], equivs
            )
        elif (
            set_base_alias
            and len(self._from_obj) == 1
            and hasattr(info, "mapper")
            and info.is_aliased_class
        ):
            self._from_obj_alias = info._adapter

def _reset_polymorphic_adapter(self, mapper):
        for m2 in mapper._with_polymorphic_mappers:
            self._polymorphic_adapters.pop(m2, None)
            for m in m2.iterate_to_root():
                self._polymorphic_adapters.pop(m.local_table, None)

def _adapt_polymorphic_element(self, element):
        if "parententity" in element._annotations:
            search = element._annotations["parententity"]
            alias = self._polymorphic_adapters.get(search, None)
            if alias:
                return alias.adapt_clause(element)

if isinstance(element, expression.FromClause):
            search = element
        elif hasattr(element, "table"):
            search = element.table
        else:
            return None

alias = self._polymorphic_adapters.get(search, None)
        if alias:
            return alias.adapt_clause(element)

def _adapt_col_list(self, cols):
        return [
            self._adapt_clause(
                expression._literal_as_label_reference(o), True, True
            )
            for o in cols
        ]

@_generative()
    def _set_lazyload_from(self, state):
        self.lazy_loaded_from = state

@_generative()
    def _adapt_all_clauses(self):
        self._orm_only_adapt = False

def _adapt_clause(self, clause, as_filter, orm_only):
        """Adapt incoming clauses to transformations which
        have been applied within this query."""

adapters = []
        # do we adapt all expression elements or only those
        # tagged as 'ORM' constructs ?
        if not self._orm_only_adapt:
            orm_only = False

if as_filter and self._filter_aliases:
            for fa in self._filter_aliases:
                adapters.append((orm_only, fa.replace))

if self._from_obj_alias:
            # for the "from obj" alias, apply extra rule to the
            # 'ORM only' check, if this query were generated from a
            # subquery of itself, i.e. _from_selectable(), apply adaption
            # to all SQL constructs.
            adapters.append(
                (
                    orm_only if self._orm_only_from_obj_alias else False,
                    self._from_obj_alias.replace,
                )
            )

if self._polymorphic_adapters:
            adapters.append((orm_only, self._adapt_polymorphic_element))

if not adapters:
            return clause

def replace(elem):
            is_orm_adapt = (
                "_orm_adapt" in elem._annotations
                or "parententity" in elem._annotations
            )
            for _orm_only, adapter in adapters:
                if not _orm_only or is_orm_adapt:
                    e = adapter(elem)
                    if e is not None:
                        return e

return visitors.replacement_traverse(clause, {}, replace)

def _query_entity_zero(self):
        """Return the first QueryEntity."""
        return self._entities[0]

def _mapper_zero(self):
        """Return the Mapper associated with the first QueryEntity."""
        return self._entities[0].mapper

def _entity_zero(self):
        """Return the 'entity' (mapper or AliasedClass) associated
        with the first QueryEntity, or alternatively the 'select from'
        entity if specified."""

return (
            self._select_from_entity
            if self._select_from_entity is not None
            else self._query_entity_zero().entity_zero
        )

@property
    def _mapper_entities(self):
        for ent in self._entities:
            if isinstance(ent, _MapperEntity):
                yield ent

def _joinpoint_zero(self):
        return self._joinpoint.get("_joinpoint_entity", self._entity_zero())

def _bind_mapper(self):
        ezero = self._entity_zero()
        if ezero is not None:
            insp = inspect(ezero)
            if not insp.is_clause_element:
                return insp.mapper

return None

def _only_full_mapper_zero(self, methname):
        if self._entities != [self._primary_entity]:
            raise sa_exc.InvalidRequestError(
                "%s() can only be used against "
                "a single mapped class." % methname
            )
        return self._primary_entity.entity_zero

def _only_entity_zero(self, rationale=None):
        if len(self._entities) > 1:
            raise sa_exc.InvalidRequestError(
                rationale
                or "This operation requires a Query "
                "against a single mapper."
            )
        return self._entity_zero()

def __all_equivs(self):
        equivs = {}
        for ent in self._mapper_entities:
            equivs.update(ent.mapper._equivalent_columns)
        return equivs

def _get_condition(self):
        return self._no_criterion_condition(
            "get", order_by=False, distinct=False
        )

def _get_existing_condition(self):
        self._no_criterion_assertion("get", order_by=False, distinct=False)

def _no_criterion_assertion(self, meth, order_by=True, distinct=True):
        if not self._enable_assertions:
            return
        if (
            self._criterion is not None
            or self._statement is not None
            or self._from_obj
            or self._limit is not None
            or self._offset is not None
            or self._group_by
            or (order_by and self._order_by)
            or (distinct and self._distinct)
        ):
            raise sa_exc.InvalidRequestError(
                "Query.%s() being called on a "
                "Query with existing criterion. " % meth
            )

def _no_criterion_condition(self, meth, order_by=True, distinct=True):
        self._no_criterion_assertion(meth, order_by, distinct)

self._from_obj = ()
        self._statement = self._criterion = None
        self._order_by = self._group_by = self._distinct = False

def _no_clauseelement_condition(self, meth):
        if not self._enable_assertions:
            return
        if self._order_by:
            raise sa_exc.InvalidRequestError(
                "Query.%s() being called on a "
                "Query with existing criterion. " % meth
            )
        self._no_criterion_condition(meth)

def _no_statement_condition(self, meth):
        if not self._enable_assertions:
            return
        if self._statement is not None:
            raise sa_exc.InvalidRequestError(
                (
                    "Query.%s() being called on a Query with an existing full "
                    "statement - can't apply criterion."
                )
                % meth
            )

def _no_limit_offset(self, meth):
        if not self._enable_assertions:
            return
        if self._limit is not None or self._offset is not None:
            raise sa_exc.InvalidRequestError(
                "Query.%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." % (meth, meth)
            )

def _get_options(
        self,
        populate_existing=None,
        version_check=None,
        only_load_props=None,
        refresh_state=None,
        identity_token=None,
    ):
        if populate_existing:
            self._populate_existing = populate_existing
        if version_check:
            self._version_check = version_check
        if refresh_state:
            self._refresh_state = refresh_state
        if only_load_props:
            self._only_load_props = set(only_load_props)
        if identity_token:
            self._refresh_identity_token = identity_token
        return self

def _clone(self):
        cls = self.__class__
        q = cls.__new__(cls)
        q.__dict__ = self.__dict__.copy()
        return q

@property
    def statement(self):
        """The 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.

"""

stmt = self._compile_context(labels=self._with_labels).statement
        if self._params:
            stmt = stmt.params(self._params)

return stmt

def subquery(self, name=None, with_labels=False, reduce_columns=False):
        """Return the full SELECT statement represented by
        this :class:`_query.Query`, embedded within an
        :class:`_expression.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:`_expression.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.Query` first to apply table-qualified labels
         to all columns.

:param reduce_columns: if True,
         :meth:`_expression.Select.reduce_columns` will
         be called on the resulting :func:`_expression.select` construct,
         to remove same-named columns where one also refers to the other
         via foreign key or WHERE clause equivalence.

"""
        q = self.enable_eagerloads(False)
        if with_labels:
            q = q.with_labels()
        q = q.statement

if reduce_columns:
            q = q.reduce_columns()
        return q.alias(name=name)

def cte(self, name=None, recursive=False):
        r"""Return the full SELECT statement represented by this
        :class:`_query.Query` represented as a common table expression (CTE).

Parameters and usage are the same as those of the
        :meth:`_expression.SelectBase.cte` method; see that method for
        further details.

Here is the `PostgreSQL WITH
        RECURSIVE example
        <http://www.postgresql.org/docs/8.4/static/queries-with.html>`_.
        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:`_expression.HasCTE.cte`

"""
        return self.enable_eagerloads(False).statement.cte(
            name=name, recursive=recursive
        )

def label(self, name):
        """Return the full SELECT statement represented by this
        :class:`_query.Query`, converted
        to a scalar subquery with a label of the given name.

Analogous to :meth:`_expression.SelectBase.label`.

"""

return self.enable_eagerloads(False).statement.label(name)

def as_scalar(self):
        """Return the full SELECT statement represented by this
        :class:`_query.Query`, converted to a scalar subquery.

Analogous to :meth:`_expression.SelectBase.as_scalar`.

"""

return self.enable_eagerloads(False).statement.as_scalar()

@property
    def selectable(self):
        """Return the :class:`_expression.Select` object emitted by this
        :class:`_query.Query`.

Used for :func:`_sa.inspect` compatibility, this is equivalent to::

query.enable_eagerloads(False).with_labels().statement

"""
        return self.__clause_element__()

def __clause_element__(self):
        return self.enable_eagerloads(False).with_labels().statement

@_generative()
    def only_return_tuples(self, value):
        """When set to True, the query results will always be a tuple.

This is specifically for single element queries. The default is False.

.. versionadded:: 1.2.5

.. seealso::

:meth:`_query.Query.is_single_entity`

"""
        self._only_return_tuples = value

@property
    def is_single_entity(self):
        """Indicates if this :class:`_query.Query`
        returns tuples or single entities.

Returns True if this query returns a single entity for each instance
        in its result list, and False if this query returns a tuple of entities
        for each result.

.. versionadded:: 1.3.11

.. seealso::

:meth:`_query.Query.only_return_tuples`

"""
        return (
            not self._only_return_tuples
            and len(self._entities) == 1
            and self._entities[0].supports_single_entity
        )

@_generative()
    def enable_eagerloads(self, value):
        """Control 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, or when using :meth:`_query.Query.yield_per`.

"""
        self._enable_eagerloads = value

def _no_yield_per(self, message):
        raise sa_exc.InvalidRequestError(
            "The yield_per Query option is currently not "
            "compatible with %s eager loading.  Please "
            "specify lazyload('*') or query.enable_eagerloads(False) in "
            "order to "
            "proceed with query.yield_per()." % message
        )

@_generative()
    def with_labels(self):
        """Apply 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 <tablename>_<columnname>; 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.

.. note:: The :meth:`_query.Query.with_labels` method *only* applies
           the output of :attr:`_query.Query.statement`, and *not* to any of
           the result-row invoking systems of :class:`_query.Query` itself,
           e.g. :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc.
           To execute
           a query using :meth:`_query.Query.with_labels`, invoke the
           :attr:`_query.Query.statement` using :meth:`.Session.execute`::

result = session.execute(query.with_labels().statement)

"""
        self._with_labels = True

@_generative()
    def enable_assertions(self, value):
        """Control 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.

"""
        self._enable_assertions = value

@property
    def whereclause(self):
        """A 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.

"""
        return self._criterion

@_generative()
    def _with_current_path(self, path):
        """Indicate 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.

"""
        self._current_path = path

@_generative(_no_clauseelement_condition)
    def with_polymorphic(
        self, cls_or_mappers, selectable=None, polymorphic_on=None
    ):
        """Load columns for inheriting classes.

:meth:`_query.Query.with_polymorphic` applies transformations
        to the "main" mapped class represented by this :class:`_query.Query`.
        The "main" mapped class here means the :class:`_query.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.

"""

if not self._primary_entity:
            raise sa_exc.InvalidRequestError(
                "No primary mapper set up for this Query."
            )
        entity = self._entities[0]._clone()
        self._entities = [entity] + self._entities[1:]
        entity.set_with_polymorphic(
            self,
            cls_or_mappers,
            selectable=selectable,
            polymorphic_on=polymorphic_on,
        )

@_generative()
    def yield_per(self, count):
        r"""Yield 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:`_query.Query.yield_per` method **is not compatible
        subqueryload eager loading or joinedload eager loading when
        using collections**.  It is potentially compatible with "select in"
        eager loading, **provided the database driver supports multiple,
        independent cursors** (pysqlite and psycopg2 are known to work,
        MySQL and SQL Server ODBC drivers do not).

Therefore in some cases, it may be helpful to disable
        eager loads, either unconditionally with
        :meth:`_query.Query.enable_eagerloads`::

q = sess.query(Object).yield_per(100).enable_eagerloads(False)

Or more selectively using :func:`.lazyload`; such as with
        an asterisk to specify the default loader scheme::

q = sess.query(Object).yield_per(100).\
                options(lazyload('*'), joinedload(Object.some_related))

.. 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`,
            :mod:`~sqlalchemy.dialects.mysql.mysqldb` and
            :mod:`~sqlalchemy.dialects.mysql.pymysql` dialects
            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.

.. seealso::

:meth:`_query.Query.enable_eagerloads`

"""
        self._yield_per = count
        self._execution_options = self._execution_options.union(
            {"stream_results": True, "max_row_buffer": count}
        )

def get(self, ident):
        """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))

some_object = session.query(VersionedFoo).get(
                {"id": 5, "version_id": 10})

:meth:`_query.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.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.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.Query` must be constructed in this way,
        i.e. against a single mapped entity,
        with no additional filtering criterion.  Loading
        options via :meth:`_query.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:`_orm.relationship`, using a simple
        foreign-key-to-primary-key criterion, will also use an
        operation equivalent to :meth:`_query.Query.get` in order to retrieve
        the target value from the local identity map
        before querying the database.  See :doc:`/orm/loading_relationships`
        for further details on relationship loading.

:param ident: A scalar, tuple, or dictionary representing the
         primary key.  For a composite (e.g. multiple column) primary key,
         a tuple or dictionary should be passed.

For a single-column primary key, the scalar calling form is typically
         the most expedient.  If the primary key of a row is the value "5",
         the call looks like::

my_object = query.get(5)

The tuple form contains primary key values typically in
         the order in which they correspond to the mapped
         :class:`_schema.Table`
         object's primary key columns, or if the
         :paramref:`_orm.Mapper.primary_key` configuration parameter were
         used, in
         the order used for that parameter. For example, if the primary key
         of a row is represented by the integer
         digits "5, 10" the call would look like::

my_object = query.get((5, 10))

The dictionary form should include as keys the mapped attribute names
         corresponding to each element of the primary key.  If the mapped class
         has the attributes ``id``, ``version_id`` as the attributes which
         store the object's primary key value, the call would look like::

my_object = query.get({"id": 5, "version_id": 10})

.. versionadded:: 1.3 the :meth:`_query.Query.get`
            method now optionally
            accepts a dictionary of attribute names to values in order to
            indicate a primary key identifier.

:return: The object instance, or ``None``.

"""
        return self._get_impl(ident, loading.load_on_pk_identity)

def _identity_lookup(
        self,
        mapper,
        primary_key_identity,
        identity_token=None,
        passive=attributes.PASSIVE_OFF,
        lazy_loaded_from=None,
    ):
        """Locate an object in the identity map.

Given a primary key identity, constructs an identity key and then
        looks in the session's identity map.  If present, the object may
        be run through unexpiration rules (e.g. load unloaded attributes,
        check if was deleted).

For performance reasons, while the :class:`_query.Query` must be
        instantiated, it may be instantiated with no entities, and the
        mapper is passed::

obj = session.query()._identity_lookup(inspect(SomeClass), (1, ))

:param mapper: mapper in use
        :param primary_key_identity: the primary key we are searching for, as
         a tuple.
        :param identity_token: identity token that should be used to create
         the identity key.  Used as is, however overriding subclasses can
         repurpose this in order to interpret the value in a special way,
         such as if None then look among multiple target tokens.
        :param passive: passive load flag passed to
         :func:`.loading.get_from_identity`, which impacts the behavior if
         the object is found; the object may be validated and/or unexpired
         if the flag allows for SQL to be emitted.
        :param lazy_loaded_from: an :class:`.InstanceState` that is
         specifically asking for this identity as a related identity.  Used
         for sharding schemes where there is a correspondence between an object
         and a related object being lazy-loaded (or otherwise
         relationship-loaded).

.. versionadded:: 1.2.9

:return: None if the object is not found in the identity map, *or*
         if the object was unexpired and found to have been deleted.
         if passive flags disallow SQL and the object is expired, returns
         PASSIVE_NO_RESULT.   In all other cases the instance is returned.

.. versionadded:: 1.2.7

"""

key = mapper.identity_key_from_primary_key(
            primary_key_identity, identity_token=identity_token
        )
        return loading.get_from_identity(self.session, mapper, key, passive)

def _get_impl(self, primary_key_identity, db_load_fn, identity_token=None):
        # convert composite types to individual args
        if hasattr(primary_key_identity, "__composite_values__"):
            primary_key_identity = primary_key_identity.__composite_values__()

mapper = self._only_full_mapper_zero("get")

is_dict = isinstance(primary_key_identity, dict)
        if not is_dict:
            primary_key_identity = util.to_list(
                primary_key_identity, default=(None,)
            )

if len(primary_key_identity) != len(mapper.primary_key):
            raise sa_exc.InvalidRequestError(
                "Incorrect number of values in identifier to formulate "
                "primary key for query.get(); primary key columns are %s"
                % ",".join("'%s'" % c for c in mapper.primary_key)
            )

if is_dict:
            try:
                primary_key_identity = list(
                    primary_key_identity[prop.key]
                    for prop in mapper._identity_key_props
                )

except KeyError as err:
                util.raise_(
                    sa_exc.InvalidRequestError(
                        "Incorrect names of values in identifier to formulate "
                        "primary key for query.get(); primary key attribute "
                        "names are %s"
                        % ",".join(
                            "'%s'" % prop.key
                            for prop in mapper._identity_key_props
                        )
                    ),
                    replace_context=err,
                )

if (
            not self._populate_existing
            and not mapper.always_refresh
            and self._for_update_arg is None
        ):

instance = self._identity_lookup(
                mapper, primary_key_identity, identity_token=identity_token
            )

if instance is not None:
                self._get_existing_condition()
                # reject calls for id in identity map but class
                # mismatch.
                if not issubclass(instance.__class__, mapper.class_):
                    return None
                return instance
            elif instance is attributes.PASSIVE_CLASS_MISMATCH:
                return None

return db_load_fn(self, primary_key_identity)

@_generative()
    def correlate(self, *args):
        """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:`_expression.Select.correlate`
        after coercion to expression constructs.

The correlation arguments take effect in such cases
        as when :meth:`_query.Query.from_self` is used, or when
        a subquery as returned by :meth:`_query.Query.subquery` is
        embedded in another :func:`_expression.select` construct.

"""

for s in args:
            if s is None:
                self._correlate = self._correlate.union([None])
            else:
                self._correlate = self._correlate.union(
                    sql_util.surface_selectables(_interpret_as_from(s))
                )

@_generative()
    def autoflush(self, setting):
        """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.

"""
        self._autoflush = setting

@_generative()
    def populate_existing(self):
        """Return a :class:`_query.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.

.. seealso::

:ref:`session_expire` - in the ORM :class:`_orm.Session`
            documentation

"""
        self._populate_existing = True

@_generative()
    def _with_invoke_all_eagers(self, value):
        """Set 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.Query._invoke_all_eagers`.

"""
        self._invoke_all_eagers = value

def with_parent(self, instance, property=None, from_entity=None):  # noqa
        """Add filtering criterion that relates the given instance
        to a child object or collection, using its attribute state
        as well as an established :func:`_orm.relationship()`
        configuration.

The method uses the :func:`.with_parent` function to generate
        the clause, the result of which is passed to
        :meth:`_query.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.Query` object's target mapper.

:param instance:
          An instance which has some :func:`_orm.relationship`.

:param property:
          String property name, or class-bound attribute, which indicates
          what relationship from the instance should be used to reconcile the
          parent/child relationship.

:param from_entity:
          Entity in which to consider as the left side.  This defaults to the
          "zero" entity of the :class:`_query.Query` itself.

"""

if from_entity:
            entity_zero = inspect(from_entity)
        else:
            entity_zero = self._entity_zero()
        if property is None:

mapper = object_mapper(instance)

for prop in mapper.iterate_properties:
                if (
                    isinstance(prop, properties.RelationshipProperty)
                    and prop.mapper is entity_zero.mapper
                ):
                    property = prop  # noqa
                    break
            else:
                raise sa_exc.InvalidRequestError(
                    "Could not locate a property which relates instances "
                    "of class '%s' to instances of class '%s'"
                    % (
                        entity_zero.mapper.class_.__name__,
                        instance.__class__.__name__,
                    )
                )

return self.filter(with_parent(instance, property, entity_zero.entity))

@_generative()
    def add_entity(self, entity, alias=None):
        """add a mapped entity to the list of result columns
        to be returned."""

if alias is not None:
            entity = aliased(entity, alias)

self._entities = list(self._entities)
        m = _MapperEntity(self, entity)
        self._set_entity_selectables([m])

@_generative()
    def with_session(self, session):
        """Return a :class:`_query.Query` that will use the given
        :class:`.Session`.

While the :class:`_query.Query`
        object is normally instantiated using the
        :meth:`.Session.query` method, it is legal to build the
        :class:`_query.Query`
        directly without necessarily using a :class:`.Session`.  Such a
        :class:`_query.Query` object, or any :class:`_query.Query`
        already associated
        with a different :class:`.Session`, can produce a new
        :class:`_query.Query`
        object associated with a target session using this method::

from sqlalchemy.orm import Query

query = Query([MyClass]).filter(MyClass.id == 5)

result = query.with_session(my_session).one()

"""

self.session = session

def from_self(self, *entities):
        r"""return a Query that selects from this Query's
        SELECT statement.

:meth:`_query.Query.from_self` essentially turns the SELECT statement
        into a SELECT of itself.  Given a query such as::

q = session.query(User).filter(User.name.like('e%'))

Given the :meth:`_query.Query.from_self` version::

q = session.query(User).filter(User.name.like('e%')).from_self()

This query renders as:

.. sourcecode:: sql

There are lots of cases where :meth:`_query.Query.from_self`
        may be useful.
        A simple one is where above, we may want to apply a row LIMIT to
        the set of user objects we query against, and then apply additional
        joins against that row-limited set::

q = session.query(User).filter(User.name.like('e%')).\
                limit(5).from_self().\
                join(User.addresses).filter(Address.email.like('q%'))

The above query joins to the ``Address`` entity but only against the
        first five results of the ``User`` query:

.. sourcecode:: sql

SELECT anon_1.user_id AS anon_1_user_id,
                   anon_1.user_name AS anon_1_user_name
            FROM (SELECT "user".id AS user_id, "user".name AS user_name
            FROM "user"
            WHERE "user".name LIKE :name_1
             LIMIT :param_1) AS anon_1
            JOIN address ON anon_1.user_id = address.user_id
            WHERE address.email LIKE :email_1

**Automatic Aliasing**

Another key behavior of :meth:`_query.Query.from_self`
        is that it applies
        **automatic aliasing** to the entities inside the subquery, when
        they are referenced on the outside.  Above, if we continue to
        refer to the ``User`` entity without any additional aliasing applied
        to it, those references wil be in terms of the subquery::

q = session.query(User).filter(User.name.like('e%')).\
                limit(5).from_self().\
                join(User.addresses).filter(Address.email.like('q%')).\
                order_by(User.name)

The ORDER BY against ``User.name`` is aliased to be in terms of the
        inner subquery:

.. sourcecode:: sql

The automatic aliasing feature only works in a **limited** way,
        for simple filters and orderings.   More ambitious constructions
        such as referring to the entity in joins should prefer to use
        explicit subquery objects, typically making use of the
        :meth:`_query.Query.subquery`
        method to produce an explicit subquery object.
        Always test the structure of queries by viewing the SQL to ensure
        a particular structure does what's expected!

**Changing the Entities**

:meth:`_query.Query.from_self`
        also includes the ability to modify what
        columns are being queried.   In our example, we want ``User.id``
        to be queried by the inner query, so that we can join to the
        ``Address`` entity on the outside, but we only wanted the outer
        query to return the ``Address.email`` column::

q = session.query(User).filter(User.name.like('e%')).\
                limit(5).from_self(Address.email).\
                join(User.addresses).filter(Address.email.like('q%'))

yielding:

.. sourcecode:: sql

SELECT address.email AS address_email
            FROM (SELECT "user".id AS user_id, "user".name AS user_name
            FROM "user"
            WHERE "user".name LIKE :name_1
             LIMIT :param_1) AS anon_1
            JOIN address ON anon_1.user_id = address.user_id
            WHERE address.email LIKE :email_1

**Looking out for Inner / Outer Columns**

Keep in mind that when referring to columns that originate from
        inside the subquery, we need to ensure they are present in the
        columns clause of the subquery itself; this is an ordinary aspect of
        SQL.  For example, if we wanted to load from a joined entity inside
        the subquery using :func:`.contains_eager`, we need to add those
        columns.   Below illustrates a join of ``Address`` to ``User``,
        then a subquery, and then we'd like :func:`.contains_eager` to access
        the ``User`` columns::

q = session.query(Address).join(Address.user).\
                filter(User.name.like('e%'))

q = q.add_entity(User).from_self().\
                options(contains_eager(Address.user))

We use :meth:`_query.Query.add_entity` above **before** we call
        :meth:`_query.Query.from_self`
        so that the ``User`` columns are present
        in the inner subquery, so that they are available to the
        :func:`.contains_eager` modifier we are using on the outside,
        producing:

.. sourcecode:: sql

SELECT anon_1.address_id AS anon_1_address_id,
                   anon_1.address_email AS anon_1_address_email,
                   anon_1.address_user_id AS anon_1_address_user_id,
                   anon_1.user_id AS anon_1_user_id,
                   anon_1.user_name AS anon_1_user_name
            FROM (
                SELECT address.id AS address_id,
                address.email AS address_email,
                address.user_id AS address_user_id,
                "user".id AS user_id,
                "user".name AS user_name
            FROM address JOIN "user" ON "user".id = address.user_id
            WHERE "user".name LIKE :name_1) AS anon_1

If we didn't call ``add_entity(User)``, but still asked
        :func:`.contains_eager` to load the ``User`` entity, it would be
        forced to add the table on the outside without the correct
        join criteria - note the ``anon1, "user"`` phrase at
        the end:

.. sourcecode:: sql

-- incorrect query
            SELECT anon_1.address_id AS anon_1_address_id,
                   anon_1.address_email AS anon_1_address_email,
                   anon_1.address_user_id AS anon_1_address_user_id,
                   "user".id AS user_id,
                   "user".name AS user_name
            FROM (
                SELECT address.id AS address_id,
                address.email AS address_email,
                address.user_id AS address_user_id
            FROM address JOIN "user" ON "user".id = address.user_id
            WHERE "user".name LIKE :name_1) AS anon_1, "user"

:param \*entities: optional list of entities which will replace
         those being selected.

"""

fromclause = (
            self.with_labels()
            .enable_eagerloads(False)
            .statement.correlate(None)
        )
        q = self._from_selectable(fromclause)
        q._enable_single_crit = False
        q._select_from_entity = self._entity_zero()
        if entities:
            q._set_entities(entities)
        return q

@_generative()
    def _set_enable_single_crit(self, val):
        self._enable_single_crit = val

@_generative()
    def _from_selectable(self, fromclause):
        for attr in (
            "_statement",
            "_criterion",
            "_order_by",
            "_group_by",
            "_limit",
            "_offset",
            "_joinpath",
            "_joinpoint",
            "_distinct",
            "_having",
            "_prefixes",
            "_suffixes",
        ):
            self.__dict__.pop(attr, None)
        self._set_select_from([fromclause], True)

# this enables clause adaptation for non-ORM
        # expressions.
        self._orm_only_from_obj_alias = False

old_entities = self._entities
        self._entities = []
        for e in old_entities:
            e.adapt_to_selectable(self, self._from_obj[0])

def values(self, *columns):
        """Return an iterator yielding result tuples corresponding
        to the given list of columns.

"""

if not columns:
            return iter(())
        q = self._clone()
        q._set_entities(columns, entity_wrapper=_ColumnEntity)
        if not q._yield_per:
            q._yield_per = 10
        return iter(q)

_values = values

def value(self, column):
        """Return a scalar result corresponding to the given
        column expression.

"""
        try:
            return next(self.values(column))[0]
        except StopIteration:
            return None

@_generative()
    def with_entities(self, *entities):
        r"""Return a new :class:`_query.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)

"""
        self._set_entities(entities)

@_generative()
    def add_columns(self, *column):
        """Add one or more column expressions to the list
        of result columns to be returned."""

self._entities = list(self._entities)
        l = len(self._entities)
        for c in column:
            _ColumnEntity(self, c)
        # _ColumnEntity may add many entities if the
        # given arg is a FROM clause
        self._set_entity_selectables(self._entities[l:])

@util.pending_deprecation(
        "0.7",
        ":meth:`.add_column` is superseded " "by :meth:`.add_columns`",
        False,
    )
    def add_column(self, column):
        """Add a column expression to the list of result columns to be
        returned.

Pending deprecation: :meth:`.add_column` will be superseded by
        :meth:`.add_columns`.

"""
        return self.add_columns(column)

def options(self, *args):
        """Return a new :class:`_query.Query` object,
        applying the given list of
        mapper options.

Most supplied options regard changing how column- and
        relationship-mapped attributes are loaded.

.. seealso::

:ref:`deferred_options`

:ref:`relationship_loader_options`

"""

return self._options(False, *args)

def _conditional_options(self, *args):
        return self._options(True, *args)

@_generative()
    def _options(self, conditional, *args):
        # most MapperOptions write to the '_attributes' dictionary,
        # so copy that as well
        self._attributes = self._attributes.copy()
        if "_unbound_load_dedupes" not in self._attributes:
            self._attributes["_unbound_load_dedupes"] = set()
        opts = tuple(util.flatten_iterator(args))
        self._with_options = self._with_options + opts
        if conditional:
            for opt in opts:
                opt.process_query_conditionally(self)
        else:
            for opt in opts:
                opt.process_query(self)

def with_transformation(self, fn):
        """Return a new :class:`_query.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.Query`
        objects.  See the example at :ref:`hybrid_transformers`.

"""
        return fn(self)

@_generative()
    def with_hint(self, selectable, text, dialect_name="*"):
        """Add an indexing or other executional context
        hint for the given entity or selectable to
        this :class:`_query.Query`.

Functionality is passed straight through to
        :meth:`_expression.Select.with_hint`,
        with the addition that ``selectable`` can be a
        :class:`_schema.Table`, :class:`_expression.Alias`,
        or ORM entity / mapped class
        /etc.

.. seealso::

:meth:`_query.Query.with_statement_hint`

:meth:`.Query.prefix_with` - generic SELECT prefixing which also
            can suit some database-specific HINT syntaxes such as MySQL
            optimizer hints

"""

if selectable is not None:
            selectable = inspect(selectable).selectable

self._with_hints += ((selectable, text, dialect_name),)

def with_statement_hint(self, text, dialect_name="*"):
        """Add a statement hint to this :class:`_expression.Select`.

This method is similar to :meth:`_expression.Select.with_hint`
        except that
        it does not require an individual table, and instead applies to the
        statement as a whole.

This feature calls down into
        :meth:`_expression.Select.with_statement_hint`.

.. versionadded:: 1.0.0

.. seealso::

:meth:`_query.Query.with_hint`

"""
        return self.with_hint(None, text, dialect_name)

def get_execution_options(self):
        """Get the non-SQL options which will take effect during execution.

.. versionadded:: 1.3

.. seealso::

:meth:`_query.Query.execution_options`
        """
        return self._execution_options

@_generative()
    def execution_options(self, **kwargs):
        """Set non-SQL options which take effect during execution.

The options are the same as those accepted by
        :meth:`_engine.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.

.. seealso::

:meth:`_query.Query.get_execution_options`

"""
        self._execution_options = self._execution_options.union(kwargs)

@_generative()
    @util.deprecated(
        "0.9",
        "The :meth:`_query.Query.with_lockmode` "
        "method is deprecated and will "
        "be removed in a future release.  Please refer to "
        ":meth:`_query.Query.with_for_update`. ",
    )
    def with_lockmode(self, mode):
        """Return a new :class:`_query.Query`
        object with the specified "locking mode",
        which essentially refers to the ``FOR UPDATE`` clause.

: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.Query.with_for_update` - improved API for
            specifying the ``FOR UPDATE`` clause.

"""
        self._for_update_arg = LockmodeArg.parse_legacy_query(mode)

@_generative()
    def with_for_update(
        self,
        read=False,
        nowait=False,
        of=None,
        skip_locked=False,
        key_share=False,
    ):
        """return a new :class:`_query.Query`
        with the specified options for the
        ``FOR UPDATE`` clause.

The behavior of this method is identical to that of
        :meth:`_expression.GenerativeSelect.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).populate_existing().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.Query.with_for_update`
           supersedes
           the :meth:`_query.Query.with_lockmode` method.

.. note::  It is generally a good idea to combine the use of the
           :meth:`_orm.Query.populate_existing` method when using the
           :meth:`_orm.Query.with_for_update` method.   The purpose of
           :meth:`_orm.Query.populate_existing` is to force all the data read
           from the SELECT to be populated into the ORM objects returned,
           even if these objects are already in the :term:`identity map`.

.. seealso::

:meth:`_expression.GenerativeSelect.with_for_update`
            - Core level method with
            full argument and behavioral description.

:meth:`_orm.Query.populate_existing` - overwrites attributes of
            objects already loaded in the identity map.

"""  # noqa: E501

self._for_update_arg = LockmodeArg(
            read=read,
            nowait=nowait,
            of=of,
            skip_locked=skip_locked,
            key_share=key_share,
        )

@_generative()
    def params(self, *args, **kwargs):
        r"""Add 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.

"""
        if len(args) == 1:
            kwargs.update(args[0])
        elif len(args) > 0:
            raise sa_exc.ArgumentError(
                "params() takes zero or one positional argument, "
                "which is a dictionary."
            )
        self._params = self._params.copy()
        self._params.update(kwargs)

@_generative(_no_statement_condition, _no_limit_offset)
    def filter(self, *criterion):
        r"""Apply the given filtering criterion to a copy
        of this :class:`_query.Query`, using SQL expressions.

e.g.::

session.query(MyClass).filter(MyClass.name == 'some name')

Multiple criteria may be specified as comma separated; the effect
        is that they will be joined together using the :func:`.and_`
        function::

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:`_expression.text`
        construct.

.. seealso::

:meth:`_query.Query.filter_by` - filter on keyword expressions.

"""
        for criterion in list(criterion):
            criterion = expression._expression_literal_as_text(criterion)

criterion = self._adapt_clause(criterion, True, True)

if self._criterion is not None:
                self._criterion = self._criterion & criterion
            else:
                self._criterion = criterion

def filter_by(self, **kwargs):
        r"""Apply the given filtering criterion to a copy
        of this :class:`_query.Query`, using keyword expressions.

e.g.::

session.query(MyClass).filter_by(name = 'some name')

Multiple criteria may be specified as comma separated; the effect
        is that they will be joined together using the :func:`.and_`
        function::

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.Query.join`.

.. seealso::

:meth:`_query.Query.filter` - filter on SQL expressions.

"""

zero = self._joinpoint_zero()
        if zero is None:
            raise sa_exc.InvalidRequestError(
                "Can't use filter_by when the first entity '%s' of a query "
                "is not a mapped class. Please use the filter method instead, "
                "or change the order of the entities in the query"
                % self._query_entity_zero()
            )

clauses = [
            _entity_descriptor(zero, key) == value
            for key, value in kwargs.items()
        ]
        return self.filter(*clauses)

@_generative(_no_statement_condition, _no_limit_offset)
    def order_by(self, *criterion):
        """Apply one or more ORDER BY criterion to the query and return
        the newly resulting :class:`_query.Query`.

All existing ORDER BY settings can be suppressed by
        passing ``None`` - this will suppress any ordering configured
        on the :func:`.mapper` object using the deprecated
        :paramref:`.mapper.order_by` parameter.

"""

if len(criterion) == 1:
            if criterion[0] is False:
                if "_order_by" in self.__dict__:
                    self._order_by = False
                return
            if criterion[0] is None:
                self._order_by = None
                return

criterion = self._adapt_col_list(criterion)

if self._order_by is False or self._order_by is None:
            self._order_by = criterion
        else:
            self._order_by = self._order_by + criterion

@_generative(_no_statement_condition, _no_limit_offset)
    def group_by(self, *criterion):
        """Apply one or more GROUP BY criterion to the query and return
        the newly resulting :class:`_query.Query`.

All existing GROUP BY settings can be suppressed by
        passing ``None`` - this will suppress any GROUP BY configured
        on mappers as well.

.. versionadded:: 1.1 GROUP BY can be cancelled by passing
           ``None``, in the same way as ORDER BY.

"""

if len(criterion) == 1:
            if criterion[0] is None:
                self._group_by = False
                return

criterion = list(chain(*[_orm_columns(c) for c in criterion]))
        criterion = self._adapt_col_list(criterion)

if self._group_by is False:
            self._group_by = criterion
        else:
            self._group_by = self._group_by + criterion

@_generative(_no_statement_condition, _no_limit_offset)
    def having(self, criterion):
        r"""Apply a HAVING criterion to the query and return the
        newly resulting :class:`_query.Query`.

:meth:`_query.Query.having` is used in conjunction with
        :meth:`_query.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)

"""

criterion = expression._expression_literal_as_text(criterion)

if criterion is not None and not isinstance(
            criterion, sql.ClauseElement
        ):
            raise sa_exc.ArgumentError(
                "having() argument must be of type "
                "sqlalchemy.sql.ClauseElement or string"
            )

criterion = self._adapt_clause(criterion, True, True)

if self._having is not None:
            self._having = self._having & criterion
        else:
            self._having = criterion

def _set_op(self, expr_fn, *q):
        return self._from_selectable(
            expr_fn(*([self] + list(q)))
        )._set_enable_single_crit(False)

def union(self, *q):
        """Produce 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.Query` object will not render ORDER BY within
        its SELECT statement.

"""
        return self._set_op(expression.union, *q)

def union_all(self, *q):
        """Produce a UNION ALL of this Query against one or more queries.