[Sqlalchemy-tickets] Issue #3563: Improve docs for `contains_eager` (zzzeek/sqlalchemy)

[Ian M. <iss...@bi...>]

New issue 3563: Improve docs for `contains_eager`
https://bitbucket.org/zzzeek/sqlalchemy/issues/3563/improve-docs-for-contains_eager

Ian McCullough:

It took me a *really* long time to discover, and then figure out how to use `contains_eager` for the use case of:

> Load entity A (which has a to-many relationship to B) populating its list of Bs with the subset of related Bs that meet a certain filter criteria.

The existing docs for `contains_eager` don't express well its applicability for this goal, and neither of the examples show any filtering. The closest they come is:

> The above query would join from the Order entity to its related User entity, and the returned Order objects would have the Order.user attribute pre-populated.

It took me a long time to figure out how this was different from `joinedload` and to understand that it could filter relationship collections. Even just a trivial example that showed a trivial filter on the related entity would go a long way. Thanks!