/skink/lib/sqlalchemy/orm/query.py
Python | 2229 lines | 2041 code | 84 blank | 104 comment | 117 complexity | 64a55e88461865cebd7b7979695f18be MD5 | raw file
Large files files are truncated, but you can click here to view the full file
- # orm/query.py
- # Copyright (C) 2005, 2006, 2007, 2008, 2009 Michael Bayer mike_mp@zzzcomputing.com
- #
- # 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:`~sqlalchemy.orm.query.Query` class, the central construct used by
- the ORM to construct database queries.
- The ``Query`` class should not be confused with the
- :class:`~sqlalchemy.sql.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 operator import itemgetter
- from sqlalchemy import sql, util, log, schema
- from sqlalchemy import exc as sa_exc
- from sqlalchemy.orm import exc as orm_exc
- from sqlalchemy.sql import util as sql_util
- from sqlalchemy.sql import expression, visitors, operators
- from sqlalchemy.orm import (
- attributes, interfaces, mapper, object_mapper, evaluator,
- )
- from sqlalchemy.orm.util import (
- AliasedClass, ORMAdapter, _entity_descriptor, _entity_info,
- _is_aliased_class, _is_mapped_class, _orm_columns, _orm_selectable,
- join as orm_join,
- )
- __all__ = ['Query', 'QueryContext', 'aliased']
- aliased = AliasedClass
- def _generative(*assertions):
- """Mark a method as generative."""
- @util.decorator
- def generate(fn, *args, **kw):
- self = args[0]._clone()
- for assertion in assertions:
- assertion(self, fn.func_name)
- fn(self, *args[1:], **kw)
- return self
- return generate
- class Query(object):
- """ORM-level SQL construction object."""
-
- _enable_eagerloads = True
- _enable_assertions = True
- _with_labels = False
- _criterion = None
- _yield_per = None
- _lockmode = None
- _order_by = False
- _group_by = False
- _having = None
- _distinct = False
- _offset = None
- _limit = None
- _statement = None
- _joinpoint = None
- _correlate = frozenset()
- _populate_existing = False
- _version_check = False
- _autoflush = True
- _current_path = ()
- _only_load_props = None
- _refresh_state = None
- _from_obj = ()
- _filter_aliases = None
- _from_obj_alias = None
- _currenttables = frozenset()
-
- def __init__(self, entities, session=None):
- self.session = session
- self._with_options = []
- self._params = {}
- self._attributes = {}
- 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 = []
- for ent in util.to_list(entities):
- entity_wrapper(self, ent)
- self._setup_aliasizers(self._entities)
- def _setup_aliasizers(self, entities):
- if hasattr(self, '_mapper_adapter_map'):
- # usually safe to share a single map, but copying to prevent
- # subtle leaks if end-user is reusing base query with arbitrary
- # number of aliased() objects
- self._mapper_adapter_map = d = self._mapper_adapter_map.copy()
- else:
- self._mapper_adapter_map = d = {}
- for ent in entities:
- for entity in ent.entities:
- if entity not in d:
- mapper, selectable, is_aliased_class = _entity_info(entity)
- if not is_aliased_class and mapper.with_polymorphic:
- with_polymorphic = mapper._with_polymorphic_mappers
- self.__mapper_loads_polymorphically_with(mapper,
- sql_util.ColumnAdapter(selectable, mapper._equivalent_columns))
- adapter = None
- elif is_aliased_class:
- adapter = sql_util.ColumnAdapter(selectable, mapper._equivalent_columns)
- with_polymorphic = None
- else:
- with_polymorphic = adapter = None
- d[entity] = (mapper, adapter, selectable, is_aliased_class, with_polymorphic)
- ent.setup_entity(entity, *d[entity])
- def __mapper_loads_polymorphically_with(self, mapper, adapter):
- for m2 in mapper._with_polymorphic_mappers:
- self._polymorphic_adapters[m2] = adapter
- for m in m2.iterate_to_root():
- self._polymorphic_adapters[m.mapped_table] = self._polymorphic_adapters[m.local_table] = adapter
- def _set_select_from(self, from_obj):
- if isinstance(from_obj, expression._SelectBaseMixin):
- from_obj = from_obj.alias()
- self._from_obj = (from_obj,)
- equivs = self.__all_equivs()
- if isinstance(from_obj, expression.Alias):
- self._from_obj_alias = sql_util.ColumnAdapter(from_obj, equivs)
- def _get_polymorphic_adapter(self, entity, selectable):
- self.__mapper_loads_polymorphically_with(entity.mapper,
- sql_util.ColumnAdapter(selectable, entity.mapper._equivalent_columns))
- 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.mapped_table, None)
- self._polymorphic_adapters.pop(m.local_table, None)
- def _reset_joinpoint(self):
- self._joinpoint = None
- self._filter_aliases = None
- def __adapt_polymorphic_element(self, element):
- if isinstance(element, expression.FromClause):
- search = element
- elif hasattr(element, 'table'):
- search = element.table
- else:
- search = None
- if search:
- alias = self._polymorphic_adapters.get(search, None)
- if alias:
- return alias.adapt_clause(element)
- def __replace_element(self, adapters):
- def replace(elem):
- if '_halt_adapt' in elem._annotations:
- return elem
- for adapter in adapters:
- e = adapter(elem)
- if e:
- return e
- return replace
- def __replace_orm_element(self, adapters):
- def replace(elem):
- if '_halt_adapt' in elem._annotations:
- return elem
- if "_orm_adapt" in elem._annotations or "parententity" in elem._annotations:
- for adapter in adapters:
- e = adapter(elem)
- if e:
- return e
- return replace
- @_generative()
- def _adapt_all_clauses(self):
- self._disable_orm_filtering = True
- def _adapt_clause(self, clause, as_filter, orm_only):
- adapters = []
- if as_filter and self._filter_aliases:
- adapters.append(self._filter_aliases.replace)
- if self._from_obj_alias:
- adapters.append(self._from_obj_alias.replace)
- if self._polymorphic_adapters:
- adapters.append(self.__adapt_polymorphic_element)
- if not adapters:
- return clause
- if getattr(self, '_disable_orm_filtering', not orm_only):
- return visitors.replacement_traverse(
- clause,
- {'column_collections':False},
- self.__replace_element(adapters)
- )
- else:
- return visitors.replacement_traverse(
- clause,
- {'column_collections':False},
- self.__replace_orm_element(adapters)
- )
- def _entity_zero(self):
- return self._entities[0]
- def _mapper_zero(self):
- return self._entity_zero().entity_zero
- def _extension_zero(self):
- ent = self._entity_zero()
- return getattr(ent, 'extension', ent.mapper.extension)
- @property
- def _mapper_entities(self):
- # TODO: this is wrong, its hardcoded to "priamry entity" when
- # for the case of __all_equivs() it should not be
- # the name of this accessor is wrong too
- for ent in self._entities:
- if hasattr(ent, 'primary_entity'):
- yield ent
- def _joinpoint_zero(self):
- return self._joinpoint or self._entity_zero().entity_zero
- def _mapper_zero_or_none(self):
- if not getattr(self._entities[0], 'primary_entity', False):
- return None
- return self._entities[0].mapper
- def _only_mapper_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._mapper_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 _generate_mapper_zero(self):
- if not getattr(self._entities[0], 'primary_entity', False):
- raise sa_exc.InvalidRequestError("No primary mapper set up for this Query.")
- entity = self._entities[0]._clone()
- self._entities = [entity] + self._entities[1:]
- return entity
- def __all_equivs(self):
- equivs = {}
- for ent in self._mapper_entities:
- equivs.update(ent.mapper._equivalent_columns)
- return equivs
- def _no_criterion_condition(self, meth):
- if not self._enable_assertions:
- return
- if self._criterion or self._statement or self._from_obj or \
- self._limit is not None or self._offset is not None or \
- self._group_by:
- raise sa_exc.InvalidRequestError("Query.%s() being called on a Query with existing criterion. " % meth)
- 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:
- 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 _no_select_modifiers(self, meth):
- if not self._enable_assertions:
- return
- for attr, methname, notset in (
- ('_limit', 'limit()', None),
- ('_offset', 'offset()', None),
- ('_order_by', 'order_by()', False),
- ('_group_by', 'group_by()', False),
- ('_distinct', 'distinct()', False),
- ):
- if getattr(self, attr) is not notset:
- raise sa_exc.InvalidRequestError(
- "Can't call Query.%s() when %s has been called" % (meth, methname)
- )
- def _get_options(self, populate_existing=None,
- version_check=None,
- only_load_props=None,
- refresh_state=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)
- 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."""
- return self._compile_context(labels=self._with_labels).\
- statement._annotate({'_halt_adapt': True})
- def subquery(self):
- """return the full SELECT statement represented by this Query, embedded within an Alias.
- Eager JOIN generation within the query is disabled.
- """
- return self.enable_eagerloads(False).statement.alias()
- def __clause_element__(self):
- return self.enable_eagerloads(False).statement
- @_generative()
- def enable_eagerloads(self, value):
- """Control whether or not eager joins are rendered.
- When set to False, the returned Query will not render
- eager joins regardless of eagerload() options
- or mapper-level lazy=False configurations.
- This is used primarily when nesting the Query's
- statement into a subquery or other
- selectable.
- """
- self._enable_eagerloads = value
- @_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.
- """
- 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):
- """The WHERE criterion for this Query."""
- 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, discriminator=None):
- """Load columns for descendant mappers of this Query's mapper.
- Using this method will ensure that each descendant mapper's
- tables are included in the FROM clause, and will allow filter()
- criterion to be used against those tables. The resulting
- instances will also have those columns already loaded so that
- no "post fetch" of those columns will be required.
- :param cls_or_mappers: a single class or mapper, or list of class/mappers,
- which inherit from this Query's mapper. Alternatively, it
- may also be the string ``'*'``, in which case all descending
- mappers will be added to the FROM clause.
- :param selectable: a table or select() statement that will
- be used in place of the generated FROM clause. This argument
- is required if any of the desired mappers use concrete table
- inheritance, since SQLAlchemy currently cannot generate UNIONs
- among tables automatically. If used, the ``selectable``
- argument must represent the full set of tables and columns mapped
- by every desired mapper. Otherwise, the unaccounted mapped columns
- will result in their table being appended directly to the FROM
- clause which will usually lead to incorrect results.
- :param discriminator: a column to be used as the "discriminator"
- column for the given selectable. If not given, the polymorphic_on
- attribute of the mapper will be used, if any. This is useful
- for mappers that don't have polymorphic loading behavior by default,
- such as concrete table mappers.
- """
- entity = self._generate_mapper_zero()
- entity.set_with_polymorphic(self, cls_or_mappers, selectable=selectable, discriminator=discriminator)
- @_generative()
- def yield_per(self, count):
- """Yield only ``count`` rows at a time.
- 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=False) since those
- collections will be cleared for a new load when encountered in a
- subsequent result batch.
- """
- self._yield_per = count
- def get(self, ident):
- """Return an instance of the object based on the given identifier, or None if not found.
- The `ident` argument is a scalar or tuple of primary key column values
- in the order of the table def's primary key columns.
- """
- # convert composite types to individual args
- if hasattr(ident, '__composite_values__'):
- ident = ident.__composite_values__()
- key = self._only_mapper_zero(
- "get() can only be used against a single mapped class."
- ).identity_key_from_primary_key(ident)
- return self._get(key, ident)
- @classmethod
- @util.deprecated('Deprecated. Use sqlalchemy.orm.with_parent '
- 'in conjunction with filter().')
- def query_from_parent(cls, instance, property, **kwargs):
- """Return a new Query with criterion corresponding to a parent instance.
- Return a newly constructed Query object, with criterion corresponding
- to a relationship to the given parent instance.
- instance
- a persistent or detached instance which is related to class
- represented by this query.
- property
- string name of the property which relates this query's class to the
- instance.
- \**kwargs
- all extra keyword arguments are propagated to the constructor of
- Query.
- """
- mapper = object_mapper(instance)
- prop = mapper.get_property(property, resolve_synonyms=True)
- target = prop.mapper
- criterion = prop.compare(operators.eq, instance, value_is_parent=True)
- return Query(target, **kwargs).filter(criterion)
- @_generative()
- def correlate(self, *args):
- self._correlate = self._correlate.union(_orm_selectable(s) for s in args)
- @_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 Query that will refresh all instances loaded.
- This includes all entities accessed from the database, including
- secondary entities, eagerly-loaded collection items.
- All changes present on entities which are already present in the
- session will be reset and the entities will all be marked "clean".
- An alternative to populate_existing() is to expire the Session
- fully using session.expire_all().
- """
- self._populate_existing = True
- def with_parent(self, instance, property=None):
- """Add a join criterion corresponding to a relationship to the given
- parent instance.
- instance
- a persistent or detached instance which is related to class
- represented by this query.
- property
- string name of the property which relates this query's class to the
- instance. if None, the method will attempt to find a suitable
- property.
- Currently, this method only works with immediate parent relationships,
- but in the future may be enhanced to work across a chain of parent
- mappers.
- """
- from sqlalchemy.orm import properties
- mapper = object_mapper(instance)
- if property is None:
- for prop in mapper.iterate_properties:
- if isinstance(prop, properties.PropertyLoader) and prop.mapper is self._mapper_zero():
- break
- else:
- raise sa_exc.InvalidRequestError(
- "Could not locate a property which relates instances "
- "of class '%s' to instances of class '%s'" %
- (self._mapper_zero().class_.__name__, instance.__class__.__name__)
- )
- else:
- prop = mapper.get_property(property, resolve_synonyms=True)
- return self.filter(prop.compare(operators.eq, instance, value_is_parent=True))
- @_generative()
- def add_entity(self, entity, alias=None):
- """add a mapped entity to the list of result columns to be returned."""
- if alias:
- entity = aliased(entity, alias)
- self._entities = list(self._entities)
- m = _MapperEntity(self, entity)
- self._setup_aliasizers([m])
- def from_self(self, *entities):
- """return a Query that selects from this Query's SELECT statement.
- \*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)
- if entities:
- q._set_entities(entities)
- return q
- _from_self = from_self
- @_generative()
- def _from_selectable(self, fromclause):
- self._statement = self._criterion = None
- self._order_by = self._group_by = self._distinct = False
- self._limit = self._offset = None
- self._set_select_from(fromclause)
- 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 self.values(column).next()[0]
- except StopIteration:
- return None
- @_generative()
- def add_column(self, column):
- """Add a SQL ColumnElement to the list of result columns to be returned."""
- self._entities = list(self._entities)
- l = len(self._entities)
- _ColumnEntity(self, column)
- # _ColumnEntity may add many entities if the
- # given arg is a FROM clause
- self._setup_aliasizers(self._entities[l:])
- def options(self, *args):
- """Return a new Query object, applying the given list of
- MapperOptions.
- """
- 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()
- opts = [o for o in 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)
- @_generative()
- def with_lockmode(self, mode):
- """Return a new Query object with the specified locking mode."""
- self._lockmode = mode
- @_generative()
- def params(self, *args, **kwargs):
- """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):
- """apply the given filtering criterion to the query and return the newly resulting ``Query``
- the criterion is any sql.ClauseElement applicable to the WHERE clause of a select.
- """
- if isinstance(criterion, basestring):
- criterion = sql.text(criterion)
- if criterion is not None and not isinstance(criterion, sql.ClauseElement):
- raise sa_exc.ArgumentError("filter() argument must be of type sqlalchemy.sql.ClauseElement or string")
- 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):
- """apply the given filtering criterion to the query and return the newly resulting ``Query``."""
- clauses = [_entity_descriptor(self._joinpoint_zero(), key)[0] == value
- for key, value in kwargs.iteritems()]
- return self.filter(sql.and_(*clauses))
- @_generative(_no_statement_condition, _no_limit_offset)
- @util.accepts_a_list_as_starargs(list_deprecation='pending')
- def order_by(self, *criterion):
- """apply one or more ORDER BY criterion to the query and return the newly resulting ``Query``"""
- if len(criterion) == 1 and criterion[0] is None:
- self._order_by = None
- else:
- criterion = [self._adapt_clause(expression._literal_as_text(o), True, True) for o in 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)
- @util.accepts_a_list_as_starargs(list_deprecation='pending')
- def group_by(self, *criterion):
- """apply one or more GROUP BY criterion to the query and return the newly resulting ``Query``"""
- criterion = list(chain(*[_orm_columns(c) for c in criterion]))
- criterion = [self._adapt_clause(expression._literal_as_text(o), True, True) for o in 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):
- """apply a HAVING criterion to the query and return the newly resulting ``Query``."""
- if isinstance(criterion, basestring):
- criterion = sql.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 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)
- """
- return self._from_selectable(
- expression.union(*([self]+ list(q))))
- def union_all(self, *q):
- """Produce 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.
- """
- return self._from_selectable(
- expression.union_all(*([self]+ list(q)))
- )
- def intersect(self, *q):
- """Produce 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.
- """
- return self._from_selectable(
- expression.intersect(*([self]+ list(q)))
- )
- def intersect_all(self, *q):
- """Produce 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.
- """
- return self._from_selectable(
- expression.intersect_all(*([self]+ list(q)))
- )
- def except_(self, *q):
- """Produce 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.
- """
- return self._from_selectable(
- expression.except_(*([self]+ list(q)))
- )
- def except_all(self, *q):
- """Produce 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.
- """
- return self._from_selectable(
- expression.except_all(*([self]+ list(q)))
- )
- @util.accepts_a_list_as_starargs(list_deprecation='pending')
- def join(self, *props, **kwargs):
- """Create a join against this ``Query`` object's criterion
- and apply generatively, returning the newly resulting ``Query``.
- Each element in \*props may be:
- * a string property name, i.e. "rooms". This will join along the
- relation of the same name from this Query's "primary" mapper, if
- one is present.
- * a class-mapped attribute, i.e. Houses.rooms. This will create a
- join from "Houses" table to that of the "rooms" relation.
- * a 2-tuple containing a target class or selectable, and an "ON"
- clause. The ON clause can be the property name/ attribute like
- above, or a SQL expression.
- e.g.::
- # join along string attribute names
- session.query(Company).join('employees')
- session.query(Company).join('employees', 'tasks')
- # join the Person entity to an alias of itself,
- # along the "friends" relation
- PAlias = aliased(Person)
- session.query(Person).join((Palias, Person.friends))
- # join from Houses to the "rooms" attribute on the
- # "Colonials" subclass of Houses, then join to the
- # "closets" relation on Room
- session.query(Houses).join(Colonials.rooms, Room.closets)
- # join from Company entities to the "employees" collection,
- # using "people JOIN engineers" as the target. Then join
- # to the "computers" collection on the Engineer entity.
- session.query(Company).join((people.join(engineers), 'employees'), Engineer.computers)
- # join from Articles to Keywords, using the "keywords" attribute.
- # assume this is a many-to-many relation.
- session.query(Article).join(Article.keywords)
- # same thing, but spelled out entirely explicitly
- # including the association table.
- session.query(Article).join(
- (article_keywords, Articles.id==article_keywords.c.article_id),
- (Keyword, Keyword.id==article_keywords.c.keyword_id)
- )
- \**kwargs include:
- aliased - when joining, create anonymous aliases of each table. This is
- used for self-referential joins or multiple joins to the same table.
- Consider usage of the aliased(SomeClass) construct as a more explicit
- approach to this.
- from_joinpoint - when joins are specified using string property names,
- locate the property from the mapper found in the most recent previous
- join() call, instead of from the root entity.
- """
- aliased, from_joinpoint = kwargs.pop('aliased', False), kwargs.pop('from_joinpoint', False)
- if kwargs:
- raise TypeError("unknown arguments: %s" % ','.join(kwargs.iterkeys()))
- return self._join(props, outerjoin=False, create_aliases=aliased, from_joinpoint=from_joinpoint)
- @util.accepts_a_list_as_starargs(list_deprecation='pending')
- def outerjoin(self, *props, **kwargs):
- """Create a left outer join against this ``Query`` object's criterion
- and apply generatively, retunring the newly resulting ``Query``.
- Usage is the same as the ``join()`` method.
- """
- aliased, from_joinpoint = kwargs.pop('aliased', False), kwargs.pop('from_joinpoint', False)
- if kwargs:
- raise TypeError("unknown arguments: %s" % ','.join(kwargs.iterkeys()))
- return self._join(props, outerjoin=True, create_aliases=aliased, from_joinpoint=from_joinpoint)
- @_generative(_no_statement_condition, _no_limit_offset)
- def _join(self, keys, outerjoin, create_aliases, from_joinpoint):
- # copy collections that may mutate so they do not affect
- # the copied-from query.
- self._currenttables = set(self._currenttables)
- self._polymorphic_adapters = self._polymorphic_adapters.copy()
- # start from the beginning unless from_joinpoint is set.
- if not from_joinpoint:
- self._reset_joinpoint()
- clause = replace_clause_index = None
-
- # after the method completes,
- # the query's joinpoint will be set to this.
- right_entity = None
-
- for arg1 in util.to_list(keys):
- aliased_entity = False
- alias_criterion = False
- left_entity = right_entity
- prop = of_type = right_entity = right_mapper = None
- # distinguish between tuples, scalar args
- if isinstance(arg1, tuple):
- arg1, arg2 = arg1
- else:
- arg2 = None
- # determine onclause/right_entity. there
- # is a little bit of legacy behavior still at work here
- # which means they might be in either order. may possibly
- # lock this down to (right_entity, onclause) in 0.6.
- if isinstance(arg2, (interfaces.PropComparator, basestring)):
- onclause = arg2
- right_entity = arg1
- elif isinstance(arg1, (interfaces.PropComparator, basestring)):
- onclause = arg1
- right_entity = arg2
- else:
- onclause = arg2
- right_entity = arg1
- # extract info from the onclause argument, determine
- # left_entity and right_entity.
- if isinstance(onclause, interfaces.PropComparator):
- of_type = getattr(onclause, '_of_type', None)
- prop = onclause.property
- descriptor = onclause
- if not left_entity:
- left_entity = onclause.parententity
- if of_type:
- right_mapper = of_type
- else:
- right_mapper = prop.mapper
- if not right_entity:
- right_entity = right_mapper
- elif isinstance(onclause, basestring):
- if not left_entity:
- left_entity = self._joinpoint_zero()
- descriptor, prop = _entity_descriptor(left_entity, onclause)
- right_mapper = prop.mapper
- if not right_entity:
- right_entity = right_mapper
- elif not left_entity:
- left_entity = self._joinpoint_zero()
- if not clause and self._from_obj:
- mp, left_selectable, is_aliased_class = _entity_info(left_entity)
- replace_clause_index, clause = sql_util.find_join_source(self._from_obj, left_selectable)
- if not clause:
- clause = left_selectable
-
- if not clause and left_entity:
- for ent in self._entities:
- if ent.corresponds_to(left_entity):
- clause = ent.selectable
- break
- # TODO:
- # this provides one kind of "backwards join"
- # tested in test/orm/query.py.
- # removal of this has been considered, but maybe not
- # see [ticket:1445]
- if not clause:
- if isinstance(onclause, interfaces.PropComparator):
- clause = onclause.__clause_element__()
- if not clause:
- raise sa_exc.InvalidRequestError("Could not find a FROM clause to join from")
- # if we have a MapperProperty and the onclause is not already
- # an instrumented descriptor. this catches of_type()
- # PropComparators and string-based on clauses.
- if prop and not isinstance(onclause, attributes.QueryableAttribute):
- onclause = prop
- # start looking at the right side of the join
- mp, right_selectable, is_aliased_class = _entity_info(right_entity)
- if mp is not None and right_mapper is not None and not mp.common_parent(right_mapper):
- raise sa_exc.InvalidRequestError(
- "Join target %s does not correspond to the right side of join condition %s" % (right_entity, onclause)
- )
- if not right_mapper and mp:
- right_mapper = mp
- # determine if we need to wrap the right hand side in an alias.
- # this occurs based on the create_aliases flag, or if the target
- # is a selectable, Join, or polymorphically-loading mapper
- if right_mapper and not is_aliased_class:
- if right_entity is right_selectable:
- if not right_selectable.is_derived_from(right_mapper.mapped_table):
- raise sa_exc.InvalidRequestError(
- "Selectable '%s' is not derived from '%s'" %
- (right_selectable.description, right_mapper.mapped_table.description))
- if not isinstance(right_selectable, expression.Alias):
- right_selectable = right_selectable.alias()
- right_entity = aliased(right_mapper, right_selectable)
- alias_criterion = True
- elif create_aliases:
- right_entity = aliased(right_mapper)
- alias_criterion = True
- elif right_mapper.with_polymorphic or isinstance(right_mapper.mapped_table, expression.Join):
- right_entity = aliased(right_mapper)
- alias_criterion = True
- aliased_entity = True
- elif prop:
- # for joins across plain relation()s, try not to specify the
- # same joins twice. the _currenttables collection tracks
- # what plain mapped tables we've joined to already.
- if prop.table in self._currenttables:
- if prop.secondary is not None and prop.secondary not in self._currenttables:
- # TODO: this check is not strong enough for different paths to the same endpoint which
- # does not use secondary tables
- raise sa_exc.InvalidRequestError("Can't join to property '%s'; a path to this "
- "table along a different secondary table already "
- "exists. Use the `alias=True` argument to `join()`." % descriptor)
- continue
- if prop.secondary:
- self._currenttables.add(prop.secondary)
- self._currenttables.add(prop.table)
- if of_type:
- right_entity = of_type
- else:
- right_entity = prop.mapper
- # create adapters to the right side, if we've created aliases
- if alias_criterion:
- right_adapter = ORMAdapter(right_entity,
- equivalents=right_mapper._equivalent_columns, chain_to=self._filter_aliases)
- # if the onclause is a ClauseElement, adapt it with our right
- # adapter, then with our query-wide adaptation if any.
- if isinstance(onclause, expression.ClauseElement):
- if alias_criterion:
- onclause = right_adapter.traverse(onclause)
- onclause = self._adapt_clause(onclause, False, True)
- # determine if we want _ORMJoin to alias the onclause
- # to the given left side. This is used if we're joining against a
- # select_from() selectable, from_self() call, or the onclause
- # has been resolved into a MapperProperty. Otherwise we assume
- # the onclause itself contains more specific information on how to
- # construct the onclause.
- join_to_left = not is_aliased_class or \
- onclause is prop or \
- self._from_obj_alias and clause is self._from_obj[0]
- # create the join
- clause = orm_join(clause, right_entity, onclause, isouter=outerjoin, join_to_left=join_to_left)
- # set up state for the query as a whole
- if alias_criterion:
- # adapt filter() calls based on our right side adaptation
- self._filter_aliases = right_adapter
- # if a polymorphic entity was aliased, establish that
- # so that MapperEntity/ColumnEntity can pick up on it
- # and adapt when it renders columns and fetches them from results
- if aliased_entity:
- self.__mapper_loads_polymorphically_with(
- right_mapper,
- ORMAdapter(right_entity, equivalents=right_mapper._equivalent_columns)
- )
- if replace_clause_index is not None:
- l = list(self._from_obj)
- l[replace_clause_index] = clause
- self._from_obj = tuple(l)
- else:
- self._from_obj = self._from_obj + (clause,)
- # future joins with from_joinpoint=True join from our established right_entity.
- self._joinpoint = right_entity
- @_generative(_no_statement_condition)
- def reset_joinpoint(self):
- """return a new Query reset the 'joinpoint' of this Query reset
- back to the starting mapper. Subsequent generative calls will
- be constructed from the new joinpoint.
- Note that each call to join() or outerjoin() also starts from
- the root.
- """
- self._reset_joinpoint()
- @_generative(_no_clauseelement_condition)
- def select_from(self, from_obj):
- """Set the `from_obj` parameter of the query and return the newly
- resulting ``Query``. This replaces the table which this Query selects
- from with the given table.
- `from_obj` is a single table or selectable.
- """
-
- if isinstance(from_obj, (tuple, list)):
- # from_obj is actually a list again as of 0.5.3. so this restriction here
- # is somewhat artificial, but is still in place since select_from() implies aliasing all further
- # criterion against what's placed here, and its less complex to only
- # keep track of a single aliased FROM element being selected against. This could in theory be opened
- # up again to more complexity.
- util.warn_deprecated("select_from() now accepts a single Selectable as its argument, which replaces any existing FROM criterion.")
- from_obj = from_obj[-1]
- if not isinstance(from_obj, expression.FromClause):
- raise sa_exc.ArgumentError("select_from() accepts FromClause objects only.")
- self._set_select_from(from_obj)
- def __getitem__(self, item):
- if isinstance(item, slice):
- start, stop, step = util.decode_slice(item)
- if isinstance(stop, int) and isinstance(start, int) and stop - start <= 0:
- return []
- # perhaps we should execute a count() here so that we
- # can still use LIMIT/OFFSET ?
- elif (isinstance(start, int) and start < 0) \
- or (isinstance(stop, int) and stop < 0):
- return list(self)[item]
- res = self.slice(start, stop)
- if step is not None:
- return list(res)[None:None:item.step]
- else:
- return list(res)
- else:
- return list(self[item:item+1])[0]
- @_generative(_no_statement_condition)
- def slice(self, start, stop):
- """apply LIMIT/OFFSET to the ``Query`` based on a range and return the newly resulting ``Query``."""
- if start is not None and stop is not None:
- self._offset = (self._offset or 0) + start
- self._limit = stop - start
- elif start is None and stop is not None:
- self._limit = stop
- elif start is not None and stop is None:
- self._offset = (self._offset or 0) + start
- @_generative(_no_statement_condition)
- def limit(self, limit):
- """Apply a ``LIMIT`` to the query and return the newly resulting
- ``Query``.
- """
- self._limit = limit
- @_generative(_no_statement_condition)
- def offset(self, offset):
- """Apply an ``OFFSET`` to the query and return the newly resulting
- ``Query``.
- """
- self._offset = offset
- @_generative(_no_statement_condition)
- def distinct(self):
- """Apply a ``DISTINCT`` to the query and return the newly resulting
- ``Query``.
- """
- self._distinct = True
- def all(self):
- """Return the results represented by this ``Query`` as a list.
- This results in an execution of the underlying query.
- """
- return list(self)
- @_generative(_no_clauseelement_condition)
- def from_statement(self, statement):
- """Execute the given SELECT statement and return results.
- This method bypasses all internal statement compilation, and the
- statement is executed without modification.
- The statement argument is either a string, a ``select()`` construct,
- or a ``text()`` construct, and should return the set of columns
- appropriate to the entity class represented by this ``Query``.
- Also see the ``instances()`` method.
- """
- if isinstance(statement, basestring):
- statement = sql.text(statement)
- if not isinstance(statement, (expression._TextClause, expression._SelectBaseMixin)):
- raise sa_exc.ArgumentError("from_statement accepts text(), select(), and union() objects only.")
- self._s…
Large files files are truncated, but you can click here to view the full file