series as well. For changes that are specific to 1.0 with an emphasis
on compatibility concerns, see :doc:`/changelog/migration_10`.
+ .. change::
+ :tags: feature, orm
+ :tickets: 3317
+
+ Added a new event suite :class:`.QueryEvents`. The
+ :meth:`.QueryEvents.before_compile` event allows the creation
+ of functions which may place additional modifications to
+ :class:`.Query` objects before the construction of the SELECT
+ statement. It is hoped that this event be made much more
+ useful via the advent of a new inspection system that will
+ allow for detailed modifications to be made against
+ :class:`.Query` objects in an automated fashion.
+
+ .. seealso::
+
+ :class:`.QueryEvents`
+
+
.. change::
:tags: feature, orm
:tickets: 3249
The event supersedes the previous system of "extension" classes.
For an introduction to the event API, see :ref:`event_toplevel`. Non-ORM events
-such as those regarding connections and low-level statement execution are described in
+such as those regarding connections and low-level statement execution are described in
:ref:`core_event_toplevel`.
Attribute Events
.. autoclass:: sqlalchemy.orm.events.SessionEvents
:members:
+Query Events
+-------------
+
+.. autoclass:: sqlalchemy.orm.events.QueryEvents
+ :members:
+
Instrumentation Events
-----------------------
from .session import Session, sessionmaker
from .scoping import scoped_session
from .attributes import QueryableAttribute
-
+from .query import Query
class InstrumentationEvents(event.Events):
"""Events related to class instrumentation events.
the :class:`.collection.linker` hook.
"""
+
+
+class QueryEvents(event.Events):
+ """Represent events within the construction of a :class:`.Query` object.
+
+ The events here are intended to be used with an as-yet-unreleased
+ inspection system for :class:`.Query`. Some very basic operations
+ are possible now, however the inspection system is intended to allow
+ complex query manipulations to be automated.
+
+ .. versionadded:: 1.0.0
+
+ """
+
+ _target_class_doc = "SomeQuery"
+ _dispatch_target = Query
+
+ def before_compile(self, query):
+ """Receive the :class:`.Query` object before it is composed into a
+ core :class:`.Select` object.
+
+ This event is intended to allow changes to the query given::
+
+ @event.listens_for(Query, "before_compile", retval=True)
+ def no_deleted(query):
+ for desc in query.column_descriptions:
+ if desc['type'] is User:
+ entity = desc['expr']
+ query = query.filter(entity.deleted == False)
+ return query
+
+ The event should normally be listened with the ``retval=True``
+ parameter set, so that the modified query may be returned.
+
+
+ """
+
+ @classmethod
+ def _listen(
+ cls, event_key, retval=False, **kw):
+ fn = event_key._listen_fn
+
+ if not retval:
+ def wrap(*arg, **kw):
+ if not retval:
+ query = arg[0]
+ fn(*arg, **kw)
+ return query
+ else:
+ return fn(*arg, **kw)
+ event_key = event_key.with_wrapper(wrap)
+
+ event_key.base_listen(**kw)
return update_op.rowcount
def _compile_context(self, labels=True):
+ if self.dispatch.before_compile:
+ for fn in self.dispatch.before_compile:
+ new_query = fn(self)
+ if new_query is not None:
+ self = new_query
+
context = QueryContext(self)
if context.statement is not None:
# "load from explicit FROMs" mode,
# i.e. when select_from() or join() is used
context.froms = list(context.from_clause)
- else:
- # "load from discrete FROMs" mode,
- # i.e. when each _MappedEntity has its own FROM
- context.froms = context.froms
+ # else "load from discrete FROMs" mode,
+ # i.e. when each _MappedEntity has its own FROM
if self._enable_single_crit:
self._adjust_for_single_inheritance(context)
context.statement = self._compound_eager_statement(context)
else:
context.statement = self._simple_statement(context)
+
return context
def _compound_eager_statement(self, context):
from sqlalchemy.testing.schema import Table, Column
from sqlalchemy.orm import mapper, relationship, \
create_session, class_mapper, \
- Mapper, column_property, \
+ Mapper, column_property, query, \
Session, sessionmaker, attributes, configure_mappers
from sqlalchemy.orm.instrumentation import ClassManager
from sqlalchemy.orm import instrumentation, events
from sqlalchemy.testing import eq_
from sqlalchemy.testing import fixtures
+from sqlalchemy.testing import AssertsCompiledSQL
from sqlalchemy.testing.util import gc_collect
from test.orm import _fixtures
from sqlalchemy import event
events.InstanceEvents._clear()
events.SessionEvents._clear()
events.InstrumentationEvents._clear()
+ events.QueryEvents._clear()
super(_RemoveListeners, self).teardown()
assert not s.dispatch.after_commit
assert len(s.dispatch.before_commit) == 1
+
+class QueryEventsTest(
+ _RemoveListeners, _fixtures.FixtureTest, AssertsCompiledSQL):
+ run_inserts = None
+ __dialect__ = 'default'
+
+ @classmethod
+ def setup_mappers(cls):
+ User = cls.classes.User
+ users = cls.tables.users
+
+ mapper(User, users)
+
+ def test_before_compile(self):
+ @event.listens_for(query.Query, "before_compile", retval=True)
+ def no_deleted(query):
+ for desc in query.column_descriptions:
+ if desc['type'] is User:
+ entity = desc['expr']
+ query = query.filter(entity.id != 10)
+ return query
+
+ User = self.classes.User
+ s = Session()
+
+ q = s.query(User).filter_by(id=7)
+ self.assert_compile(
+ q,
+ "SELECT users.id AS users_id, users.name AS users_name "
+ "FROM users "
+ "WHERE users.id = :id_1 AND users.id != :id_2",
+ checkparams={'id_2': 10, 'id_1': 7}
+ )
+
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
