as a result of the bugfix for :ticket:`3167`,
where attribute and validation events are no longer
called within the flush process.  The mutable
extension was relying upon this behavior in the case where a column
level Python-side default were responsible for generating the new value
on INSERT or UPDATE, or when a value were fetched from the RETURNING
clause for "eager defaults" mode.  The new value would not be subject
to any event when populated and the mutable extension could not
establish proper coercion or history listening.  A new event
:meth:`.InstanceEvents.refresh_flush` is added which the mutable
extension now makes use of for this use case.
fixes #3427
- Added new event :meth:`.InstanceEvents.refresh_flush`, invoked
when an INSERT or UPDATE level default value fetched via RETURNING
or Python-side default is invoked within the flush process.  This
is to provide a hook that is no longer present as a result of
:ticket:`3167`, where attribute and validation events are no longer
called within the flush process.
- Added a new semi-public method to :class:`.MutableBase`
:meth:`.MutableBase._get_listen_keys`.  Overriding this method
is needed in the case where a :class:`.MutableBase` subclass needs
events to propagate for attribute keys other than the key to which
the mutable type is associated with, when intercepting the
:meth:`.InstanceEvents.refresh` or
:meth:`.InstanceEvents.refresh_flush` events.  The current example of
this is composites using :class:`.MutableComposite`.

event where its invocation was moved to be after the class manager's
instrumentation of the class, which is the opposite of what the
documentation for the event explicitly states.  The rationale for the
switch was due to Declarative taking the step of setting up
the full "instrumentation manager" for a class before it was mapped
for the purpose of the new ``@declared_attr`` features
described in :ref:`feature_3150`, but the change was also made
against the classical use of :func:`.mapper` for consistency.
However, SQLSoup relies upon the instrumentation event happening
before any instrumentation under classical mapping.
The behavior is reverted in the case of classical and declarative
mapping, the latter implemented by using a simple memoization
without using class manager.
fixes #3388

changes made to the :class:`.Query` object's collection of entities
to load within the event would render in the SQL, but would not
be reflected during the loading process.
fixes #3387

: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.
fixes #3317

as that of :ticket:`3199`, when the ``named=True`` parameter
would be used.  Some events would fail to register, and others
would not invoke the event arguments correctly, generally in the
case of when an event was "wrapped" for adaption in some other way.
The "named" mechanics have been rearranged to not interfere with
the argument signature expected by internal wrapper functions.
fixes #3197

if a load() or refresh() event changes history (which...why...but anyway)
the state of the object is the same; currently it seems that history
gets reset but on a refresh, the object still goes into session.dirty
- simplify what we store in partials

any speed improvements :(.   code is in a much better place to be run into
C, however
- The ``proc()`` callable passed to the ``create_row_processor()``
method of custom :class:`.Bundle` classes now accepts only a single
"row" argument.
- Deprecated event hooks removed:  ``populate_instance``,
``create_instance``, ``translate_row``, ``append_result``
- the getter() idea is somewhat restored; see ref #3175

mapper is implicitly combining one of its column-based attributes
with that of the parent, where those columns normally don't necessarily
share the same value.  This is an extension of an existing check that
was added via :ticket:`1892`; however this new check emits only a
warning, instead of an exception, to allow for applications that may
be relying upon the existing behavior.
fixes #3042

flag for :func:`.event.listen` to work with mapper / instance events.