From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Thu, 2 Nov 2017 17:53:34 +0000 (-0400)
Subject: Add doc note for contains_eager() w/ subclasses.
X-Git-Tag: rel_1_1_15~2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4e4642d5d8c41bee01b55bd8393132a380f70ec9;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Add doc note for contains_eager() w/ subclasses.

Change-Id: I9634136e1855a081c25b04bb6ae8248f0f94be1c
Fixes: #4130
(cherry picked from commit 152522b3f28de290d9ea2903fa2c414b8579515a)
---

diff --git a/lib/sqlalchemy/orm/strategy_options.py b/lib/sqlalchemy/orm/strategy_options.py
index 079f0d6e60..4e3f1e767e 100644
--- a/lib/sqlalchemy/orm/strategy_options.py
+++ b/lib/sqlalchemy/orm/strategy_options.py
@@ -546,7 +546,7 @@ def contains_eager(loadopt, attr, alias=None):
     ``User`` entity, and the returned ``Order`` objects would have the
     ``Order.user`` attribute pre-populated.
 
-    :func:`contains_eager` also accepts an `alias` argument, which is the
+    :func:`.contains_eager` also accepts an `alias` argument, which is the
     string name of an alias, an :func:`~sqlalchemy.sql.expression.alias`
     construct, or an :func:`~sqlalchemy.orm.aliased` construct. Use this when
     the eagerly-loaded rows are to come from an aliased table::
@@ -556,6 +556,18 @@ def contains_eager(loadopt, attr, alias=None):
                 join((user_alias, Order.user)).\
                 options(contains_eager(Order.user, alias=user_alias))
 
+    When using :func:`.contains_eager` in conjunction with inherited
+    subclasses, the :meth:`.RelationshipProperty.of_type` modifier should
+    also be used in order to set up the pathing properly::
+
+        sess.query(Company).\
+            outerjoin(Company.employees.of_type(Manager)).\
+            options(
+                contains_eager(
+                    Company.employees.of_type(Manager),
+                    alias=Manager)
+            )
+
     .. seealso::
 
         :ref:`loading_toplevel`