- add class_ to AliasedInsp

- redefine inspect(Class.attrname).parent to be always an inspectable
target; either Mapper or AliasedInsp
- add most major features to 08 migration, document, link

5 files changed, 46 insertions, 16 deletions

diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 7effd8e58..983b4dfec 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -158,9 +158,17 @@ class QueryableAttribute(interfaces._MappedAttribute,
         # TODO: conditionally attach this method based on clause_element ?
         return self
 
-    @property
+    @util.memoized_property
     def parent(self):
-        return self._parententity
+        """Return an inspection instance representing the parent.
+
+        This will be either an instance of :class:`.Mapper`
+        or :class:`.AliasedInsp`, depending upon the nature
+        of the parent entity which this attribute is associated
+        with.
+
+        """
+        return inspection.inspect(self._parententity)
 
     @property
     def expression(self):
@@ -208,6 +216,15 @@ class QueryableAttribute(interfaces._MappedAttribute,
 
     @util.memoized_property
     def property(self):
+        """Return the :class:`.MapperProperty` associated with this
+        :class:`.QueryableAttribute`.
+
+
+        Return values here will commonly be instances of
+        :class:`.ColumnProperty` or :class:`.RelationshipProperty`.
+
+
+        """
         return self.comparator.property
 
 inspection._self_inspects(QueryableAttribute)
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index a0abb2743..e2b5e94e0 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -386,20 +386,8 @@ class RelationshipProperty(StrategizedProperty):
             return self.property.mapper
 
         @util.memoized_property
-        def parent(self):
-            """The parent :class:`.Mapper` or :class:`.AliasedClass`
-            referred to by this
-            :class:`.RelationshipProperty.Comparator.
-
-            This is the "parent" or "local" side of the
-            :func:`.relationship`.
-
-            """
-            return self.property.parent
-
-        @util.memoized_property
         def _parententity(self):
-            return self.parent
+            return self.property.parent
 
         def _source_selectable(self):
             elem = self.property.parent._with_polymorphic_selectable
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 02fb7d4f7..9289c01e1 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1751,7 +1751,6 @@ class Query(object):
                         right_entity = onclause.property.mapper
 
                 left_entity = onclause._parententity
-                assert left_entity is onclause.parent
 
                 prop = onclause.property
                 if not isinstance(onclause,  attributes.QueryableAttribute):
diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py
index fb4197c58..cf3238b15 100644
--- a/lib/sqlalchemy/orm/util.py
+++ b/lib/sqlalchemy/orm/util.py
@@ -581,11 +581,20 @@ class AliasedInsp(_InspectionAttr, AliasedInsp):
     * ``polymorphic_on`` - an alternate column or SQL expression which
       will be used as the "discriminator" for a polymorphic load.
 
+    .. seealso::
+
+        :ref:`inspection_toplevel`
+
     """
 
     is_aliased_class = True
     "always returns True"
 
+    @property
+    def class_(self):
+        """Return the mapped class ultimately represented by this
+        :class:`.AliasedInsp`."""
+        return self.mapper.class_
 
 inspection._inspects(AliasedClass)(lambda target: target._aliased_insp)
 
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index 1681b26f4..84fe9a82e 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -5535,6 +5535,12 @@ class Select(HasPrefixes, SelectBase):
         If the fromclause is None, correlation is disabled for the returned
         select().
 
+        .. seealso::
+
+            :meth:`.Select.correlate_except`
+
+            :ref:`correlated_subqueries`
+
         """
         self._should_correlate = False
         if fromclauses and fromclauses[0] is None:
@@ -5545,6 +5551,17 @@ class Select(HasPrefixes, SelectBase):
 
     @_generative
     def correlate_except(self, *fromclauses):
+        """"Return a new select() construct which will auto-correlate
+        on FROM clauses of enclosing selectables, except for those FROM
+        clauses specified here.
+
+        .. seealso::
+
+            :meth:`.Select.correlate`
+
+            :ref:`correlated_subqueries`
+
+        """
         self._should_correlate = False
         if fromclauses and fromclauses[0] is None:
             self._correlate_except = ()