loading documentation

Change-Id: I3ce7e2cc521c4dd155195819a919017d4cc63b3c

Pull request courtesy Stefan Urbanek.  fixes #1957

versions 0.8.0 and 0.8.1, due :ticket:`2714`.  The case where
joined eager loading needs to join out over a subclass-bound
relationship when "with_polymorphic" were also used would fail
to join from the correct entity.
fixes #3593

unambiguous tracking of all object lifecycle state transitions
in terms of the :class:`.Session` itself, e.g. pending,
transient,  persistent, detached.   The state of the object
within each event is also defined.
fixes #2677
- Added a new session lifecycle state :term:`deleted`.  This new state
represents an object that has been deleted from the :term:`persistent`
state and will move to the :term:`detached` state once the transaction
is committed.  This resolves the long-standing issue that objects
which were deleted existed in a gray area between persistent and
detached.   The :attr:`.InstanceState.persistent` accessor will
**no longer** report on a deleted object as persistent; the
:attr:`.InstanceState.deleted` accessor will instead be True for
these objects, until they become detached.
- The :paramref:`.Session.weak_identity_map` parameter is deprecated.
See the new recipe at :ref:`session_referencing_behavior` for
an event-based approach to maintaining strong identity map behavior.
references #3517

mapped attribute on top of an :func:`.aliased` object would
resolve to the original mapper, not the :func:`.aliased`
version of it, thereby causing problems for a :class:`.Query`
that relies on this attribute (e.g. it's the only representative
attribute given in the constructor) to figure out the correct FROM
clause for the query.
fixes #3466
- apply consitency to ._parententity vs.
__clause_element__()._annotations['parententity']
in terms of aliased class, test it all.

joins of :ticket:`3222` takes place inappropriately
for a JOIN along explicit join criteria with a single-inheritance
subclass that does not make use of any discriminator, resulting
in an additional "AND NULL" clause.
fixes #3462

to protect against unknown conditions when splicing inner joins
together within joined eager loads with ``innerjoin=True``; if
some of the joins use a "secondary" table, the assertion needs to
unwrap further joins in order to pass.
fixes #3412

NEVER_SET symbol could easily leak into a lazyload query, subsequent
to the flush of a pending object.  This would occur typically
for a many-to-one relationship that does not use a simple
"get" strategy.   The good news is that the fix improves efficiency
vs. 0.9, because we can now skip the SELECT statement entirely
when we detect NEVER_SET symbols present in the parameters; prior to
:ticket:`3061`, we couldn't discern if the None here were set or not.
fixes #3368

between fully and match on those, rather than trying to
compare selectables; fixes #3347